From architecture-documentation
Generates technical architecture documentation from codebases with system diagrams, data flow analysis, component deep dives, and architectural decisions. Use when analyzing codebases for documentation, system design docs, technical handoffs, or architecture reviews.
npx claudepluginhub dha201/architecture-documentation-plugin --plugin architecture-documentationThis skill uses the workspace's default tool permissions.
Generates in-depth technical architecture documentation from codebases. Produces engineer-focused documentation with system diagrams, data flow analysis, component deep dives, and architectural decision rationale.
Creates new Angular apps using Angular CLI with flags for routing, SSR, SCSS, prefixes, and AI config. Follows best practices for modern TypeScript/Angular development. Use when starting Angular projects.
Generates Angular code and provides architectural guidance for projects, components, services, reactivity with signals, forms, dependency injection, routing, SSR, ARIA accessibility, animations, Tailwind styling, testing, and CLI tooling.
Executes ctx7 CLI to fetch up-to-date library documentation, manage AI coding skills (install/search/generate/remove/suggest), and configure Context7 MCP. Useful for current API refs, skill handling, or agent setup.
Generates in-depth technical architecture documentation from codebases. Produces engineer-focused documentation with system diagrams, data flow analysis, component deep dives, and architectural decision rationale.
Core principle: Depth over breadth. Technical rigor over high-level summaries.
Copy this checklist and check off items as you complete them:
Architecture Documentation Progress:
- [ ] Phase 1: Codebase exploration (structure, entry points, dependencies)
- [ ] Phase 2: Components identified (services, modules, databases)
- [ ] Phase 3: Data flow traced (request lifecycle, transformations)
- [ ] Phase 4: Business context extracted (README, comments, code)
- [ ] Phase 5: Documentation generated following structure below
- [ ] Phase 6: Diagrams created (PlantUML via Kroki, Mermaid, and/or Eraser syntax)
- [ ] Phase 7: Engineering analysis complete (all "why" questions answered)
- [ ] Phase 8: Quality validation passed
Follow this structure (see example-output.pdf for full reference):
Abstract
Context & Scope
Architecture Constraints & Principles
High-Level Architecture
Component Deep Dives
Cross-Cutting Concerns
Decision Log (ADRs)
Appendix A: Technology Stack Summary
Appendix B: API Endpoint Reference
Template format:
## 4. Component Deep Dives
### Component Responsibility Matrix
| Component | Primary Responsibility | Key Dependencies | Input/Output | Failure Modes | Recovery Strategies |
|-----------|----------------------|------------------|--------------|---------------|--------------------|
| [Name] | What it does (1 sentence) | Services/DBs it needs | What goes in → What comes out | How it breaks | How it recovers |
| [Name] | ... | ... | ... | ... | ... |
### 4.1 [Component Name]
[PlantUML diagram of internal logic]
**Purpose:** One sentence summary.
**Implementation Details (The "How"):**
- **Stack:** Technologies used
- **Key Algorithms:** How does it work?
- **Dependencies:** Libraries/services with citation (why chosen over alternatives)
**Engineering Analysis (The "Why"):**
- **Trade-offs:** Why this approach? What was rejected and why?
- **Configuration:** Why these specific settings? (timeouts, limits, buffer sizes)
- **State Management:** Stateless or stateful? Where persisted? How consistent?
- **Edge Cases:** What errors are handled? Retry logic? Failure modes?
Determine documentation type first:
For new documentation:
Understand project structure:
Identify components:
Analyze data flow:
Abstract:
Business Context:
System Context Diagram:
High-Level Architecture:
Component Deep Dives:
Cross-Cutting Concerns:
Decision Log:
Optional Appendices (if applicable):
Three diagram engines are available. Choose based on needs:
Option A: PlantUML via Kroki (default) — Free, self-hostable, 25+ diagram engines, 900+ AWS cloud icons in stdlib.
Option B: Mermaid — GitHub/GitLab native rendering, dedicated architecture-beta diagram type, C4 support, Iconify icon ecosystem.
Option C: Eraser — Concise syntax, visual styling (watercolor, bold), requires API key.
Generate PlantUML code using cloud icon macros (see kroki-syntax.md and icon-reference.md):
```plantuml
@startuml System Context
!include <awslib/AWSCommon>
!include <awslib/General/Users>
!include <awslib/Compute/Lambda>
!include <awslib/Database/Aurora>
left to right direction
Users(users, "End Users", "")
Lambda(api, "API Service", "Node.js 20")
Aurora(db, "Database", "PostgreSQL 15")
users --> api : HTTPS/JSON
api --> db : SQL Queries
@enduml
```
Kroki endpoints:
POST https://kroki.io/plantuml/svgPOST https://kroki.io/c4plantuml/svgGenerate Mermaid diagrams using the architecture-beta type for cloud topology or C4 types for system modeling (see mermaid-syntax.md and mermaid-icon-reference.md):
Architecture diagram (built-in icons — works on GitHub/GitLab natively):
```mermaid
architecture-beta
group vpc(cloud)[AWS Cloud]
group private(cloud)[Private Subnet] in vpc
service users(internet)[End Users]
service api(server)[API Service] in vpc
service app(server)[App Server] in private
service db(database)[Database] in private
users:R --> L:api
api:B --> T:app
app:R --> L:db
```
Architecture diagram (with registered Iconify icons — requires local rendering):
```mermaid
architecture-beta
group vpc(logos:aws)[AWS Cloud]
service users(internet)[End Users]
service apigw(logos:aws-api-gateway)[API Gateway] in vpc
service lambda(logos:aws-lambda)[Lambda] in vpc
service db(logos:aws-aurora)[Aurora DB] in vpc
users:R --> L:apigw
apigw:R --> L:lambda
lambda:R --> L:db
```
C4 container diagram:
```mermaid
C4Container
title Container Diagram
Person(user, "User", "End user")
System_Boundary(sys, "My System") {
Container(app, "App", "React", "Frontend SPA")
ContainerDb(db, "Database", "PostgreSQL", "User data")
}
System_Ext(ext, "External API", "Third-party service")
Rel(user, app, "Uses", "HTTPS")
Rel(app, db, "Reads/Writes", "SQL")
Rel(app, ext, "Calls", "REST")
```
Mermaid rendering: Use render-kroki-diagrams.js (routes to /mermaid/ endpoint) or render natively on GitHub/GitLab. For full Iconify icon support, use Mermaid CLI (mmdc) or browser rendering with registerIconPacks().
Platform note: GitHub and GitLab render Mermaid natively but only support the 5 built-in icons (cloud, database, disk, internet, server). For branded cloud icons, render locally and embed as images.
Generate Eraser diagram code (see eraser-syntax.md):
```eraser
// System Context
colorMode bold
direction right
Users [icon: users, label: "End Users"]
API [icon: aws-lambda, label: "API Service"]
Database [icon: aws-rds, label: "PostgreSQL 15"]
Users > API: HTTPS/JSON
API > Database: SQL Queries
```
Eraser rendering: Requires ERASER_API_KEY env var. Use render-eraser-diagrams.js.
PlantUML/Kroki:
Mermaid:
Eraser:
For each component, answer ALL these questions with specifics (not vague statements):
After generating documentation, validate immediately using this checklist:
@startuml/@enduml within plantuml fences; Mermaid blocks in mermaid fences; Eraser blocks in ```eraser fencesleft to right direction / top to bottom direction)If validation fails:
### API Gateway
**Purpose:** Handles API requests.
**Implementation:**
- Uses FastAPI
- Routes requests to backend services
**Why:** It's fast and easy to use.
Problems: No WHY for library choice, no trade-offs, no configuration rationale, no edge cases, generic statements.
### Component Responsibility Matrix
| Component | Primary Responsibility | Key Dependencies | Input/Output | Failure Modes | Recovery Strategies |
|-----------|----------------------|------------------|--------------|---------------|--------------------|
| **Query Router** | Routes user queries to specialized agents via LLM intent classification | Azure OpenAI (gpt-5-mini) | User query (string) → Agent selection + args (JSON) | LLM fails to select tool, API timeout, non-English input | Fall back to default agent; log exceptions to App Insights; reject non-English with fixed response |
| **PostgreSQL DB** | Persistent storage for user profiles, query history, embeddings | PostGIS extension, pgvector | SQL queries → Result sets | Connection pool exhaustion, deadlocks, disk full | Auto-reconnect with exponential backoff; query timeout (30s); read replicas for queries |
| **Redis Cache** | Session state, rate limiting, hot data caching | None (standalone) | Key-value GET/SET → Cached data or miss | Cache miss, eviction, connection failure | Graceful degradation to DB; 5-minute TTL; connection retry (3x with backoff) |
What makes this good: Concise summary of each component's role, dependencies, data flow, failure scenarios, and recovery—providing quick reference before detailed sections.
### Query Router (stream.py)
**Purpose:** Routes user queries to appropriate specialized agent based on query intent.
**Implementation Details:**
- **Stack:** Python 3.11, FastAPI, AsyncAzureOpenAI v1.x
- **Key Algorithm:** LLM-based intent classification via function calling
- **Dependencies:**
- `openai==1.x`: Official SDK with native async streaming; type-safe; actively maintained. Chosen over `langchain` for direct control and lower overhead.
- `httpx==0.x`: Required for custom timeout configuration; `trust_env=False` prevents proxy interference
**Engineering Analysis:**
- **Trade-offs:**
- LLM-based router vs keyword regex: Regex is 10x faster but brittle and fails on paraphrased queries. LLM handles ambiguity and phrasing variations with 95%+ accuracy vs 60% for regex in testing.
- Model Selection (gpt-5-mini): Classification is simpler than generation. Mini model offers 10x cost reduction ($0.15 vs $1.50 per 1M tokens) and lower latency (~200ms vs ~800ms) compared to gpt-4o, without sacrificing routing accuracy (both achieved 96% in our test set).
- **Configuration:**
- `timeout_keep_alive=300s`: LLM responses can take 30-60s for complex queries; 5-minute keep-alive prevents client disconnect during long-running requests. Determined from p95 latency metrics showing 45s max.
- `httpx.Timeout(read=30.0)`: 30s read timeout balances allowing slow responses and failing fast on stalled connections. Based on upstream SLA of 25s + 5s buffer.
- `max_retries=0`: Streaming responses cannot be retried mid-stream; client must handle retry. Retrying would cause duplicate partial responses.
- **State Management:** Stateless component; all routing decisions made per-request from query content alone. No session state persisted.
- **Edge Cases:**
- No Tool Selection: If LLM fails to select tool (< 0.1% of requests), system falls back to direct response with default agent.
- Execution Exceptions: All tool exceptions caught, logged with full traceback to Application Insights, and returned to user via friendly SSE error message (HTTP 200 with error type in stream).
- Non-English Input: Intercepted immediately via Router LLM system prompt ("Only process English queries"). Returns fixed fallback response without further LLM calls, preventing unnecessary inference costs for unsupported languages.
What makes this good: Specific numbers, alternatives considered, trade-off analysis, configuration rationale linked to requirements, concrete failure scenarios.
Prioritize technical depth in:
Adopt formal language throughout:
Formal Vocabulary:
Diagram Presentation:
**Figure X: Title** only (no descriptive subtitle)Trade-offs Format:
Header Usage:
Don't:
Do:
This skill includes comprehensive reference materials:
PlantUML/Kroki:
Mermaid:
architecture-beta), C4 types, flowchart icon shapes, rendering options, platform limitationsEraser:
Shared:
When generating diagrams, reference these files to:
After generating documentation, render diagrams with the appropriate script:
# Render all PlantUML and Mermaid diagrams from a markdown file
./render-kroki-diagrams.js Architecture.md --format svg
# Replace code blocks with image references
./render-kroki-diagrams.js Architecture.md --format svg --replace
# Use self-hosted Kroki
./render-kroki-diagrams.js Architecture.md --base-url http://localhost:8000
The script auto-detects diagram types: C4 PlantUML routes to /c4plantuml/, regular PlantUML to /plantuml/, and Mermaid to /mermaid/.
Note: Kroki's Mermaid rendering requires docker-compose with the kroki-mermaid companion container when self-hosting. The public Kroki instance supports Mermaid out of the box.
# Render all Eraser diagrams (requires ERASER_API_KEY env var)
./render-eraser-diagrams.js Architecture.md --format svg
# Replace code blocks with image references
./render-eraser-diagrams.js Architecture.md --format svg --replace
# Use explicit API key
./render-eraser-diagrams.js Architecture.md --api-key YOUR_KEY
Without an API key, the script saves raw .eraser files for manual rendering.
## Appendix A: Technology Stack Summary
| Category | Technology | Version | Purpose | Layer |
|----------|-----------|---------|---------|-------|
| **Backend** | FastAPI | 0.104.x | HTTP framework, async routing | Application |
| **AI/ML** | Azure OpenAI | gpt-4o, gpt-5-mini | LLM inference, intent classification | AI Service |
| **Data Storage** | PostgreSQL | 15.x | Persistent storage, user profiles | Data |
| **Observability** | Application Insights | Latest | APM, distributed tracing | Infrastructure |
## Appendix B: API Endpoint Reference
### POST /api/chat
**Purpose:** Stream chat responses with agent routing
**Authentication:** Bearer JWT (HS256)
**Request:**
```json
{
"query": "What is the status of order #12345?",
"user_id": "user_abc123"
}
Response: Server-Sent Events (SSE)
Event Types:
agent_selected: {"agent": "order_lookup", "args": {...}}content_delta: {"delta": "The order status is..."}done: {"finish_reason": "stop"}Error Responses:
401 Unauthorized: Invalid/missing JWT429 Too Many Requests: Rate limit exceeded
## Output Format
Generate a single markdown file with:
- All sections from the template structure
- PlantUML diagram code blocks (wrapped in `@startuml`/`@enduml` within ```plantuml fences)
- Cloud icon macros matching actual technologies (AWS/Azure/GCP icons from icon-reference.md)
- Inline code examples where relevant (with file paths and line numbers)
- Tables for configuration rationale, trade-offs analysis
- Concrete examples throughout
- Exact payload transformations showing before/after
- Optional appendices if system has APIs or uses multiple technologies
## Final Checklist
Before finalizing documentation:
- [ ] All 8 checklist phases completed
- [ ] All validation checks passed
- [ ] Every component has detailed engineering analysis
- [ ] All diagrams use correct syntax (PlantUML with cloud icon macros, Mermaid with architecture-beta/C4/flowchart, or Eraser with proper properties)
- [ ] No vague statements (all specifics with numbers, examples)
- [ ] Consistent terminology used throughout
- [ ] Trade-offs explained for major decisions
- [ ] Configuration values justified
- [ ] Failure modes documented
- [ ] Real examples included (payloads, code with line numbers)