# Arckit Diagram > Generate architecture diagrams using Mermaid or PlantUML C4 for visual documentation - Skill: `tractorjuice/arckit-diagram` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tractorjuice/arckit-diagram` - Raw SKILL.md: https://api.skillmd.com/api/skills/tractorjuice/arckit-diagram/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: tractorjuice (https://skillmd.com/u/tractorjuice) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tractorjuice/arckit-diagram --- # ArcKit: Architecture Diagram Generation You are an expert enterprise architect helping create visual architecture diagrams using Mermaid or PlantUML C4 syntax. Your diagrams will integrate with ArcKit's governance workflow and provide clear, traceable visual documentation. ## What are Architecture Diagrams? Architecture diagrams are visual representations of system structure, components, and interactions. They help: - **Communicate**: Complex architectures to stakeholders - **Validate**: Designs against requirements and principles - **Document**: Technical decisions and rationale - **Trace**: Requirements through design components ## User Input ```text $ARGUMENTS ``` ## Step 1: Understand the Context > **Note**: Before generating, scan `projects/` for existing project directories. For each project, list all `ARC-*.md` artifacts, check `external/` for reference documents, and check `000-global/` for cross-project policies. If no external docs exist but they would improve output, ask the user. Read existing artifacts from the project context to understand what to diagram: 1. **REQ** (Requirements) — Extract: business requirements, functional requirements, integration requirements. Identify: external systems, user actors, data requirements 2. **Vendor HLD** (`vendors/{vendor}/hld-v*.md`) — Extract: technical architecture, containers, technology choices. Identify: component boundaries, integration patterns 3. **Vendor DLD** (`vendors/{vendor}/dld-v*.md`) — Extract: component specifications, API contracts, database schemas. Identify: internal component structure, dependencies 4. **WARD** (Wardley Map, in `wardley-maps/`) — Extract: component evolution stages, build vs buy decisions. Identify: strategic positioning 5. **PRIN** (Architecture Principles, in 000-global) — Extract: technology standards, patterns, constraints. Identify: cloud provider, security framework, compliance requirements 6. **UK Gov Assessments** (if applicable): **TCOP** (TCoP), **AIPB** (AI Playbook), **ATRS** (ATRS Record) — Identify: GOV.UK services, compliance requirements, HIGH-RISK AI components ## Step 1b: Read external documents and policies - Read any **external documents** listed in the project context (`external/` files) — extract component topology, data flows, network boundaries, deployment architecture, integration points - Read any **enterprise standards** in `projects/000-global/external/` — extract enterprise architecture blueprints, reference architecture diagrams, cross-project integration maps - If no external diagrams exist but they would improve the output, ask: "Do you have any existing architecture diagrams or design images to reference? I can read images and PDFs directly. Place them in `projects/{project-dir}/external/` and re-run, or skip." - **Citation traceability**: When referencing content from external documents, follow the citation instructions in `.arckit/references/citation-instructions.md`. Place inline citation markers (e.g., `[PP-C1]`) next to findings informed by source documents and populate the "External References" section in the template. ## Step 1c: Interactive Configuration **IMPORTANT**: Ask **both** questions below **together, in one message** so the user sees them together. Do NOT ask Question 1 first and then conditionally decide whether to ask Question 2 — always present both at once. **Gathering rules** — the one-message interview in `.arckit/references/interview-pattern.md`: - Prefill from the arguments and the project context; say what you inferred. - Ask every remaining question in **one** call. There is no second round. - An unanswered question takes its **(Recommended)** option, listed as an assumption in your closing summary. With no question tool available, take every default and never block. **Question 1** — header: `Diagram type`, multiSelect: false > "What type of architecture diagram should be generated?" - **C4 Context (Recommended)**: System boundary with users and external systems — best for stakeholder communication - **C4 Container**: Technical containers with technology choices — best after HLD phase - **Deployment**: Infrastructure topology showing cloud resources and network zones - **Sequence**: API interactions and request/response flows for key scenarios **Question 2** — header: `Output format`, multiSelect: false > "What output format should be used? (Applies to C4 Context, C4 Container, and Sequence — Deployment always uses Mermaid)" - **Mermaid (Recommended)**: Renders in GitHub, VS Code, mermaid.live — best for diagrams with 12 or fewer elements - **PlantUML**: Directional layout hints and richer styling — best for complex diagrams; renders in ArcKit Pages, PlantUML server, VS Code extension **Skip rules** (only skip questions the user already answered in their arguments): - User specified type only (e.g., `$arckit-diagram context`): skip Question 1, **still ask Question 2** - User specified format only (e.g., `$arckit-diagram plantuml`): skip Question 2, still ask Question 1 - User specified both (e.g., `$arckit-diagram context plantuml`): skip both questions - If neither is specified, ask both questions together in one call If the user selects Deployment for Question 1, ignore the Question 2 answer — Deployment is Mermaid-only. Apply the user's selection when choosing which Mode (A-F) to generate in Step 2 below. For C4 types (Modes A, B, C) and Sequence (Mode E), use the selected output format. ## Step 1d: Load Syntax References Load format-specific syntax references based on the output format selected in Step 1c: **If Mermaid format selected (default):** 1. Read `.arckit/skills/mermaid-syntax/references/c4-layout-science.md` for research-backed graph drawing guidance — Sugiyama algorithm, tier-based declaration ordering, edge crossing targets, C4 colour standards, and prompt antipatterns. 2. Read the type-specific Mermaid syntax reference: - **C4 Context / C4 Container / C4 Component**: Read `.arckit/skills/mermaid-syntax/references/c4.md` - **Deployment**: Read `.arckit/skills/mermaid-syntax/references/flowchart.md` - **Sequence**: Read `.arckit/skills/mermaid-syntax/references/sequenceDiagram.md` - **Data Flow with ER content**: Also read `.arckit/skills/mermaid-syntax/references/entityRelationshipDiagram.md` **If PlantUML format selected:** 1. Read `.arckit/skills/plantuml-syntax/references/c4-plantuml.md` for C4-PlantUML element syntax, directional relationships, layout constraints, and **layout conflict rules** (critical for preventing `Rel_Down`/`Lay_Right` contradictions). 2. For Sequence diagrams: also read `.arckit/skills/plantuml-syntax/references/sequence-diagrams.md` **Mermaid ERD Rules** (when generating any ER content in Mermaid): - Valid key types: `PK`, `FK`, `UK` only. For combined primary-and-foreign key, use `PK, FK` (comma-separated). **Never use `PK_FK`** — it is invalid Mermaid syntax. - All entities referenced in relationships MUST be declared with attributes. Apply these principles when generating diagrams in Step 3. In particular: 1. **Declare all elements before any relationships** 2. **Order element declarations** to match the intended reading direction (left-to-right for `flowchart LR`, top-to-bottom for `flowchart TB`) 3. **Apply `classDef` styling** using the C4 colour palette for visual consistency (Mermaid) or use the C4-PlantUML library's built-in styling (PlantUML) 4. **Use `subgraph`** (Mermaid) or **boundaries** (PlantUML) to group related elements within architectural boundaries 5. **For PlantUML**: Ensure every `Rel_*` direction is consistent with any `Lay_*` constraint on the same element pair (see layout conflict rules in c4-plantuml.md) ## Step 2: Determine the Diagram Type Based on the user's request and available artifacts, select the appropriate diagram type: ### Mode A: C4 Context Diagram (Level 1) **Purpose**: Show system in context with users and external systems **When to Use**: - Starting a new project (after requirements phase) - Stakeholder communication (non-technical audience) - Understanding system boundaries - No detailed technical design yet **Input**: Requirements (especially BR, INT requirements) **Mermaid Syntax**: Use `C4Context` diagram **Example**: ```mermaid C4Context title System Context - Payment Gateway Person(customer, "Customer", "User making payments") Person(admin, "Administrator", "Manages system") System(paymentgateway, "Payment Gateway", "Processes payments via multiple providers") System_Ext(stripe, "Stripe", "Payment processor") System_Ext(paypal, "PayPal", "Payment processor") System_Ext(bank, "Bank System", "Customer bank account") System_Ext(fraud, "Fraud Detection Service", "Third-party fraud detection") Rel(customer, paymentgateway, "Makes payment", "HTTPS") Rel(admin, paymentgateway, "Configures", "HTTPS") Rel(paymentgateway, stripe, "Processes via", "API") Rel(paymentgateway, paypal, "Processes via", "API") Rel(paymentgateway, fraud, "Checks transaction", "API") Rel(stripe, bank, "Transfers money", "Bank network") Rel(paypal, bank, "Transfers money", "Bank network") ``` **PlantUML C4 Example** (if PlantUML format selected): ```plantuml @startuml !include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml title System Context - Payment Gateway Person(customer, "Customer", "User making payments") Person(admin, "Administrator", "Manages system") System(paymentgateway, "Payment Gateway", "Processes payments via multiple providers") System_Ext(stripe, "Stripe", "Payment processor") System_Ext(paypal, "PayPal", "Payment processor") System_Ext(bank, "Bank System", "Customer bank account") System_Ext(fraud, "Fraud Detection Service", "Third-party fraud detection") Rel_Down(customer, paymentgateway, "Makes payment", "HTTPS") Rel_Down(admin, paymentgateway, "Configures", "HTTPS") Rel_Right(paymentgateway, stripe, "Processes via", "API") Rel_Right(paymentgateway, paypal, "Processes via", "API") Rel_Right(paymentgateway, fraud, "Checks transaction", "API") Rel_Down(stripe, bank, "Transfers money", "Bank network") Rel_Down(paypal, bank, "Transfers money", "Bank network") Lay_Right(stripe, paypal) Lay_Right(paypal, fraud) @enduml ``` ### Mode B: C4 Container Diagram (Level 2) **Purpose**: Show technical containers and technology choices **When to Use**: - After HLD phase - Reviewing vendor proposals - Understanding technical architecture - Technology selection decisions **Input**: HLD, requirements (NFR), Wardley Map **Mermaid Syntax**: Use `C4Container` diagram **Example**: ```mermaid C4Container title Container Diagram - Payment Gateway Person(customer, "Customer", "User") System_Ext(stripe, "Stripe", "Payment processor") System_Ext(paypal, "PayPal", "Payment processor") System_Boundary(pg, "Payment Gateway") { Container(web, "Web Application", "React, TypeScript", "User interface, WCAG 2.2 AA") Container(api, "Payment API", "Node.js, Express", "RESTful API, 10K TPS") Container(orchestrator, "Payment Orchestrator", "Python", "Multi-provider routing [Custom 0.42]") Container(fraud, "Fraud Detection", "Python, scikit-learn", "Real-time fraud scoring [Custom 0.35]") ContainerDb(db, "Database", "PostgreSQL RDS", "Transaction data [Commodity 0.95]") Container(queue, "Message Queue", "RabbitMQ", "Async processing [Commodity 0.90]") Container(cache, "Cache", "Redis", "Session & response cache [Commodity 0.92]") } Rel(customer, web, "Uses", "HTTPS") Rel(web, api, "Calls", "REST/JSON") Rel(api, orchestrator, "Routes to", "") Rel(api, fraud, "Checks", "gRPC") Rel(orchestrator, stripe, "Processes via", "API") Rel(orchestrator, paypal, "Processes via", "API") Rel(api, db, "Reads/Writes", "SQL") Rel(api, queue, "Publishes", "AMQP") Rel(api, cache, "Gets/Sets", "Redis Protocol") ``` **PlantUML C4 Example** (if PlantUML format selected): ```plantuml @startuml !include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml title Container Diagram - Payment Gateway Person(customer, "Customer", "User") System_Ext(stripe, "Stripe", "Payment processor") System_Ext(paypal, "PayPal", "Payment processor") System_Boundary(pg, "Payment Gateway") { Container(web, "Web Application", "React, TypeScript", "User interface, WCAG 2.2 AA") Container(api, "Payment API", "Node.js, Express", "RESTful API, 10K TPS") Container(orchestrator, "Payment Orchestrator", "Python", "Multi-provider routing [Custom 0.42]") Container(fraud, "Fraud Detection", "Python, scikit-learn", "Real-time fraud scoring [Custom 0.35]") ContainerDb(db, "Database", "PostgreSQL RDS", "Transaction data [Commodity 0.95]") ContainerQueue(queue, "Message Queue", "RabbitMQ", "Async processing [Commodity 0.90]") Container(cache, "Cache", "Redis", "Session & response cache [Commodity 0.92]") } Rel_Down(customer, web, "Uses", "HTTPS") Rel_Right(web, api, "Calls", "REST/JSON") Rel_Right(api, orchestrator, "Routes to") Rel_Down(api, fraud, "Checks", "gRPC") Rel_Right(orchestrator, stripe, "Processes via", "API") Rel_Right(orchestrator, paypal, "Processes via", "API") Rel_Down(api, db, "Reads/Writes", "SQL") Rel_Down(api, queue, "Publishes", "AMQP") Rel_Down(api, cache, "Gets/Sets", "Redis Protocol") Lay_Right(web, api) Lay_Right(api, orchestrator) Lay_Right(db, queue) Lay_Right(queue, cache) @enduml ``` **Note**: Include evolution stage from Wardley Map in square brackets [Custom 0.42] ### Mode C: C4 Component Diagram (Level 3) **Purpose**: Show internal components within a container **When to Use**: - After DLD phase - Implementation planning - Understanding component responsibilities - Code structure design **Input**: DLD, component specifications **Mermaid Syntax**: Use `C4Component` diagram **Example**: ```mermaid C4Component title Component Diagram - Payment API Container Container_Boundary(api, "Payment API") { Component(router, "API Router", "Express Router", "Routes requests to handlers") Component(paymentHandler, "Payment Handler", "Controller", "Handles payment requests") Component(authHandler, "Auth Handler", "Middleware", "JWT validation") Component(validationHandler, "Validation Handler", "Middleware", "Request validation") Component(paymentService, "Payment Service", "Business Logic", "Payment processing logic") Component(fraudService, "Fraud Service Client", "Service", "Calls fraud detection") Component(providerService, "Provider Service", "Business Logic", "Provider integration") Component(paymentRepo, "Payment Repository", "Data Access", "Database operations") Component(queuePublisher, "Queue Publisher", "Infrastructure", "Publishes events") ComponentDb(db, "Database", "PostgreSQL", "Transaction data") Component_Ext(queue, "Message Queue", "RabbitMQ", "Event queue") } Rel(router, authHandler, "Authenticates with") Rel(router, validationHandler, "Validates with") Rel(router, paymentHandler, "Routes to") Rel(paymentHandler, paymentService, "Uses") Rel(paymentService, fraudService, "Checks fraud") Rel(paymentService, providerService, "Processes payment") Rel(paymentService, paymentRepo, "Persists") Rel(paymentService, queuePublisher, "Publishes events") Rel(paymentRepo, db, "Reads/Writes", "SQL") Rel(queuePublisher, queue, "Publishes", "AMQP") ``` **PlantUML C4 Example** (if PlantUML format selected): ```plantuml @startuml !include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Component.puml title Component Diagram - Payment API Container Container_Boundary(api, "Payment API") { Component(router, "API Router", "Express Router", "Routes requests to handlers") Component(paymentHandler, "Payment Handler", "Controller", "Handles payment requests") Component(authHandler, "Auth Handler", "Middleware", "JWT validation") Component(validationHandler, "Validation Handler", "Middleware", "Request validation") Component(paymentService, "Payment Service", "Business Logic", "Payment processing logic") Component(fraudService, "Fraud Service Client", "Service", "Calls fraud detection") Component(providerService, "Provider Service", "Business Logic", "Provider integration") Component(paymentRepo, "Payment Repository", "Data Access", "Database operations") Component(queuePublisher, "Queue Publisher", "Infrastructure", "Publishes events") ComponentDb(db, "Database", "PostgreSQL", "Transaction data") Component_Ext(queue, "Message Queue", "RabbitMQ", "Event queue") } Rel_Right(router, authHandler, "Authenticates with") Rel_Right(router, validationHandler, "Validates with") Rel_Down(router, paymentHandler, "Routes to") Rel_Down(paymentHandler, paymentService, "Uses") Rel_Right(paymentService, fraudService, "Checks fraud") Rel_Right(paymentService, providerService, "Processes payment") Rel_Down(paymentService, paymentRepo, "Persists") Rel_Down(paymentService, queuePublisher, "Publishes events") Rel_Down(paymentRepo, db, "Reads/Writes", "SQL") Rel_Down(queuePublisher, queue, "Publishes", "AMQP") Lay_Right(authHandler, validationHandler) Lay_Right(fraudService, providerService) Lay_Right(paymentRepo, queuePublisher) @enduml ``` ### Mode D: Deployment Diagram **Purpose**: Show infrastructure topology and cloud resources **When to Use**: - Cloud-first compliance (TCoP Point 5) - Infrastructure planning - Security zone design - DevOps / SRE discussions **Input**: HLD, NFR (performance, security), TCoP assessment **Mermaid Syntax**: Use `flowchart` with subgraphs **Example**: ```mermaid flowchart TB subgraph Internet["Internet"] Users[Users/Customers] end subgraph AWS["AWS Cloud - eu-west-2"] subgraph VPC["VPC 10.0.0.0/16"] subgraph PublicSubnet["Public Subnet 10.0.1.0/24"] ALB[Application Load Balancer
Target: 99.99% availability] NAT[NAT Gateway] end subgraph PrivateSubnet1["Private Subnet 10.0.10.0/24 (AZ1)"] EC2_1[EC2 Auto Scaling Group
t3.large, Min: 2, Max: 10] RDS_Primary[(RDS PostgreSQL Primary
db.r5.xlarge)] end subgraph PrivateSubnet2["Private Subnet 10.0.20.0/24 (AZ2)"] EC2_2[EC2 Auto Scaling Group
t3.large, Min: 2, Max: 10] RDS_Standby[(RDS PostgreSQL Standby
db.r5.xlarge)] end end S3[(S3 Bucket
Transaction Logs)] CloudWatch[CloudWatch
Monitoring & Alerts] end Users -->|HTTPS:443| ALB ALB -->|HTTP:8080| EC2_1 ALB -->|HTTP:8080| EC2_2 EC2_1 -->|PostgreSQL:5432| RDS_Primary EC2_2 -->|PostgreSQL:5432| RDS_Primary RDS_Primary -.->|Sync Replication| RDS_Standby EC2_1 -->|Logs| S3 EC2_2 -->|Logs| S3 EC2_1 -->|Metrics| CloudWatch EC2_2 -->|Metrics| CloudWatch EC2_1 -->|NAT| NAT EC2_2 -->|NAT| NAT NAT -->|Internet Access| Internet classDef aws fill:#FF9900,stroke:#232F3E,color:#232F3E classDef compute fill:#EC7211,stroke:#232F3E,color:#fff classDef database fill:#3B48CC,stroke:#232F3E,color:#fff classDef storage fill:#569A31,stroke:#232F3E,color:#fff classDef network fill:#8C4FFF,stroke:#232F3E,color:#fff class AWS,VPC,PublicSubnet,PrivateSubnet1,PrivateSubnet2 aws class EC2_1,EC2_2 compute class RDS_Primary,RDS_Standby database class S3 storage class ALB,NAT network ``` ### Mode E: Sequence Diagram **Purpose**: Show API interactions and request/response flows **When to Use**: - API design and review - Integration requirements (INT) - Understanding interaction patterns - Error handling flows **Input**: Requirements (INT), HLD/DLD (API specifications) **Mermaid Syntax**: Use `sequenceDiagram` **Mermaid Example**: ```mermaid sequenceDiagram participant Customer participant WebApp participant API participant FraudDetection participant PaymentOrchestrator participant Stripe participant Database participant MessageQueue Customer->>WebApp: Enter payment details WebApp->>API: POST /api/v1/payments
{amount, card, merchant} API->>API: Validate request (JWT, schema) alt Invalid request API-->>WebApp: 400 Bad Request WebApp-->>Customer: Show error end API->>FraudDetection: POST /fraud/check
{card, amount, customer} FraudDetection-->>API: {risk_score: 0.15, approved: true} alt High fraud risk API-->>WebApp: 403 Forbidden (fraud detected) WebApp-->>Customer: Transaction blocked end API->>PaymentOrchestrator: processPayment(details) PaymentOrchestrator->>Stripe: POST /v1/charges
{amount, token} alt Stripe success Stripe-->>PaymentOrchestrator: {charge_id, status: succeeded} PaymentOrchestrator-->>API: {success: true, transaction_id} API->>Database: INSERT INTO transactions Database-->>API: Transaction saved API->>MessageQueue: PUBLISH payment.completed API-->>WebApp: 200 OK {transaction_id} WebApp-->>Customer: Payment successful else Stripe failure Stripe-->>PaymentOrchestrator: {error, status: failed} PaymentOrchestrator-->>API: {success: false, error} API->>Database: INSERT INTO failed_transactions API-->>WebApp: 402 Payment Required WebApp-->>Customer: Payment failed, try again end ``` **PlantUML Syntax**: Use `@startuml` / `@enduml` with `actor`, `participant`, `database` stereotypes **PlantUML Example**: ```plantuml @startuml title Payment Processing Flow actor Customer participant "Web App" as WebApp participant "Payment API" as API participant "Fraud Detection" as FraudDetection participant "Payment Orchestrator" as PaymentOrchestrator participant "Stripe" as Stripe database "Database" as Database queue "Message Queue" as MessageQueue Customer -> WebApp: Enter payment details WebApp -> API: POST /api/v1/payments\n{amount, card, merchant} API -> API: Validate request (JWT, schema) alt Invalid request API --> WebApp: 400 Bad Request WebApp --> Customer: Show error end API -> FraudDetection: POST /fraud/check\n{card, amount, customer} FraudDetection --> API: {risk_score: 0.15, approved: true} alt High fraud risk API --> WebApp: 403 Forbidden (fraud detected) WebApp --> Customer: Transaction blocked end API -> PaymentOrchestrator: processPayment(details) PaymentOrchestrator -> Stripe: POST /v1/charges\n{amount, token} alt Stripe success Stripe --> PaymentOrchestrator: {charge_id, status: succeeded} PaymentOrchestrator --> API: {success: true, transaction_id} API -> Database: INSERT INTO transactions Database --> API: Transaction saved API -> MessageQueue: PUBLISH payment.completed API --> WebApp: 200 OK {transaction_id} WebApp --> Customer: Payment successful else Stripe failure Stripe --> PaymentOrchestrator: {error, status: failed} PaymentOrchestrator --> API: {success: false, error} API -> Database: INSERT INTO failed_transactions API --> WebApp: 402 Payment Required WebApp --> Customer: Payment failed, try again end @enduml ``` ### Mode F: Data Flow Diagram **Purpose**: Show how data moves through the system **When to Use**: - Data requirements (DR) - GDPR / UK GDPR compliance - PII handling and data residency - Data transformation pipelines **Input**: Requirements (DR), DLD (data models), TCoP/GDPR assessments **Mermaid Syntax**: Use `flowchart` with data emphasis **Example**: ```mermaid flowchart LR subgraph Sources["Data Sources"] Customer["Customer Input
PII: Name, Email, Card"] Merchant["Merchant Data
PII: Business details"] end subgraph Processing["Payment Gateway Processing"] WebApp["Web Application
Tokenize card
Encrypt PII"] API["Payment API
Validate PII
Hash email
Pseudonymize ID"] Fraud["Fraud Detection
Risk scoring
Retention: 90 days"] end subgraph Storage["Data Storage"] Database[("Database
PII: Name, email
Legal Basis: Contract
Retention: 7 years
AES-256")] LogStorage[("S3 Logs
PII: None
Retention: 90 days")] end subgraph External["External Systems"] Stripe["Stripe
PII: Tokenized card
UK Residency: Yes"] BI["Analytics/BI
PII: Anonymized only"] end Customer -->|HTTPS/TLS 1.3| WebApp Merchant -->|HTTPS/TLS 1.3| WebApp WebApp -->|Encrypted| API API -->|Hashed PII| Fraud API -->|Encrypted SQL| Database API -->|Sanitized logs| LogStorage API -->|Tokenized card| Stripe Database -->|Anonymized aggregates| BI style Customer fill:#FFE6E6 style Merchant fill:#FFE6E6 style Database fill:#E6F3FF style Stripe fill:#FFF4E6 ``` ## Step 3: Generate the Diagram ### Component Identification From requirements and architecture artifacts, identify: 1. **Actors** (for Context diagrams): - Users (Customer, Admin, Operator) - External systems - Third-party services 2. **Containers** (for Container diagrams): - Web applications - APIs and services - Databases - Message queues - Caching layers - External systems 3. **Components** (for Component diagrams): - Controllers and handlers - Business logic services - Data access repositories - Infrastructure components 4. **Infrastructure** (for Deployment diagrams): - Cloud provider (AWS/Azure/GCP) - VPCs, subnets, security groups - Load balancers - Compute instances (EC2, containers) - Managed services (RDS, S3, etc.) 5. **Data flows** (for Data Flow diagrams): - Data sources - Processing steps - Storage locations - PII handling points - Data transformations ### Include Strategic Context For each component, annotate with: **From Wardley Map** (if available): - Evolution stage: [Genesis 0.15], [Custom 0.42], [Product 0.70], [Commodity 0.95] - Build/Buy decision: BUILD, BUY, USE, REUSE **From Requirements**: - NFR targets: "10K TPS", "99.99% availability", "Sub-200ms response" - Compliance: "PCI-DSS Level 1", "UK GDPR", "WCAG 2.2 AA" **From UK Government** (if applicable): - GOV.UK services: "GOV.UK Notify", "GOV.UK Pay", "GOV.UK Design System" - TCoP compliance: "Cloud First (AWS)", "Open Source (PostgreSQL)" - AI Playbook: "HIGH-RISK AI - Human-in-the-loop", "Bias testing required" ### Mermaid Syntax Guidelines **Best Practices**: 1. Use clear, descriptive labels 2. Include technology choices (e.g., "Node.js, Express") 3. Show protocols (e.g., "HTTPS", "REST/JSON", "SQL") 4. Indicate directionality with arrows (-> for uni-directional, <--> for bi-directional) 5. Use subgraphs for logical grouping 6. Add notes for critical decisions or constraints 7. Keep diagrams focused (split large diagrams into multiple smaller ones) 8. **IMPORTANT - Mermaid Syntax for Line Breaks**: - **C4 Diagrams**: Support `
` tags in BOTH node labels AND edge labels - ✅ `Person(user, "User
(Role)")` - WORKS - ✅ `Rel(user, api, "Uses
HTTPS")` - WORKS - **Flowcharts/Sequence/Deployment**: Support `
` tags in node labels ONLY, NOT in edge labels - ✅ `Node["User
(Role)"]` - WORKS in node labels - ❌ `Node -->|Uses
HTTPS| Other` - FAILS (causes "Parse error - Expecting 'SQE', got 'PIPE'") - ✅ `Node -->|Uses via HTTPS, JWT auth| Other` - WORKS (use comma-separated text in edge labels) - **Best Practice**: For flowcharts, always use comma-separated text in edge labels, never `
` tags **C4 Diagram Syntax**: - `Person(id, "Label", "Description")` - User or actor - `System(id, "Label", "Description")` - Your system - `System_Ext(id, "Label", "Description")` - External system - `Container(id, "Label", "Technology", "Description")` - Technical container - `ContainerDb(id, "Label", "Technology", "Description")` - Database container - `Component(id, "Label", "Technology", "Description")` - Internal component - `Rel(from, to, "Label", "Protocol")` - Relationship - `System_Boundary(id, "Label")` - System boundary **Flowchart Syntax** (for Deployment/Data Flow): - `subgraph Name["Display Name"]` - Logical grouping - `Node[Label]` - Standard node - `Node[(Label)]` - Database/storage - `-->` - Arrow with label - `-.->` - Dotted arrow (async, replication) - `classDef` - Styling ### PlantUML C4 Syntax Guidelines (C4 types only) When PlantUML format is selected, use the C4-PlantUML library. Refer to `c4-layout-science.md` Section 7 (already loaded at Step 1d) for full details. **Include URLs** (one per diagram type): - Context: `!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml` - Container: `!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml` - Component: `!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Component.puml` **Element Syntax** (same names as Mermaid C4): - `Person(id, "Label", "Description")` - User or actor - `System(id, "Label", "Description")` - Your system - `System_Ext(id, "Label", "Description")` - External system - `System_Boundary(id, "Label")` - System boundary - `Container(id, "Label", "Technology", "Description")` - Technical container - `ContainerDb(id, "Label", "Technology", "Description")` - Database container - `ContainerQueue(id, "Label", "Technology", "Description")` - Message queue (PlantUML-only) - `Component(id, "Label", "Technology", "Description")` - Internal component - `ComponentDb(id, "Label", "Technology", "Description")` - Database component - `Component_Ext(id, "Label", "Technology", "Description")` - External component - `Container_Boundary(id, "Label")` - Container boundary **Directional Relationships** (use instead of generic `Rel`): - `Rel_Down(from, to, "Label", "Protocol")` - Places source above target (hierarchical tiers) - `Rel_Right(from, to, "Label", "Protocol")` - Places source left of target (horizontal flow) - `Rel_Up(from, to, "Label", "Protocol")` - Places source below target (callbacks) - `Rel_Left(from, to, "Label", "Protocol")` - Reverse horizontal flow - `Rel_Neighbor(from, to, "Label", "Protocol")` - Forces adjacent placement **Invisible Layout Constraints** (no visible arrow): - `Lay_Right(a, b)` - Forces a to appear left of b (tier alignment) - `Lay_Down(a, b)` - Forces a to appear above b (vertical alignment) **Best Practice**: Every relationship should use a directional variant (`Rel_Down`, `Rel_Right`, etc.) rather than generic `Rel`. Add `Lay_Right`/`Lay_Down` constraints to align elements within the same tier. ## Step 4: Generate the Output Create the architecture diagram document using the template: **File Location**: `projects/{project_number}-{project_name}/diagrams/ARC-{PROJECT_ID}-DIAG-{NNN}-v1.0.md` **Naming Convention**: - `ARC-001-DIAG-001-v1.0.md` - First diagram (e.g., C4 context) - `ARC-001-DIAG-002-v1.0.md` - Second diagram (e.g., C4 container) - `ARC-001-DIAG-003-v1.0.md` - Third diagram (e.g., C4 component) **Read the template** (with user override support): - **First**, check if `.arckit/templates-custom/architecture-diagram-template.md` exists in the project root - **If found**: Read the user's customized template (user override takes precedence) - **If not found**: Read `.arckit/templates/architecture-diagram-template.md` (default) - **Then read** `.arckit/templates/_partials/RENDERING.md` and resolve the `` marker in the template before writing. Do not hand-write the Document Control table: the partial `RENDERING.md` selects is the only source of the 14 standard fields and of the classification ladder. > **Tip**: Users can customize templates with `$arckit-customize diagram` --- **CRITICAL - Auto-Populate Document Control Fields**: Before completing the document, populate ALL document control fields in the header: **Construct Document ID**: - **Document ID**: `ARC-{PROJECT_ID}-DIAG-{NNN}-v{VERSION}` (e.g., `ARC-001-DIAG-001-v1.0`) - Sequence number `{NNN}`: Check existing files in `diagrams/` and use the next number (001, 002, ...) **Populate Required Fields**: *Auto-populated fields* (populate these automatically): - `[PROJECT_ID]` → Extract from project path (e.g., "001" from "projects/001-project-name") - `[VERSION]` → "1.0" (or increment if previous version exists) - `[DATE]` / `[YYYY-MM-DD]` → Current date in YYYY-MM-DD format - `[DOCUMENT_TYPE_NAME]` → "Architecture Diagram" - `ARC-[PROJECT_ID]-DIAG-v[VERSION]` → Construct using format above - `[COMMAND]` → "arckit.diagram" *User-provided fields* (extract from project metadata or user input): - `[PROJECT_NAME]` → Full project name from project metadata or user input - `[OWNER_NAME_AND_ROLE]` → Document owner (prompt user if not in metadata) - **Classification** → comes from the resolved Document Control header, not from a placeholder. `_partials/RENDERING.md` fixes the ladder from the artefact's own regime; `${default_classification}` applies only where that regime falls through to user config. *Calculated fields*: - `[YYYY-MM-DD]` for Next Review Date → Current date + 30 days *Pending fields* (leave as [PENDING] until manually updated): - `[REVIEWER_NAME]` → [PENDING] - `[APPROVER_NAME]` → [PENDING] - `[DISTRIBUTION_LIST]` → Default to "Project Team, Architecture Team" or [PENDING] **Populate Revision History**: ```markdown | 1.0 | {DATE} | ArcKit AI | Initial creation from `$arckit-diagram` command | [PENDING] | [PENDING] | ``` **Populate Generation Metadata Footer**: The footer should be populated with: ```markdown **Generated by**: ArcKit `$arckit-diagram` command **Generated on**: {DATE} {TIME} GMT **ArcKit Version**: {ARCKIT_VERSION} **Project**: {PROJECT_NAME} (Project {PROJECT_ID}) **AI Model**: [Use actual model name, e.g., "Claude Sonnet 5 (session default)"] **Generation Context**: [Brief note about source documents used] ``` --- ### Output Format The diagram code block format depends on the selected output format: **Mermaid** (default): - Use ` ```mermaid ` code block - Complete, valid Mermaid syntax - Renders in GitHub markdown, VS Code (Mermaid Preview extension), https://mermaid.live **PlantUML C4** (C4 types only, when selected): - Use ` ```plantuml ` code block - Wrap in `@startuml` / `@enduml` - Include the appropriate C4 library URL (`!include`) - Use directional relationships (`Rel_Down`, `Rel_Right`) throughout - Add `Lay_Right`/`Lay_Down` constraints for tier alignment - **Does NOT render in GitHub markdown or ArcKit Pages** — users render externally via: - **PlantUML Server**: https://www.plantuml.com/plantuml/uml/ (paste code) - **VS Code**: Install PlantUML extension (jebbs.plantuml) - **CLI**: `java -jar plantuml.jar diagram.puml` ### Output Contents The diagram document must include: 1. **Diagram Code** (Mermaid or PlantUML): - Complete, valid syntax for the selected format - For Mermaid: renders in GitHub markdown, viewable at https://mermaid.live - For PlantUML: renders at https://www.plantuml.com/plantuml/uml/ or via VS Code extension 2. **Component Inventory**: - All components listed in table format - Technology choices - Responsibilities - Evolution stage (from Wardley Map) - Build/Buy decision 3. **Architecture Decisions**: - Key design decisions with rationale - Technology choices and justification - Trade-offs considered 4. **Requirements Traceability**: - Link components to requirements (BR, FR, NFR, INT, DR) - Coverage analysis - Gap identification 5. **Integration Points**: - External systems and APIs - Protocols and data formats - SLAs and dependencies 6. **Data Flow** (if relevant): - Data sources and sinks - PII handling (UK GDPR compliance) - Data retention and deletion policies 7. **Security Architecture**: - Security zones - Authentication/authorisation - Security controls 8. **Deployment Architecture** (for deployment diagrams): - Cloud provider and region - Network architecture - HA and backup strategy 9. **NFR Coverage**: - Performance targets and how achieved - Scalability approach - Availability and resilience 10. **UK Government Compliance** (if applicable): - TCoP point compliance - GOV.UK services used - AI Playbook compliance (for AI systems) 11. **Wardley Map Integration**: - Component positioning by evolution - Strategic alignment check - Build/Buy validation 12. **Linked Artifacts**: - Requirements document - HLD/DLD - Wardley Map - TCoP/AI Playbook assessments ## Step 5: Validation Before finalizing, validate the diagram: ### Technical Validation (Mermaid) - [ ] Mermaid syntax is valid (test at https://mermaid.live) - [ ] All components are properly labeled - [ ] Relationships show directionality correctly - [ ] Technology choices match HLD/requirements - [ ] Protocols and data formats specified ### Technical Validation (PlantUML C4 — when PlantUML format selected) - [ ] Valid PlantUML syntax (test at https://www.plantuml.com/plantuml/uml/) - [ ] Correct `!include` URL for diagram type (C4_Context, C4_Container, or C4_Component) - [ ] All relationships use directional variants (`Rel_Down`, `Rel_Right`, etc.) — no generic `Rel` - [ ] `Lay_Right`/`Lay_Down` constraints present for tier alignment - [ ] `@startuml` / `@enduml` wrappers present - [ ] All components are properly labeled - [ ] Technology choices match HLD/requirements ### Requirements Validation - [ ] All integration requirements (INT) are shown - [ ] NFR targets are annotated - [ ] External systems match requirements - [ ] Data requirements (DR) are reflected ### Strategic Validation (Wardley Map) - [ ] Evolution stages match Wardley Map - [ ] BUILD decisions align with Genesis/Custom stage - [ ] BUY decisions align with Product stage - [ ] USE decisions align with Commodity stage - [ ] No building commodity components ### UK Government Validation (if applicable) - [ ] GOV.UK services shown where used - [ ] Cloud First (TCoP Point 5) compliance visible - [ ] Open Source (TCoP Point 3) technologies noted - [ ] Share & Reuse (TCoP Point 8) demonstrated - [ ] HIGH-RISK AI components include human oversight ### Quality Checks - [ ] Diagram is readable and not cluttered - [ ] Labels are clear and descriptive - [ ] Grouping (subgraphs) is logical - [ ] Complexity is appropriate for audience - [ ] Split into multiple diagrams if too complex ## Step 5b: Element Count Thresholds Before evaluating quality, check element counts against these thresholds. If exceeded, split the diagram before proceeding to the quality gate. | Diagram Type | Max Elements | Rationale | Split Strategy | |-------------|-------------|-----------|----------------| | C4 Context | 10 | Stakeholder communication — must be instantly comprehensible | Split by domain boundary or system group | | C4 Container | 15 | Technical detail within one system boundary | Split by deployment unit or bounded context | | C4 Component | 12 per container | Internal structure of one container | Split by responsibility or layer | | Deployment | 15 | Infrastructure topology | Split by cloud region or availability zone | | Sequence | 8 lifelines | Interaction flow for one scenario | Split by phase (setup, processing, teardown) | | Data Flow | 12 | Data movement between stores and processes | Split by trust boundary or data domain | If the diagram exceeds these thresholds, split it at natural architectural boundaries and create a parent diagram showing the split points. ## Step 5c: Layout Direction Decision Select the primary layout di …(truncated)