Architecture Doc

You are a technical documentation architect. The user wants to generate comprehensive architecture documentation with diagrams using Mermaid syntax.

What to check first

• Run npm list mermaid to verify Mermaid is installed for diagram generation
• Check if you have a docs/ or architecture/ directory structure already in place
• Verify your project has a README or existing documentation baseline

Steps

1. Create a dedicated docs/architecture.md file that will serve as the main architecture document
2. Define your system's core components using a Mermaid graph diagram with graph TD (top-down) syntax
3. Add a high-level system architecture diagram showing service boundaries using flowchart with subgraph blocks
4. Create a data flow diagram using graph LR (left-right) to show how information moves between components
5. Include a deployment architecture diagram showing environments, servers, and infrastructure relationships
6. Document each component with a brief description, responsibilities, and key dependencies in markdown below the diagrams
7. Add a sequence diagram showing critical user flows or API interactions using Mermaid sequenceDiagram
8. Generate HTML output using mermaid-cli with command: mmdc -i docs/architecture.md -o docs/architecture.html

Code

# System Architecture Documentation

## 1. High-Level System Architecture

\`\`\`mermaid
graph TD
    Client[Client Applications]
    API[API Gateway]
    Auth[Authentication Service]
    Core[Core Business Logic]
    DB[(Database)]
    Cache[Redis Cache]
    Queue[Message Queue]
    
    Client -->|HTTPS| API
    API -->|Validate Token| Auth
    API -->|Process Request| Core
    Core -->|Query/Update| DB
    Core -->|Get/Set| Cache
    Core -->|Publish Event| Queue
    Queue -->|Consume Event| Core
    
    style API fill:#4A90E2
    style Auth fill:#7B68EE
    style Core fill:#50C878
    style DB fill:#FF6B6B
    style Cache fill:#FFD700
    style Queue fill:#FF8C00
\`\`\`

## 2. Component Dependencies

\`\`\`mermaid
graph LR
    UI[UI Layer] -->|REST/GraphQL| API[API Layer]
    API -->|DTO Mapping| Service[Service Layer]
    Service -->|Domain Logic| Domain[Domain Layer]
    Domain -->|Persistence| Repo[Repository Layer]
    Repo -->|SQL Queries| DB[(PostgreSQL)]
    Service -->|Cache Check| Cache[Redis]
    Service -->|Async Jobs| Queue[RabbitMQ]
    
    style UI fill:#E8F5E9
    style API fill:#E3F2FD
    style Service fill:#FFF3E0
    style Domain fill:#F3E5F5
    style Repo fill:#FCE4EC

Note: this example was truncated in the source. See the GitHub repo for the latest full version.

Common Pitfalls

• Treating this skill as a one-shot solution — most workflows need iteration and verification
• Skipping the verification steps — you don't know it worked until you measure
• Applying this skill without understanding the underlying problem — read the related docs first

When NOT to Use This Skill

• When a simpler manual approach would take less than 10 minutes
• On critical production systems without testing in staging first
• When you don't have permission or authorization to make these changes

How to Verify It Worked

• Run the verification steps documented above
• Compare the output against your expected baseline
• Check logs for any warnings or errors — silent failures are the worst kind

Production Considerations

• Test in staging before deploying to production
• Have a rollback plan — every change should be reversible
• Monitor the affected systems for at least 24 hours after the change