generate

Architecture Overview

Generate a comprehensive architecture overview of the current project as a single markdown document with embedded Mermaid diagrams.

When to Use

• User asks for an architecture overview or diagram
• User wants to understand the project structure
• User wants to document the system design
• User asks for an architecture diagram

Prerequisites

None. Mermaid diagrams render natively in GitHub, GitLab, VS Code, and most markdown viewers.

Procedure

Step 1: Explore the Codebase

0. Do not just rely on architecture information in the README or docs — explore the actual codebase to understand the real structure. These files are often outdated or incomplete.
1. List the top-level directory structure.
2. Identify the primary language and framework (e.g., Swift/SwiftUI, TypeScript/React, Python/Django).
3. Scan key directories to understand the project layout:
   • Source directories (e.g., src/, Sources/, lib/, app/)
   • Test directories
   • Configuration files (package.json, Package.swift, build.gradle, etc.)
4. Read a representative sample of files from each directory to understand their purpose.

Step 2: Identify Architectural Layers

Classify the codebase into layers. Common patterns include:

Layer	Examples
Presentation / UI	Views, components, pages, screens, templates
Application / Services	Business logic, use cases, service classes, controllers
Domain / Models	Data models, entities, enums, value objects
Infrastructure / Persistence	Database access, API clients, file I/O, platform APIs
Helpers / Utilities	Shared helpers, extensions, date formatters, constants

Adapt the layers to match what the project actually uses — don't force a pattern that isn't there.

Step 3: Map Dependencies

Identify how layers depend on each other:

• Which layer calls which?
• What are the key entry points?
• Are there clear dependency boundaries or is it tightly coupled?

Step 4: Generate the Architecture Overview Markdown

Produce a single markdown file containing both the diagrams and the written overview. Use this structure:

# Architecture Overview: {Project Name}

## Project Summary

{One paragraph describing what the project is and its tech stack.}

## Architecture Diagram

{Layer overview mermaid diagram — see "Layer Overview Diagram" below.}

## Layer Descriptions

### {Layer 1 Name}
- **Purpose**: ...
- **Key files/classes**: ...
- **Dependencies**: ...

### {Layer 2 Name}
...

## Subsystem Details

### {Subsystem 1 Name}

