playbook/antigravity-awesome-skills/skills/ecl-harness-engineer/references/architecture-diagrams.md

# Architecture Diagram Templates

Auto-generated Mermaid diagrams for visualizing codebase structure. These diagrams are derived
from actual code analysis — not hand-drawn, not aspirational. Every diagram should reflect
what the code **actually does**, not what the author wishes it did.

## Table of Contents

- [How to Generate Diagrams](#how-to-generate-diagrams)
- [Package Dependency Graph](#1-package-dependency-graph)
- [Data Flow Diagram](#2-data-flow-diagram)
- [Component Relationship Diagram](#3-component-relationship-diagram)
- [Call Hierarchy Diagram](#4-call-hierarchy-diagram)
- [Interface Implementation Map](#5-interface-implementation-map)
- [Module Boundary Diagram](#6-module-boundary-diagram)
- [Sequence Diagram for Key Flows](#7-sequence-diagram-for-key-flows)

---

## How to Generate Diagrams

Diagrams are generated by analyzing actual code, not by guessing. Follow this process:

### For Go projects
```bash
# List all packages and their imports
go list -json ./... | jq '{ImportPath, Imports}'

# Find interfaces and their implementations
grep -rn 'type.*interface' --include='*.go' .
grep -rn 'func.*) .*(' --include='*.go' . | head -50

# Map package dependencies
go list -m -json all
```

### For TypeScript/Node projects
```bash
# Find all imports
grep -rn "from ['\"]" --include='*.ts' src/

# Find interfaces and classes
grep -rn "export interface\|export class\|export type" --include='*.ts' src/

# Check package.json dependencies
cat package.json | jq '.dependencies, .devDependencies'
```

### For Python projects
```bash
# Find all imports
grep -rn "^from \|^import " --include='*.py' src/

# Find classes and their bases
grep -rn "class .*:" --include='*.py' src/

# Check dependency declarations
cat pyproject.toml  # or requirements.txt
```

After gathering this data, generate the appropriate Mermaid diagrams below.

---

## 1. Package Dependency Graph

Shows which packages depend on which. The most important diagram for understanding architecture.

### Template

````markdown
```mermaid
graph TD
    subgraph "Layer 5 — Entry Points"
        CMD[cmd/]
    end
    subgraph "Layer 4 — Interfaces"
        UI[ui/]
        SDK[sdk/]
        API[api/]
    end
    subgraph "Layer 3 — Business Logic"
        CORE[core/]
        SVC[services/]
    end
    subgraph "Layer 2 — Infrastructure"
        CFG[config/]
        LOG[logging/]
    end
    subgraph "Layer 1 — Utilities"
        UTIL[utils/]
    end
    subgraph "Layer 0 — Types"
        TYPES[types/]
    end

    CMD --> UI
    CMD --> API
    UI --> CORE
    SDK --> CORE
    API --> SVC
    CORE --> CFG
    CORE --> UTIL
    SVC --> CFG
    CFG --> TYPES
    UTIL --> TYPES
    LOG --> TYPES

    style TYPES fill:#e8f5e9
    style UTIL fill:#e3f2fd
    style CFG fill:#e3f2fd
    style LOG fill:#e3f2fd
    style CORE fill:#fff3e0
    style SVC fill:#fff3e0
    style UI fill:#fce4ec
    style SDK fill:#fce4ec
    style API fill:#fce4ec
    style CMD fill:#f3e5f5
```
````

### Generation Guidance

When generating this diagram from real code:

1. Run `go list -json ./...` (or equivalent for your language)
2. For each package, extract its internal imports
3. Group packages by their layer assignment (from lint-deps rules)
4. Draw edges for each internal import relationship
5. Color by layer level (green=L0, blue=L1-2, orange=L3, pink=L4, purple=L5)

Important: only include **internal** dependencies, not stdlib or third-party.

---

## 2. Data Flow Diagram

Shows how data moves through the system end-to-end.

### Template

````markdown
```mermaid
flowchart LR
    INPUT["User Input<br/><i>CLI args / HTTP request</i>"]
    PARSE["Parse & Validate<br/><code>cmd/parse.go</code>"]
    LOGIC["Business Logic<br/><code>core/processor.go</code>"]
    STORE["Storage Layer<br/><code>storage/db.go</code>"]
    OUTPUT["Output<br/><i>stdout / HTTP response</i>"]

    INPUT --> PARSE
    PARSE --> LOGIC
    LOGIC --> STORE
    STORE --> LOGIC
    LOGIC --> OUTPUT

    subgraph "Config"
        CFG["config/config.go"]
    end
    CFG -.-> PARSE
    CFG -.-> LOGIC
    CFG -.-> STORE
```
````

### Generation Guidance

To map data flow accurately:

1. Find entry points (`main()`, HTTP handlers, CLI command handlers)
2. Trace what happens to user input step by step
3. Note which files/functions are involved at each step — include the actual file path
4. Identify where data is transformed, stored, or returned
5. Show config/logging as dotted lines (support infrastructure, not primary flow)

---

## 3. Component Relationship Diagram

Shows the major components and their interactions. Best for projects with clear module boundaries.

### Template

````markdown
```mermaid
graph TB
    subgraph "Public API Surface"
        REST["REST API<br/><code>api/router.go:25</code>"]
        GRPC["gRPC Service<br/><code>api/grpc/server.go:18</code>"]
        CLI_CMD["CLI Commands<br/><code>cmd/root.go:42</code>"]
    end

    subgraph "Core Domain"
        AUTH["Auth Service<br/><code>core/auth/service.go:15</code>"]
        USER["User Service<br/><code>core/user/service.go:22</code>"]
        BILLING["Billing Engine<br/><code>core/billing/engine.go:30</code>"]
    end

    subgraph "Infrastructure"
        DB["Database<br/><code>infra/postgres/client.go:10</code>"]
        CACHE["Cache<br/><code>infra/redis/client.go:8</code>"]
        QUEUE["Message Queue<br/><code>infra/queue/producer.go:12</code>"]
    end

    REST --> AUTH
    REST --> USER
    GRPC --> BILLING
    CLI_CMD --> USER

    AUTH --> DB
    AUTH --> CACHE
    USER --> DB
    BILLING --> DB
    BILLING --> QUEUE
```
````

### Generation Guidance

1. Identify major service/component boundaries
2. For each component, find the primary file and line where it's defined
3. Map method calls between components (grep for cross-package function calls)
4. Group by architectural layer

---

## 4. Call Hierarchy Diagram

Shows the function call chain for critical code paths.

### Template

````markdown
```mermaid
graph TD
    A["main()<br/><code>main.go:15</code>"]
    B["cmd.Execute()<br/><code>cmd/root.go:42</code>"]
    C["runCommand()<br/><code>cmd/run.go:28</code>"]
    D["service.Process()<br/><code>core/service.go:55</code>"]
    E["validator.Check()<br/><code>core/validate.go:12</code>"]
    F["store.Save()<br/><code>storage/store.go:33</code>"]
    G["reporter.Output()<br/><code>output/report.go:20</code>"]

    A --> B
    B --> C
    C --> D
    D --> E
    D --> F
    D --> G
    E -->|"validation error"| C
    F -->|"storage error"| D
```
````

### Generation Guidance

1. Start from the entry point of the flow you want to document
2. Use LSP `outgoingCalls` to trace the call chain, or grep for function invocations
3. Include the file and line number for each function
4. Show error paths as labeled edges
5. Keep it to 8-12 nodes max — if more complex, split into sub-diagrams

---

## 5. Interface Implementation Map

Shows which types implement which interfaces. Critical for understanding extensibility.

### Template

````markdown
```mermaid
classDiagram
    class Provider {
        <<interface>>
        +Execute(ctx, input) Result, error
        +Name() string
        +SupportsStream() bool
    }

    class OpenAIProvider {
        -client *openai.Client
        -model string
        +Execute(ctx, input) Result, error
        +Name() string
        +SupportsStream() bool
    }

    class AnthropicProvider {
        -client *anthropic.Client
        -model string
        +Execute(ctx, input) Result, error
        +Name() string
        +SupportsStream() bool
    }

    class MockProvider {
        -responses []Result
        +Execute(ctx, input) Result, error
        +Name() string
        +SupportsStream() bool
    }

    Provider <|.. OpenAIProvider : implements
    Provider <|.. AnthropicProvider : implements
    Provider <|.. MockProvider : implements

    note for Provider "Defined in core/types/provider.go:18"
    note for OpenAIProvider "Defined in providers/openai/provider.go:25"
    note for AnthropicProvider "Defined in providers/anthropic/provider.go:22"
    note for MockProvider "Defined in testing/mock_provider.go:10"
```
````

### Generation Guidance

1. Find all interfaces: `grep -rn 'type.*interface' --include='*.go'`
2. Find implementations by matching method signatures
3. For each implementation, list its struct fields (private) and methods (public)
4. Add source file location as notes
5. Focus on the most important interfaces — don't try to diagram everything

---

## 6. Module Boundary Diagram

Shows public vs internal API surface. Useful for library/SDK projects.

### Template

````markdown
```mermaid
graph TB
    subgraph "Public API (exported)"
        PUB_TYPES["Types<br/><code>pkg/types.go</code><br/><i>Config, Options, Result</i>"]
        PUB_FUNC["Functions<br/><code>pkg/client.go</code><br/><i>New(), Run(), Close()</i>"]
        PUB_IFACE["Interfaces<br/><code>pkg/interfaces.go</code><br/><i>Provider, Store</i>"]
    end

    subgraph "Internal (unexported)"
        INT_CORE["Core Logic<br/><code>internal/core/</code>"]
        INT_PARSE["Parsing<br/><code>internal/parse/</code>"]
        INT_UTIL["Utilities<br/><code>internal/util/</code>"]
    end

    PUB_FUNC --> INT_CORE
    PUB_FUNC --> INT_PARSE
    INT_CORE --> INT_UTIL
    INT_PARSE --> INT_UTIL

    style PUB_TYPES fill:#c8e6c9
    style PUB_FUNC fill:#c8e6c9
    style PUB_IFACE fill:#c8e6c9
    style INT_CORE fill:#ffecb3
    style INT_PARSE fill:#ffecb3
    style INT_UTIL fill:#ffecb3
```
````

---

## 7. Sequence Diagram for Key Flows

Shows time-ordered interactions between components for specific user scenarios.

### Template

````markdown
```mermaid
sequenceDiagram
    participant User
    participant CLI as CLI (cmd/run.go)
    participant Auth as Auth Service (core/auth/)
    participant DB as Database (storage/)
    participant API as External API

    User->>CLI: run --project my-app
    CLI->>Auth: Authenticate(token)
    Auth->>DB: GetUser(token)
    DB-->>Auth: User{id, role}
    Auth-->>CLI: AuthResult{ok, user}
    CLI->>API: FetchProject("my-app")
    API-->>CLI: ProjectData{...}
    CLI-->>User: Display results
```
````

### Generation Guidance

1. Pick the 3-5 most common/important user flows
2. Trace the complete sequence from user input to final output
3. Include actual component names and file paths
4. Show both success and error paths
5. Keep each sequence to 10-15 messages max

---

## Diagram Selection Guide

Not every project needs all seven diagram types. Choose based on what matters:

| Project Type | Recommended Diagrams |
|---|---|
| CLI tool | Package Dependency, Data Flow, Call Hierarchy |
| Web API | Package Dependency, Component Relationship, Sequence |
| Library/SDK | Package Dependency, Interface Implementation, Module Boundary |
| Microservice | Component Relationship, Data Flow, Sequence |
| Monolith | Package Dependency, Component Relationship, Interface Implementation |

## Diagram Quality Checklist

Every generated diagram should pass these checks:

- [ ] **Grounded in code**: Every node references an actual file/package (not aspirational)
- [ ] **File references**: Include `code>file:line</code>` where possible
- [ ] **No orphan nodes**: Every node has at least one connection
- [ ] **Layered layout**: Higher-level components at top, lower at bottom
- [ ] **Color coding**: Consistent colors across diagrams in the same project
- [ ] **Reasonable size**: 5-15 nodes per diagram; split if larger
- [ ] **Updated date**: Note when the diagram was last regenerated