Reverse engineering

Available in product edition: Professional

⚠Beta

Reverse engineering relies on the Modelling Support MCP server, which is in beta. Behaviour and prompts may change between releases. See Modelling Support MCP server for the current contract. It is recommended to review the outcome carefully.

What it is for

Reverse engineering helps you get a design starting point when you already have a codebase. It turns the current state of your code into K5 design elements and relationships so you can open the Solution Designer workbench with something to refine instead of an empty model. The same run can also create diagrams of that result when you ask for them.

The same capabilities can also bring an existing design back in line with the implementation. Use that when the first result was incomplete, or when the code has evolved and the design was not updated with it. See Align an existing design with the implementation.

Main use cases:

• Onboard an existing project into solution design without modelling everything by hand first.
• Compare an existing design with the current implementation and update the design so the two match again.

How it works

The flow is AI-assisted and driven through the Model Context Protocol (MCP):

1. Your coding assistant (with MCP enabled) can reach the Modelling Support MCP server, which exposes your K5 repository, element types, GraphQL, and mutations.
2. You run the guided MCP prompt generate-k5-design-from-code, which steers the model to inspect your repository, interpret structure and dependencies, confirm scope with you where needed, and create or update design elements and relationships via the server’s tools. After the model is written, the same prompt can create one or more diagrams of it.

For endpoint, authentication (including personal access tokens), and tool behaviour, use the full reference: Modelling Support MCP server.

After a design exists, you can also paste a chat message that asks the assistant to compare that design with the implementation and update it.

Supported coding assistants

The feature is intended to work with any coding assistant that can reach the Modelling Support MCP server and invoke its tools. A UI for MCP prompts is optional: if prompts are missing, paste the guided prompt from the section below.

It has been verified and work efficiently with the following coding assistants:

• GitHub Copilot
• IBM Bob
• Cursor IDE

❗️info

The result quality strongly depends on the selected coding assistant, the chosen AI model, and the structure and quality of the existing codebase. Insufficient design creation or other errors can occur when the selected model has no suitable context window size for the repository and prompt payload. In such cases, switch to a model with a larger context window and retry the workflow.

Steps to use the feature

1. Import the project into Solution Designer if it is not there already (same project you want to create a design for).

2. Create a new Git branch in Solution Designer for this design work. Reverse engineering will write into that branch’s design scope.

3. Clone that branch locally in your AI-enabled IDE so the assistant can read the same codebase you want reflected in the model.

4. Create a personal access token in Solution Designer under User settings → Access tokens. Copy the token value when it is shown (it starts with k5pat_ and is displayed only once).

5. Configure MCP in the IDE: add the Modelling Support MCP server and authenticate with your personal access token via the K5-Access-Token header. Example for Cursor (.cursor/mcp.json):

   {
     "mcpServers": {
       "k5-workbench": {
         "url": "https://workbench.mycompany.com/diagram/mcp",
         "headers": {
           "K5-Access-Token": "k5pat_<your-token>"
         }
       }
     }
   }

   Replace the URL with your deployment’s MCP endpoint (see Endpoint) and the placeholder with your token. Other auth options (OAuth client or static JWT) are described under Authentication.

6. Start the reverse-engineering workflow in one of two ways:

   • If your coding assistant supports MCP prompts: Run the server prompt generate-k5-design-from-code from your assistant and follow the instructions in the prompt chat. The exact invocation depends on the coding assistant; in assistants such as GitHub Copilot and Cursor, you can type /<mcp-server-name>/generate-k5-design-from-code directly into the chat input field, where <mcp-server-name> is the name you gave the Modelling Support MCP server in your configuration.
   • If your coding assistant does not support MCP prompts: Some assistants can use the Modelling Support server for tools only and do not let you pick server-defined prompts from the UI. In that case, keep MCP configured so the assistant can still call the modelling tools, and paste the guided prompt into the chat yourself. Use the block under Prompt to paste below.

7. After triggering the reverse-engineering workflow, carefully review the responses within your Chat window. The coding assistant will ask you various times to clarify or confirm things, in order to make sure the design meets your expectation.

8. After successful running the prompt, switch back to the Solution Designer and revisit the created design.

