© 2026 UML Forge. All rights reserved.

AI-generated diagrams may contain errors — review before production use.

FeedbackTermsPrivacy
UML Forge
DocsLog inGet started free
Docs›How-to Articles

How-to Articles

Step-by-step guides for common diagram workflows.

🔄
How to document an API with sequence diagrams2 min

Turn a list of endpoints and services into a professional interaction diagram — with failure paths.

🔐
How to produce a security threat model3 min

Generate a STRIDE analysis, data-flow diagram with sensitivity labels, and trust boundary map.

🔍
How to reverse-engineer an existing codebase3 min

Point at any codebase description and get accurate class, sequence, or dependency diagrams.

📦
How to produce a team onboarding package3 min

Generate a system overview, developer workflow diagram, and gotchas table for new team members.

📄
How to keep diagrams current with Living Docs2 min

Update existing diagrams to reflect sprint or PR changes, with changelog headers.

📋
How to get a plain-English analysis report (Report Mode)1 min

Receive a full written report — findings, health scores, and a remediation roadmap — alongside your diagrams.

📦
uvx vs pip install — do I need to install anything?2 min

Understand the difference between uvx and pip install, and what you actually need to get started.

🏛️
How to modernise legacy COBOL, Fortran, or Ada code5 min

Extract class, sequence, and state diagrams from any legacy codebase — the first step in any migration to modern languages.

🔄umlforge_api_sequence2 min

How to document an API with sequence diagrams

When to use this

Use this tool when you are designing or documenting REST or event-driven API interactions between microservices. It is ideal before writing integration code, during PR review, and for stakeholder handovers.

What to provide

You need:
- endpoints — the routes involved (e.g. "POST /orders, POST /payments, GET /orders/{id}")
- services — the services that call each other (e.g. "OrderService, PaymentService, NotificationService")
- auth_method — how the API is secured (e.g. "JWT Bearer", "API Key")
- include_error_flows — set to true to include 4xx/5xx paths and retries

Example prompt

``
Use umlforge_api_sequence with:
- endpoints: "POST /orders, POST /payments, GET /orders/{id}"
- services: "OrderService, PaymentService, NotificationService, EmailService"
- auth_method: "JWT Bearer"
- include_error_flows: true
``

What you get

A Mermaid sequenceDiagram showing all participants, request/response arrows, auth flow, error branches, and retry paths. Paste the output into GitHub, Notion, or any Markdown editor to render it.
🔐umlforge_threat_model3 min

How to produce a security threat model

When to use this

Use this tool whenever your architecture changes, a new feature adds a data flow, or you are approaching a compliance audit. It is also useful in PR review for any change that touches auth, data storage, or external integrations.

What to provide

You need:
- system_description — what the system does, who uses it, and what data it handles
- components — the services, databases, and external integrations involved
- data_flows — how data moves between components (e.g. "user → API → DB → email provider")
- trust_boundaries — where trust changes (e.g. "public internet to internal network")

Example prompt

``
Use umlforge_threat_model with:
- system_description: "SaaS API that generates diagrams for paying users.
Stores bcrypt API keys and usage logs in PostgreSQL."
- components: "FastAPI, Neon PostgreSQL, Anthropic API, Paystack"
- data_flows: "Claude → connector → API → Anthropic → API → DB → response"
- trust_boundaries: "Public internet / Railway private network / Neon VPC"
``

What you get

A DFD with sensitivity labels (PII, secrets, financial), a STRIDE table listing threats per component (Spoofing, Tampering, Repudiation, Information Disclosure, DoS, Elevation of Privilege), and a trust boundary diagram. Compliance-ready in seconds.
🔍umlforge_reverse_engineer3 min

How to reverse-engineer an existing codebase

When to use this

Use this when you have inherited a codebase, are doing a pre-refactor audit, want to produce architecture documentation for an existing system, or need to onboard someone quickly without writing docs from scratch.

What to provide

You need:
- codebase — paste code snippets, file contents, or write a structured description of the codebase
- language — the primary language (e.g. "Python", "TypeScript", "Java")
- diagram_type — what kind of diagram you want: class, sequence, dependency, or all
- focus_area — (optional) the specific module or layer to zoom in on

