📦 deps(thirdparty): update snapshots
This commit is contained in:
ci[bot]
+420
@@ -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
|
||||
Reference in New Issue
Block a user