💡Reduce tool-call confirmations

The reverse-engineering workflow invokes multiple MCP tools in sequence. Depending on your coding assistant, each call may require manual confirmation, which can slow down the run noticeably. If your assistant supports an allowlist (or auto-approve list) for MCP tools, consider adding the Modelling Support MCP server tools to it before starting the workflow. This lets the assistant call the tools without prompting you every time while still keeping other tools gated.

❗️info

After the workflow, the generated design is only present in the branch within the Solution Designer. To continue working with it, make sure you commit and push the changes through the Solution Designer.

Prompt to paste (when MCP prompts are unavailable)

When your coding assistant does not support integration of MCP prompts, and therefore you cannot trigger generate-k5-design-from-code from the UI, please directly copy the below prompt into your coding assistant:

You are an assistant that creates a k5 design based on the current implementation. The design is meant to represent the core aspects of the code so that it can be used for communication, alignment and to provide structured insights.
The design has to match a special design format, which is described by a list of element types that represent the building blocks of the design and the possible relationships between them.
Whenever an acronym and branch is required in the MCP tools, read the project acronym from the k5-project.yml and use the local git branch as branch.
IMPORTANT NOTE: NEVER trigger multiple GraphQL mutation tool calls in parallel. ALWAYS execute these one by one to avoid concurrent modification problems. However, feel free to combine multiple element creations into one single GraphQL mutation operation call wherever possible.
Follow the steps to create the k5 design:

0. Use MCP tool "list-k5-element-types" to retrieve all available types of elements that could represent the desired design. After that, ask me to choose a design approach or some dedicated element from the list, which will be used to guide the design generation. After I answer, use that guidance for the rest of the flow.

1. Iterate over the retrieved list and only keep the element types that fit the design approach I confirmed. Let me confirm that the found list is appropriate before continuing with the next step.

2. For each of the identified k5 element types separately (NEVER do one call for all element types together), call MCP tool "get-k5-element-types-details" with the respective element type provided. Keep this to understand the available properties of each element type, which need to be filled with proper values from the code later on.

3. Before you analyze or read the implementation: ask me which part of the codebase should be considered (for example specific paths, modules, layers, services, or the whole repository). Do not start understanding the code until I have confirmed the scope.

4. Understand the code that is implemented, strictly within the code scope I confirmed.

5. Resolve k5 design elements from the code scope while considering the following rules:
* consider available properties for each element type resolved in step 2
* Fill as many element properties as possible with retrieved details from the code
Let me confirm that the identified design is appropriate before continuing with the next step.

6. For each element type that is part of the design, use the MCP tool "get-partial-k5-graphql-schema" with operation type "mutation" and item type "elements" (ALWAYS pass operationTypes: ["mutation"] and itemTypes: ["elements"]) to read the GraphQL Schema to use it for mutating the concrete element instances.

7. For each element to create, resolve a valid GraphQL mutation input while following the following rules:
* Ensure, that it is compliant with the retrieved graphql schema for the element type
* Properties of type elementReference are references to other elements and properties of type elementReferenceSelection are references to other elements or static values. If the element type that is referenced is a composite-part, the creation of it has to be made inline through the parent element. If another default model element is referenced, the default model element has to be created first and then the reference has to be created.
* Group / bundle creation of multiple element types together in one graphql mutation operation call wherever possible.
Perform the GraphQL mutations sequentially by using another MCP tool called "mutate-k5-element-instance". Make sure, you always do one after the other to avoid that we get problems with concurrent modifications.