Example prompt

``
Use umlforge_reverse_engineer with:
- codebase: "FastAPI app with api/auth.py (API key auth, bcrypt),
api/router.py (routes /v1/generate and /v1/suggest), api/prompts/ (12 prompt
modules inheriting from BasePrompt), api/limiter.py (rate limiting),
api/usage.py (usage logging), api/db.py (SQLAlchemy async session)"
- language: "Python"
- diagram_type: "dependency"
- focus_area: "api/prompts layer"
``

What you get

A dependency or class diagram showing module relationships, inheritance hierarchies, and key interfaces. The tool infers structure from your description and produces an accurate Mermaid diagram — no need to paste source code.
📦umlforge_onboarding3 min

How to produce a team onboarding package

When to use this

Use this when a new developer is joining your team, you are doing a module handover, or you need to produce documentation before departure. The output is designed to get someone productive in days, not weeks.

What to provide

You need:
- system_description — what the system is, who uses it, and what it does
- tech_stack — languages, frameworks, databases, and infrastructure
- key_workflows — the 2–3 most important flows a new developer must understand
- pain_points — (optional but highly recommended) known gotchas, non-obvious decisions, and areas that trip up new developers

Example prompt

``
Use umlforge_onboarding with:
- system_description: "B2B SaaS that processes customer invoices, matches them to
purchase orders, and routes exceptions to a human review queue."
- tech_stack: "Node.js, TypeScript, PostgreSQL, Redis, BullMQ, React, AWS S3"
- key_workflows: "Invoice ingestion, PO matching, exception escalation"
- pain_points: "BullMQ jobs retry 3 times silently before dead-lettering.
The PO matcher uses fuzzy matching — threshold is in config, not code."
``

What you get

A C4 container diagram (system overview) and a sequence diagram (developer workflow from local dev to production). Plus a gotchas table covering pain points you described and others the tool infers — what the code does, why it does it that way, and what breaks if you change it.
📄umlforge_living_docs2 min

How to keep diagrams current with Living Docs

When to use this

Use this after any sprint, PR, or architectural change that affects an existing diagram. It diffs your old diagram against the described changes and produces an updated version — plus flags for any elements that were intentionally removed.

What to provide

You need:
- current_diagrams — paste in your existing Mermaid diagram(s), including the ```mermaid fences
- sprint_changes — a description of what changed: new components, removed flows, renamed services, modified behaviour
- affected_files — (optional) the files or modules touched in this sprint or PR

Example prompt

``
Use umlforge_living_docs with:
- current_diagrams: """
`mermaid
sequenceDiagram
User->>API: POST /orders
API->>DB: INSERT order
DB-->>API: order_id
API-->>User: 201 Created
`
"""
- sprint_changes: "Added async email notification via SendGrid after order creation.
Added idempotency key header check before INSERT. Orders now also write to Redis
cache for fast GET lookups."
- affected_files: "api/orders.py, api/email.py, api/cache.py"
``

What you get

An updated Mermaid diagram with %% changelog headers (date, what changed, which sprint/PR). New elements are added, removed ones are flagged with REMOVED annotations, and a prose architecture evolution note is included — ready to paste into your wiki.
📋umlforge_reverse_engineer1 min

How to get a plain-English analysis report (Report Mode)

What Report Mode does

Report Mode is a Pro feature that runs a second AI pass after your diagrams are generated. Instead of just a diagram, you receive:

- System Overview — what the codebase or system does, written for non-technical stakeholders
- Key Findings — each architectural problem explained in plain English with real-world risk and business impact
- Remediation Roadmap — numbered list of specific fixes, naming the exact library or pattern to use, with effort estimates (Low / Medium / High)
- Health Score — letter grades (A–F) across three dimensions (e.g. Architecture, Maintainability, Test Readiness)

Available on: umlforge_reverse_engineer, umlforge_threat_model, umlforge_deployment, umlforge_erd_schema, umlforge_api_sequence

Option A — Ask Claude directly in the chat

Add report_mode=True to your request. Examples:

``
Use umlforge_reverse_engineer with:
- github_url: "https://github.com/pallets/flask"
- report_mode: True
`

