> ## Documentation Index
> Fetch the complete documentation index at: https://docs.keldyn.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate an architecture from your codebase

> Use the Keldyn MCP server to infer a Threagile architecture model from your repository, save it to a use case, and analyze it for security risks and compliance gaps.

A use case's **architecture model** is what Keldyn uses to run threat modeling and architecture-based compliance checks. Instead of hand-drawing it, you can let an AI agent connected to the [Keldyn MCP server](/keldyn-mcp-server) infer the model directly from your code — technical assets, data assets, trust boundaries, shared runtimes, and communication links — then save it and analyze it, all without leaving your editor.

<Note>
  The `generate-architecture` prompt models your system from the **code and config it can inspect**, not from a questionnaire. Run the agent from the repository you want to model so it can read your source.
</Note>

## What you'll use

| Piece                               | Type     | Role                                                                                    |
| ----------------------------------- | -------- | --------------------------------------------------------------------------------------- |
| **`generate-architecture`**         | Prompt   | Briefs the agent to infer a Threagile model from the codebase (or a scope) and save it. |
| **`update-use-case-architecture`**  | Tool     | Validates the model against the Threagile schema and saves it to a use case.            |
| **`analyze-use-case-architecture`** | Tool     | Runs Threagile security analysis + RCM compliance checks and returns fixable issues.    |
| **`keldyn://threagile-schema`**     | Resource | The authoritative schema for allowed properties and enum values.                        |

## Before you start

<Steps>
  <Step title="Connect the MCP server">
    Follow [Keldyn MCP server](/keldyn-mcp-server) to connect your AI tool and sign in to the team that owns the target use case.
  </Step>

  <Step title="Open the repository">
    Start the agent from the repo (or monorepo) you want to model, so it can list and read your files.
  </Step>

  <Step title="Have a use case ready">
    Know which use case the architecture belongs to. If you don't pass one, the agent will list your use cases and ask you to choose before saving.
  </Step>
</Steps>

## 1. Generate the model

Invoke the `generate-architecture` prompt. It accepts three optional arguments:

| Argument       | Purpose                                                                                                            |
| -------------- | ------------------------------------------------------------------------------------------------------------------ |
| `useCaseId`    | The use case to save to. Omit it and the agent runs `list-use-cases` and asks you which one.                       |
| `scope`        | A path, glob, or monorepo package to base the model on (e.g. `apps/keldyn-api`). Defaults to the whole repository. |
| `instructions` | Extra product/architecture hints to honor while modeling.                                                          |

```text theme={null}
Use the generate-architecture prompt for use case <USE_CASE_ID>,
scoped to apps/keldyn-api. Map the services, data stores, auth, and
external integrations from the code, then save the model.
```

Behind the scenes the agent will:

<Steps>
  <Step title="Map the system from code">
    List tracked files (e.g. `git ls-files`), then read entrypoints, service boundaries, APIs, data stores, auth, queues, external integrations, and infra/config — restricted to your `scope` if you set one.
  </Step>

  <Step title="Use the real schema for enums">
    Read the `keldyn://threagile-schema` resource for allowed property names and enum values (rather than guessing), including production-required root fields like `business_criticality`.
  </Step>

  <Step title="Save via the tool">
    Call `update-use-case-architecture` with the `architectureData` object and your `useCaseId`, and report back the `useCaseName` and whether `success` was true.
  </Step>
</Steps>

<Warning>
  The model should reflect **only assets and links you can justify from the code** — the prompt explicitly avoids inventing services that aren't evidenced. If the agent proposes something you don't recognize, ask it to cite the file it inferred it from.
</Warning>

<Tip>
  **Infrastructure-as-code counts as evidence too.** If your repository defines infrastructure with Terraform (or similar), tell the agent to read it — files like `*.tf`, `*.tfvars`, and modules describe your real deployed topology (VPCs and subnets → trust boundaries, managed databases and buckets → data stores, load balancers/queues/functions → technical assets, security groups → communication links). Point the `scope` and `instructions` at them so the model is grounded in what's actually provisioned:

  ```text theme={null}
  Use generate-architecture for use case <USE_CASE_ID>. Also read the
  Terraform under infra/ (*.tf, *.tfvars, modules/) and use it to infer
  trust boundaries, data stores, and external services alongside the app code.
  ```
