opencode-skills-collection 3.0.46 → 3.0.48

package/bundled-skills/ecl-harness-engineer/references/architecture-diagrams.md

@@ -0,0 +1,420 @@
+# 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