{Brief description of this subsystem's responsibility.}

{Per-subsystem class diagram — see "Per-Subsystem Class Diagrams" below.}

### {Subsystem 2 Name}
...

## Data Flow

{Brief prose overview of how data moves through the system — a paragraph or numbered list describing the typical request/action flow through the layers.}

### {Flow 1 Name}

{One-sentence description of what triggers this flow.}

{Sequence diagram — see "Key Data Flow Sequence Diagrams" below.}

### {Flow 2 Name}
...

Layer Overview Diagram

Create a graph TD (top-down) mermaid diagram showing all subsystems/layers as nodes with dependency arrows between them.

Template:

```mermaid
graph TD
    classDef ui fill:#d0ebff,stroke:#1971c2,stroke-width:2px,color:#1971c2
    classDef services fill:#d3f9d8,stroke:#2b8a3e,stroke-width:2px,color:#2b8a3e
    classDef models fill:#e5dbff,stroke:#5f3dc4,stroke-width:2px,color:#5f3dc4
    classDef infra fill:#ffe3e3,stroke:#c92a2a,stroke-width:2px,color:#c92a2a
    classDef helpers fill:#fff3bf,stroke:#e67700,stroke-width:2px,color:#e67700

    UI["Presentation / UI<br/>Views, Components"]:::ui
    SVC["Services<br/>Business Logic"]:::services
    MDL["Models / Domain<br/>Entities, Enums"]:::models
    INF["Infrastructure<br/>DB, API Clients"]:::infra

    UI -->|"calls"| SVC
    SVC -->|"uses"| MDL
    SVC -->|"reads/writes"| INF
    INF -->|"persists"| MDL
```

Rules:

• One node per subsystem/layer. Use ["Name<br/>Short summary"] for multi-line labels.
• Apply the layer color with :::className using the classDef definitions above.
• Label every arrow with the relationship type: -->|"label"| for solid arrows, -.->|"label"| for dashed arrows (cross-subsystem or weak dependencies).
• Show dependency direction as caller -> callee.
• Adapt the layers and arrows to what the project actually has. Do not force the template layers if they don't exist.

Per-Subsystem Class Diagrams

For each major subsystem, create a classDiagram mermaid block showing the classes/interfaces within that subsystem and their relationships. Do not include helper/utility classes.

Template:

```mermaid
classDiagram
    class DrinkService {
        +addDrink()
        +deleteDrink()
        +fetchDrinks()
    }
    class GoalService {
        +getCurrentGoal()
        +updateGoal()
    }
    class DrinkEntry {
        +id: UUID
        +amount: Double
        +timestamp: Date
    }

    DrinkService --> DrinkEntry : manages 1:n
    DrinkService --> Liquid : uses
    GoalService ..> ExternalAPI : fetches from
```

Rules:

• List key methods and properties in each class (not exhaustive — focus on what matters for understanding architecture).
• Use annotations for special types: <<interface>>, <<enum>>, <<abstract>>, <<struct>>.
• Relationship arrows:
  • --> solid arrow for intra-subsystem dependencies.
  • ..> dashed arrow for cross-subsystem dependencies.
  • Label after : describes the relationship (e.g., : manages 1:n, : uses, : has, : creates, : inherits).
  • Include cardinality when it adds clarity (e.g., 1:n, 1:1, 0..n).
• Apply colors using style directives on individual nodes to match the layer color scheme:

  style DrinkService fill:#d3f9d8,stroke:#2b8a3e
  style GoalService fill:#d3f9d8,stroke:#2b8a3e
  

• If a subsystem has more than ~15 classes, split it into multiple diagrams grouped by responsibility.

Color Scheme

Use these colors consistently across all diagrams:

Layer Type	fill	stroke	Used in
UI / Presentation	#d0ebff	#1971c2	classDef ui, style
Services / Logic	#d3f9d8	#2b8a3e	classDef services, style
Models / Domain	#e5dbff	#5f3dc4	classDef models, style
Infrastructure / Persistence	#ffe3e3	#c92a2a	classDef infra, style
Helpers / Utilities	#fff3bf	#e67700	classDef helpers, style
Cross-subsystem reference	#f1f3f5	#868e96	dashed arrows (..>)

Key Data Flow Sequence Diagrams

Identify 1–3 key user interactions (e.g., creating a record, submitting a form, processing a request) and create a sequenceDiagram mermaid block for each. These show the runtime flow across layers — complementing the static class diagrams above.

Template:

```mermaid
sequenceDiagram
    actor User
    participant UI as QuickAddView
    participant SVC as DrinkService
    participant DB as SwiftData

    User->>UI: taps "Add Drink"
    UI->>SVC: addEntry(liquid, volume)
    SVC->>DB: insert(DrinkEntry)
    SVC->>DB: save()
    SVC-->>UI: DrinkEntry
    UI-->>User: updates summary
```

Rules:

• Use actor for the user/external trigger. Use participant for internal components (views, services, persistence, external APIs).
• Alias participants to short names for readability: participant SVC as DrinkService.
• Arrow types:
  • ->> solid arrow for synchronous calls (request).
  • -->> dashed arrow for returns/responses.
  • --) solid arrow with open head for async/fire-and-forget (e.g., scheduling a notification).
• Label every arrow with the method or action name.
• Use Note over or Note right of sparingly to clarify non-obvious behavior (e.g., "SwiftData @Query auto-updates UI").
• Use alt/else blocks for conditional paths only when they are essential to understanding the flow. Don't over-detail happy-path-only flows.
• Keep diagrams focused: 5–15 messages per diagram. If a flow is longer, split it or summarize sub-flows with a Note.
• Apply box coloring with box groups when it helps distinguish layers:

  box rgb(208,235,255) Presentation
  participant UI as QuickAddView
  end
  

  Use the same layer color scheme (hex values from the Color Scheme table, as rgb(r,g,b)).