8. After successfully creating the element instances, ask me whether I want to continue with creating relationships between the elements. If yes, continue with the next steps. If no, you may still continue with the optional diagram-creation flow afterwards based on the created elements:
8a) First, for each element type that is part of the design, use the MCP tool "get-allowed-k5-relationships" (with acronym and branch as in other tools) to retrieve the allowed relationships for that element type. Only relationship types returned by this tool may be created—do not create any relationship that is not in the allowed list. Also consider the allowed destination element types for each relationship type.
8b) Based on these allowed relationships, resolve a valid relationship design for the current codebase. Let me confirm the found list.
8c) Then, use the MCP tool "get-partial-k5-graphql-schema" with operation type "mutation" and item type "relationships" (ALWAYS pass operationTypes: ["mutation"] and itemTypes: ["relationships"]) to read the GraphQL Schema for creating relationships.
8d) Based on the retrieved graphql schema, resolve a valid graphql mutation input for each allowed relationship / connection to create. Ensure that for sourceIdentifier and destinationIdentifier, the uuid of the respective element is used.
8e) Perform the GraphQL mutation by using the MCP tool called "mutate-k5-element-instance" (also one after the other to avoid concurrent modification problems).
9. After the actual model elements and relationships have been created, ask me whether I want to create one or more diagrams to visualize the design. Do not create any diagram automatically without asking first.
10. If I want a diagram, ask what should be visualized. Always offer at least these options: one diagram containing all newly created elements and all newly created relationships, one or more meaningful suggested scopes derived from the created design, a custom scope defined by me. When suggesting meaningful scopes, derive them from the actual created design and code structure. Prefer suggestions such as:
* per bounded context / domain area
* per service / module / component
* per API surface and its related handlers / operations
* per aggregate / entity cluster
* per integration or dependency view between major elements.
Only suggest scopes that match the created element types and relationships; do not invent views that are unsupported by the design.
11. Before creating the diagram, summarize the selected visualization scope and let me confirm it. If I choose a custom scope, help me define it in terms of the created model elements and relationships.
12. After I confirm the scope, create the diagram element using the available k5 / MCP tools for diagram creation. Choose a concise name and description that reflect the selected scope.
13. When preparing diagram content, use the following rules:
* Only use elements and relationships that were created or confirmed as part of the selected visualization scope.
* Keep the initial diagram focused and readable; prefer a coherent subset over an overloaded view.
* Treat the diagram as a designed picture: visual quality is a primary goal. The result must look clean, balanced, and easy to scan — not like randomly dropped boxes.
* Before adding any diagram content, choose a layout that fits the selected scope and the in-scope relationships, including their visible edge labels. For example, use a left-to-right flow, a top-down hierarchy, or clustered groups by domain, service, or layer.
* Plan node placement with the relationships/edges in mind, not in isolation. Anticipate edge routing, edge density, and the space needed for relationship labels so that the final picture remains readable.
* Align related nodes and keep the overall composition balanced.
* Never place nodes on top of each other. Compute positions from each node's actual size, or from the default size of its visualization type, so that bounding boxes do not overlap.
* Leave well-suited space between nodes: enough gap that boxes, labels, and edges stay visually separated. Avoid both cramped clusters and large empty deserts.
* Use nested / expanded parent nodes when composition or aggregation relationships exist and when it makes sense to do so.
* When adding edges, choose sourceHandle and targetHandle based on the relative node positions so connectors take the shortest clean path, leave room for labels, and do not cross boxes unnecessarily.
* If some selected elements have no relevant relationships in scope, they may still be added as standalone nodes when that helps explain the design.
14. After creating the diagram, prepare a concrete layout plan for the confirmed scope based on the rules above. Choose explicit x/y positions for all nodes before placing them.
15. Add the selected elements as diagram nodes by using the available diagram MCP tools such as "add-nodes-to-diagram". Only add nodes for elements that are part of the confirmed scope, and place them according to the prepared layout plan.
16. After placing the nodes, add the relevant relationships as diagram edges by using the available diagram MCP tools such as "add-edges-to-diagram". Only add edges when both endpoint elements are already present on the diagram and when the relationship is part of the confirmed scope.
17. After the diagram content has been created, tell me what diagram or diagrams were created, what scope each diagram covers, and mention any notable exclusions due to the selected scope.

Flow during the run

Once you start generate-k5-design-from-code (or paste the equivalent prompt), the assistant follows a fixed sequence of MCP tool calls and code reading. The prompt tells the model to use your project acronym from k5-project.yml and your local Git branch name as branch whenever a tool requires them—so keep the repo you cloned on the branch you want modelled, and ensure that branch is checked out in Solution Designer as described in step 2.

Stages (what happens):