`
Use umlforge_threat_model with:
- system_description: "SaaS API with FastAPI, PostgreSQL, and Paystack payments"
- auth_mechanism: "JWT and Bearer API keys"
- report_mode: True
``

Claude Code, Cursor, and Windsurf will call the tool with that parameter automatically.

Option B — Turn it on permanently in your dashboard

Go to umlforge.dev/dashboard → Pro Features → toggle Report Mode ON.

Once enabled, every tool call you make automatically includes report_mode=True — you never have to add it manually. Toggle it off whenever you want diagrams only (useful when you need a quick diagram and don't want to wait for the second AI pass).

This is the recommended approach for Pro users who want reports as a default.

Performance note

Report Mode makes a second AI call after the diagrams are generated. Expect generation time to roughly double (from ~20–40 seconds to ~40–90 seconds). The extra time produces the full written report — all sections are generated in that second call, not streamed incrementally.

If you need a quick diagram during active development, toggle Report Mode off. Turn it back on for audits, reviews, and stakeholder deliverables.
📦umlforge_reverse_engineer2 min

uvx vs pip install — do I need to install anything?

Short answer

No manual installation required. Your coding editor (Claude Code, Cursor, Windsurf) handles everything automatically from the .mcp.json config block. You set it up once and forget it.

What uvx does

uvx is a tool runner provided by uv (a fast Python package manager). It works like npx in the Node.js world:

- Downloads the umlforge package to a temporary isolated environment
- Starts the MCP server process
- Cleans up when your editor closes

Your .mcp.json config tells your editor to run uvx umlforge==0.1.2. When you open your editor, it executes that command — downloading and starting the connector automatically. You never touch Python environments or pip directly.

``json
{
"mcpServers": {
"umlforge": {
"command": "uvx",
"args": ["umlforge==0.1.2"],
"env": { "UMLFORGE_API_KEY": "your-key" }
}
}
}
``

What pip install umlforge does

pip install umlforge permanently installs the connector package into your current Python environment. PyPI shows this command by default for every package — it does not know about the MCP / uvx use case.

You would use pip install umlforge only if:
- You want to run the connector as a standalone command outside of an editor
- You are building something that imports the connector as a Python library
- You have a custom setup that does not support uvx

For the vast majority of users, pip install is never needed.

The only prerequisite

You need uv installed on your machine to use uvx. Claude Code bundles it automatically. Cursor and Windsurf users may need to install it once:

macOS / Linux:
``
curl -LsSf https://astral.sh/uv/install.sh | sh
`

Windows (PowerShell):
`
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
`

