Skip to main content

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 Builder workbench with something to refine instead of an empty model.

Main use case:

  • Onboard an existing project into solution design without modelling everything by hand first.

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.

For endpoint, JWT authentication, and tool behaviour, use the full reference: Modelling Support MCP server.

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:

❗️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 Builder if it is not there already (same project you want to create a design for).
  2. Create a new Git branch in Solution Builder 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. Configure MCP in the IDE: add the Modelling Support MCP server to your coding assistant IDE and set up authentication. See Authentication for the available options (OAuth client, dynamic client registration, or static Bearer token).
  5. 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.
  6. 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.
  7. After successful running the prompt, switch back to the Solution Builder 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 Builder. To continue working with it, make sure you commit and push the changes through the Solution Builder.

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.

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 to retrieve further insights and understand the available properties of each element type.

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
* Properties of type elementReference are references to other elements. Make sure they are considered and created as well.
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 type 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
* Group creation of multiple element types together if possible.
* For model elements referencing others (properties of type elementReference):
    * Phase 1 - Create element that references the other thing first: Create the element and collect its UUID --> owning element
    * Phase 2 - Create referenced element(s): Create all elements (in case omlParentId is required, set it to the owning element UUID from Phase 1), and collect all child UUIDs from responses
    * Phase 3 - Link referenced elements to owning element: Immediately edit the owning element to update its properties with the collected referenced element UUIDs
    * This ensures bidirectional references are complete and correct: children point up via omlParentId, parent points down via reference arrays
Perform the GraphQL mutations (create or edit) by using another MCP tool called "mutate-k5-element-instance". 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:
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".

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 Builder as described in step 4.

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 properties (including creating any referenced elements for properties of type elementReference), 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 (create/edit). For elementReference properties, it follows the 3-phase flow: create owning element → create referenced elements (with omlParentId when required) → edit owning element to link the collected UUIDs.
  8. Optional relationships — If you agree to continue, 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 to create relationships.

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:

CheckpointWhat the assistant expects from you
After listing element typesChoose a design approach or a dedicated element type from the list to guide what will be modelled.
After filtering element typesConfirm that the shortlisted element types fit your chosen approach before per-type detail calls start.
Before any code is analyzedConfirm the code scope to consider (paths/modules/services/whole repo).
After proposing the element designConfirm that the planned elements (including elementReference-driven elements) and properties match what you want before any element mutations run.
After elements are createdSay whether you want to continue with relationships between elements (yes/no). If you decline, the relationship phase is skipped.
After proposing relationshipsIf you chose to continue, Confirm the planned relationship set before relationship mutations run.

Until you confirm at the first two checkpoints, no design data is written via mutations; after that, each mutation step changes the model on the branch in Solution Builder.

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

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.

See also​