1. Discover possible element types — Calls list-k5-element-types and asks you to pick a design approach or a dedicated element to guide the rest of the run.
2. Constrain to relevant element types — Filters the element types to match your guidance, then asks you to confirm the final element-type shortlist.
3. Fetch per-type details — Calls get-k5-element-types-details for each selected element type (one call per type) so it can use valid properties and shapes.
4. Confirm code scope — Asks you which repository scope to analyze (paths/modules/services/whole repo) and waits for your confirmation before reading code.
5. Understand the implementation — Reads and interprets only the confirmed code scope.
6. Propose elements — Maps code to K5 elements and fills as many properties as the code supports, then asks you to confirm the proposed design before mutating anything.
7. Persist elements — Loads get-partial-k5-graphql-schema (mutations, elements) and performs sequential mutate-k5-element-instance calls. Several creations can be bundled into one mutation; the mutation calls themselves still run one after another. A referenced composite part is created inline on its parent. A referenced default model element is created first, then linked. An elementReferenceSelection may point at another element or a static value.
8. Optional relationships — Asks whether to continue with relationships. If you agree, it loads allowed relationship types (get-allowed-k5-relationships), proposes a relationship set that respects allowed relationship types and destination element types, asks you to confirm, then uses get-partial-k5-graphql-schema (mutations, relationships) and sequential mutate-k5-element-instance calls. If you decline, relationship creation is skipped. Diagrams can still be offered from the elements that were created.
9. Optional diagrams — After the elements exist, and after any relationships you chose to create, asks whether you want one or more diagrams. A diagram is created only after you ask for one.
10. Choose a visualization scope — If you want a diagram, offers at least three choices: one diagram of all newly created elements and relationships; one or more scopes taken from the created design and the code; or a custom scope you define. Suggested scopes stay within what the design can show — for example a bounded context or domain area, a service, module, or component, an API surface with its handlers, an aggregate or entity cluster, or an integration view between major elements.
11. Confirm the scope — Summarizes the selected scope and waits for your confirmation. For a custom scope, it helps you express that scope in terms of the created elements and relationships.
12. Create and lay out the diagram — Creates the diagram with a name and description that match the confirmed scope, plans explicit positions before placing anything, adds in-scope elements as nodes (add-nodes-to-diagram), then adds in-scope relationships as edges (add-edges-to-diagram) only when both ends are already on the diagram. The layout is chosen for the scope and its relationships: related nodes stay aligned, boxes do not overlap, labels have room, and parent nodes are nested where composition or aggregation calls for it. Elements with no relationship in scope can still appear as standalone nodes when that helps explain the design. Further layout rules, such as a minimum node width, can be supplied through a diagram layout skill.
13. Report the result — Tells you which diagrams were created, what each one covers, and what was left out because of the scope you chose.

Where you need to respond — the assistant should stop and wait at these points; reply clearly (approve, adjust, or reject) so the run can continue or stop safely:

Checkpoint	What the assistant expects from you
After listing element types	Choose a design approach or a dedicated element type from the list to guide what will be modelled.
After filtering element types	Confirm that the shortlisted element types fit your chosen approach before per-type detail calls start.
Before any code is analyzed	Confirm the code scope to consider (paths/modules/services/whole repo).
After proposing the element design	Confirm that the planned elements and properties match what you want before any element mutations run.
After elements are created	Say whether you want to continue with relationships between elements (yes/no). If you decline, relationships are skipped. Diagrams can still be created from the elements that exist.
After proposing relationships	If you chose to continue, confirm the planned relationship set before relationship mutations run.
After elements and any relationships	Say whether you want one or more diagrams. A diagram is created only when you ask for one.
When a diagram is requested	Choose what to show: all newly created elements and relationships, a suggested scope, or a custom scope.
Before the diagram is created	Confirm the summarized visualization scope.

Until you confirm at the first two checkpoints, no design data is written via mutations. Element mutations, relationship mutations, and diagram creation each run only after the confirmation that precedes them, and each of those steps changes the model on the branch in Solution Designer.

After the run, open Solution Designer on that branch and continue modelling, diagrams, and reviews in the workbench as usual.

Align an existing design with the implementation

