sigistry Architecture Diagramming
Purpose
Provide standardized methodology and templates for generating architecture diagrams from codebase analysis. Uses the C4 Model for hierarchical architecture views and Mermaid for diagram rendering.
C4 Model Overview
The C4 Model defines four levels of architecture abstraction:
| Level | Name | Shows | When to Use |
|---|---|---|---|
| 1 | System Context | System + external actors | Always, the "big picture" |
| 2 | Container | Applications, data stores, services | When multiple deployable units exist |
| 3 | Component | Internal modules within a container | When analyzing a specific service |
| 4 | Code | Classes, interfaces | Rarely, only for critical components |
Diagram Selection Guide
Choose diagrams based on what exists in the codebase:
| What You Find | Diagrams to Generate |
|---|---|
| Multiple services/microservices | System Overview (L1), Container (L2), Dependency Graph |
| Database schemas/models | ER Diagram |
| API endpoints | API Interaction Diagram |
| Message queues/events | Event Flow Diagram |
| Multi-step workflows | Sequence Diagrams |
| Docker/K8s configs | Deployment/Infrastructure Diagram |
| Monolith with modules | Component Diagram (L3) |
Diagram Generation Process
- Scan project structure to identify components and boundaries
- Read config files (docker-compose, k8s, CI/CD, infrastructure-as-code)
- Map entry points, routes, and service communication
- Identify data stores and their relationships
- Select appropriate diagram types from the guide above
- Generate only diagrams relevant to findings, do not include generic templates
- Use proper Mermaid syntax with styling (subgraphs, colors, labels)
Mermaid Styling Conventions
%% Color coding for diagram elements:
%% - External actors/users: fill:#e1f5fe (light blue)
%% - External services: fill:#ffebee (light red)
%% - Core services: default styling
%% - Databases: use cylinder notation [( )]
%% - Critical components: fill:#fff3e0 (light orange)
Key Principles
- Generate only what exists: Never include components not found in the codebase
- Label with actual technology: Use real framework/database names discovered
- Show actual relationships: Trace real imports, API calls, and configurations
- Include risk assessment: Flag high-risk dependencies and single points of failure
Additional Resources
Reference Files
For codebase discovery heuristics at each C4 level, consult:
references/c4-model-guide.md: What to look for in code at each C4 level, container identification heuristics, and common architectural layer patterns