How-to Articles

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.

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

``
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
``

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.

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.

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")

``
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"
``

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.

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.

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

``
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"
``

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.

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.

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

``
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."
``

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.

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.

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

``
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"
``

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.

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 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.

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 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'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
``

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.