A reverse-engineering run does not always capture the whole implementation. Later, the code can also move on while the design stays as it was. In both cases the design and the implementation are out of step, and you can ask the coding assistant to compare them and update the design.

Use the same setup as for the initial workflow: the Modelling Support MCP server is configured in your coding assistant, and the repository you cloned is on the branch that holds the design you want to update. That same branch must be checked out in Solution Designer.

This follow-up is a chat prompt you paste into the coding assistant. The server prompt generate-k5-design-from-code remains the way to create the first design from code. Paste the following text into the chat:

Check the k5 design in the workbench and compare it with the implementation. List what should be changed in the design to match the implementation and update it after confirmation.

The assistant reads the current design through the Modelling Support MCP server and the implementation from the local repository. It then lists what should change in the design so it matches the implementation. Review that list in the chat. Reply with what to keep, adjust, or drop. The assistant updates the design on the branch only after you confirm.

You can narrow the comparison in the same message—for example to a module, a service, a set of paths, or specific element types.

The comparison can call several MCP tools. If your coding assistant asks you to confirm each tool call, the allowlist tip from the reverse-engineering steps applies here as well.

After the update, switch back to Solution Designer and review the design on that branch. To keep the update, commit and push the changes through the workbench.

Inject project-specific conversion rules

If your project has specific mapping requirements (for example, naming conventions or detailed business-logic mapping rules), you can inject these rules into the reverse-engineering workflow by providing a skill to your coding assistant (if skills are supported by that assistant).

Create the skill in the assistant-specific skill folder, for example:

• .github/skills
• .bob/skills
• .cursor/skills

To ensure that the skill is picked up automatically when using the reverse-engineering prompt, use exactly the following metadata:

• name: resolve-k5-design-from-code-rules
• description: Specific rules for converting and mapping current code to k5 design elements. Use when resolving a k5 design from the current codebase. Keywords: k5 design resolution, code to design rules, design mapping rules.

Example skill file content:

---
name: resolve-k5-design-from-code-rules
description: 'Specific rules for converting and mapping current code to k5 design elements. Use when resolving a k5 design from the current codebase. Keywords: k5 design resolution, code to design rules, design mapping rules.'
---

# Code to K5 Design Conversion Rules

Extend the K5 design creation workflow with project-specific mapping rules. This skill provides injection points for the reverse engineering steps when generating a K5 design from existing code. Use this skill to define how specific code patterns, naming conventions, and architectural structures in your project should be interpreted and mapped to K5 design elements.

## Template: Add Your Mapping Rules Below
### Naming Conventions for k5 design elements
- All K5 Entity identifiers and labels must end with "Entity"
- Domain Service identifiers and labels must be prefixed with "SVC"

### Detail level for business logic mapping
- Business logic of DDD services and DDD commands needs to be created as a step by step mapping of the code logic to policies and rules in K5. This includes mapping of algorithms, decision trees, and complex logic to K5 policies.
- Business logic of DDD services and DDD commands need to be created as proper markdown document, with the sections "Precondition", "Main logic" and "Postcondition". Provide each section even if it is empty.

Inject project-specific diagram layout rules

When the workflow creates diagram content, you can influence how nodes and edges are laid out by providing an additional skill to your coding assistant (if skills are supported by that assistant). Use it for rules such as minimum node size, spacing, alignment, or how edges should be placed.

Create the skill in the same assistant-specific skill folder as the conversion rules, for example:

• .github/skills
• .bob/skills
• .cursor/skills

To ensure that the skill is picked up when diagram nodes and edges are created, use exactly the following metadata:

• name: k5-diagram-layout-rules
• description: Specific rules around layout, positioning, etc. when creating diagram content (nodes, edges) on k5 diagrams

Example skill file content:

---
name: k5-diagram-layout-rules
description: 'Specific rules around layout, positioning, etc. when creating diagram content (nodes, edges) on k5 diagrams'
---

# k5 diagram layout rules
...

See also

• Manage access tokens — create, rotate, and revoke personal access tokens
• Modelling Support MCP server — endpoint, auth, tools, and generate-k5-design-from-code
• Modeling environment
• Project configuration — k5-project.yml — project acronym