After that, paste your .mcp.json config block and you are done. The connector updates automatically whenever you pin a new version number in the args` array.

Version pinning

Always use a pinned version in your config:

``
"args": ["umlforge==0.1.2"] ✓ Recommended
"args": ["umlforge"] ✗ Unpinned — pulls latest on every launch
``

Pinning ensures your setup is reproducible and immune to unexpected breaking changes in a new release. Check pypi.org/project/umlforge for the latest version number and update the pin when you want to upgrade.
🏛️umlforge_reverse_engineer5 min

How to modernise legacy COBOL, Fortran, or Ada code

Why this works

UML Forge uses Claude, which understands decades of programming history — including COBOL, Fortran, Ada, RPG IV, PL/1, MUMPS, and Assembly. Unlike IDE-based tools that require a working compiler, UML Forge works from code text and descriptions, making it the only MCP diagramming tool that handles legacy systems out of the box.

Supported legacy languages: COBOL (ANSI 85, COBOL 2002), Fortran (77, 90, 95, 2003), Ada (83, 95, 2005, 2012), RPG IV / ILE RPG (IBM AS/400), PL/1, MUMPS/M (OpenVMS, Caché), Assembly (x86, Z80, IBM S/360 macro), BASIC, Pascal, Delphi.

The modernisation workflow

The recommended four-step workflow:

Step 1 — Diagram the legacy system
Paste COBOL/Fortran/Ada snippets into umlforge_reverse_engineer. Get class, sequence, and state diagrams that document what the code actually does.

Step 2 — Identify bounded contexts
Use the class diagram to draw boundary lines around logically cohesive groups. Each boundary becomes one modern microservice or module.

Step 3 — Hand diagrams to your AI coding agent
Provide the Mermaid diagrams as a spec: "Implement this class diagram in Python/Go/TypeScript." The agent has a precise blueprint — not a vague description.

Step 4 — Validate behaviour
Use umlforge_api_sequence to diagram the new system and compare it against the original. Any divergence in sequence diagrams reveals missed behaviour.

COBOL example

Paste your COBOL source directly into the codebase field. The tool maps COBOL constructs to modern diagram concepts:

| COBOL construct | Diagram concept |
|---|---|
| FD + 01 record | Class with attributes |
| 88-level condition | Boolean method (isActive, isSuspended) |
| WORKING-STORAGE | Shared state / fields |
| PARAGRAPH | Method in sequence diagram |
| PERFORM loop | Loop fragment in sequence |

``
Use umlforge_reverse_engineer with:
- codebase: """
IDENTIFICATION DIVISION.
PROGRAM-ID. CUSTORD.
DATA DIVISION.
FILE SECTION.
FD CUSTOMER-FILE.
01 CUSTOMER-RECORD.
05 CUST-ID PIC 9(6).
05 CUST-NAME PIC X(40).
05 CUST-STATUS PIC X.
88 CUST-ACTIVE VALUE 'A'.
88 CUST-CLOSED VALUE 'C'.
PROCEDURE DIVISION.
MAIN-PARA.
PERFORM PROCESS-ORDERS UNTIL END-OF-FILE
STOP RUN.
PROCESS-ORDERS.
READ CUSTOMER-FILE
IF CUST-ACTIVE
PERFORM APPROVE-TRANSACTION.
"""
- max_nodes: 15
``

Fortran example

Fortran modules and derived types map cleanly to classes. The tool also captures LAPACK/BLAS external dependencies as labelled external nodes.

``
Use umlforge_reverse_engineer with:
- codebase: """
MODULE solver_module
USE mesh_module
TYPE :: FESolver
TYPE(Mesh) :: mesh
REAL(8), ALLOCATABLE :: global_K(:,:)
REAL(8), ALLOCATABLE :: displacement_vector(:)
CONTAINS
PROCEDURE :: assemble_global_stiffness
PROCEDURE :: solve_linear_system
PROCEDURE :: check_yield_criterion
END TYPE FESolver
END MODULE solver_module
"""
- max_nodes: 20
``

Ada example

Ada's protected types and task types are correctly identified as concurrent components. The sequence diagram captures entry/accept rendezvous patterns.

``
Use umlforge_reverse_engineer with:
- codebase: """
package Collision_Detector is
task type Conflict_Monitor is
entry Start (Registry : access Track_Registry);
entry Stop;
end Conflict_Monitor;
protected Conflict_Queue is
procedure Enqueue (Report : Conflict_Report);
entry Dequeue (Report : out Conflict_Report);
end Conflict_Queue;
end Collision_Detector;
"""
- max_nodes: 15
``

What you get

Three diagrams:

- Class diagram — all data structures mapped to classes with attributes, methods inferred from paragraphs/subroutines, and inheritance or composition relationships
- Sequence diagram — the dominant execution flow (main loop, primary transaction path, or interrupt handler)
- State diagram — entity lifecycle if stateful entities are found (order status, account status, task states)

Plus architectural smell flags — god classes, anemic models, tight coupling to file I/O, missing error handling — which serve as your modernisation backlog.

The smell flags are your sprint backlog. Each flag maps to a refactoring task. Work through them in priority order and the legacy system's architecture becomes progressively cleaner as you port it.
← Getting Started
Install the connector and generate your first diagram.
Tool Reference →
All 13 tools listed with descriptions.