</Tip>

<Tip>
  If saving fails schema validation, the agent re-reads `keldyn://threagile-schema`, fixes the model, and retries `update-use-case-architecture` once. Pasting the JSON into chat is **not** enough — the model only persists when the tool call succeeds.
</Tip>

## 2. Analyze the architecture

Once a model is saved, run `analyze-use-case-architecture` to threat-model it and check it against your frameworks in one pass.

```text theme={null}
Run analyze-use-case-architecture for use case <USE_CASE_ID> and list
the issues by severity.
```

It returns a unified, most-severe-first list of **issues** combining two sources:

* **Security risks** (from Threagile) — each with `severity`, `CWE`, `STRIDE` category, and the affected asset.
* **Compliance failures** (failed RCM architecture checks) — each with the `frameworkName` and `rcmId` it violates.

Every issue includes a **`proposedEdit`**: a natural-language remediation the agent can turn into an architecture change.

| Argument    | Purpose                                                                                                                                                                                  |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `useCaseId` | The use case to analyze. Omit to use the first listed use case.                                                                                                                          |
| `run`       | `true` (default) runs a **fresh** Threagile analysis (can take up to \~3 minutes). Set `false` to read the last stored analysis instead. RCM compliance checks are always computed live. |

<Note>
  Analysis requires a saved architecture — run `generate-architecture` / `update-use-case-architecture` first. Issues are capped at **32 per call**; when more remain, the result flags `truncated` with a `remainingIssues` count so you fix a batch at a time.
</Note>

## 3. Remediate and re-verify

Architecture hardening is a loop: fix a batch of issues, save, and re-run to confirm they cleared and fetch the next batch.

<Steps>
  <Step title="Turn proposed edits into model changes">
    For each issue, convert its `proposedEdit` into a concrete change to the architecture object (e.g. add an encryption protocol on a link, introduce a trust boundary, tag a data asset).
  </Step>

  <Step title="Save the updated model">
    Call `update-use-case-architecture` with the revised `architectureData`.
  </Step>

  <Step title="Re-run the analysis">
    Call `analyze-use-case-architecture` again to verify the fixed issues are gone and pull any remaining ones.
  </Step>
</Steps>

```text theme={null}
For the highest-severity issues from the analysis, apply the proposed
edits to the architecture, save with update-use-case-architecture, then
re-run analyze-use-case-architecture to confirm they're resolved.
```

<Tip>
  Don't try to fix hundreds of issues at once. Work the returned batch (up to 32), re-run, and repeat — the tool is designed for this incremental loop.
</Tip>

## Keeping the model current

Re-run `generate-architecture` (or targeted `update-use-case-architecture` edits) after significant changes — new services, data stores, or integrations — so the threat model and compliance checks stay accurate. Pair this with the [controls-to-code workflow](/guides/mcp-controls-to-code): an up-to-date architecture is what drives the architecture-based control checks you close there.

## Next steps

<CardGroup cols={2}>
  <Card title="From controls to code" icon="git-compare-arrows" href="/guides/mcp-controls-to-code" arrow={true}>
    Read your controls, analyze code for evidence, and close gaps with tasks.
  </Card>

  <Card title="Keldyn MCP server" icon="plug" href="/keldyn-mcp-server" arrow={true}>
    Connect your AI tool and see the full catalog of tools and prompts.
  </Card>

  <Card title="Working with a use case" icon="box" href="/working-with-use-cases" arrow={true}>
    Explore the Architecture Workspace and track control progress in the app.
  </Card>

  <Card title="Frameworks & controls" icon="list-checks" href="/frameworks-and-controls" arrow={true}>
    See how architecture checks feed control coverage and maturity.
  </Card>
</CardGroup>