• Avoid parentheses and special characters in arrow labels — they cause parse errors. Use plain text descriptions.
• Pick flows that cross multiple layers and reveal how the system works, not trivial single-layer operations.

Step 5: Save the Output

• Save the combined architecture overview as architecture-overview.md at the project root.
• If the file already exists, ask the user before overwriting.

Step 6: Self-Review & Validation

Phase A: Syntax Pre-flight

Re-read each mermaid code block and verify before rendering:

1. No reserved-word collisions. These words cannot be used as bare node IDs: end, graph, subgraph, style, class, classDef, click, callback, link, linkStyle. Wrap them in quotes or use alternative IDs (e.g., EndNode["End"] instead of end).
2. Special characters are quoted. Node labels containing parentheses, brackets, braces, or other special characters must use the ["..."] syntax.
3. All quotes are balanced. Every opening " has a matching close.
4. Arrow syntax is correct. --> for solid, -.-> for dashed, -->|"label"| for labeled arrows in graph. --> and ..> with : label in classDiagram.
5. classDef is only used in graph diagrams. For classDiagram, use per-node style directives instead.
6. Line breaks use <br/> in graph node labels (not \n).

Phase B: Syntax Validation

Run the mermaid CLI to validate all diagrams parse correctly:

npx -y @mermaid-js/mermaid-cli -i architecture-overview.md -o /tmp/mermaid-validation.md -q

Fix any syntax errors and re-run until all diagrams pass (look for ✅ per diagram).

Phase C: Visual Review

Render all diagrams to PNG at 2x scale for readability, then visually inspect each one:

npx -y @mermaid-js/mermaid-cli -i architecture-overview.md -o /tmp/mermaid-review.md -e png -s 2 -q

This produces numbered PNG files (/tmp/mermaid-review-1.png, /tmp/mermaid-review-2.png, etc.) — one per mermaid block in document order. Read each PNG image using the Read tool and check for:

• Readability: text is large enough to read; no labels are tiny or squished
• No overlaps: labels, arrows, and nodes do not overlap or obscure each other
• No clipping: all content is fully visible, nothing cut off at diagram edges
• Logical layout: nodes are arranged in a sensible order (e.g., tab 1/2/3 left-to-right, caller above callee)
• Color correctness: layer colors are distinguishable and match the intended scheme
• Arrow clarity: arrows connect the right nodes and labels are positioned near their arrows

If any issues are found, edit the mermaid source in architecture-overview.md to fix them (e.g., shorten long labels, split an overcrowded diagram, reorder node declarations to hint better layout), then re-render and re-check the affected diagrams.

Phase D: Content Review

Verify the output against the quality checklist below.

Quality Checklist

• Layer overview diagram shows all subsystems/layers with dependency arrows
• Each major subsystem has its own class diagram section
• Helper/utility classes are excluded from class diagrams
• Arrow labels describe relationship type (uses, has, creates, 1:n, etc.)
• Cross-subsystem dependencies use dashed arrows (..> or -.->)
• Layer colors follow the color scheme table
• Arrows show correct dependency direction (caller -> callee)
• The overview matches what the code actually does, not what it should do
• All mermaid blocks use valid syntax (no reserved-word conflicts, balanced quotes)
• Node IDs do not collide with mermaid reserved words
• Diagrams are not excessively large (split if >15 classes per diagram)
• Project summary, layer descriptions, and data flow sections are filled in
• 1–3 key data flows have sequence diagrams showing runtime interactions across layers
• Sequence diagram participants match actual class/component names from the codebase
• Sequence diagram arrow labels use plain text without parentheses or special characters
• All diagrams rendered to PNG and visually reviewed for readability
• No overlapping or clipped text in rendered diagrams