Expert architecture documentation covering ADR (Architecture Decision Records) format, C4 model diagrams, system context diagrams, sequence diagrams, deployment diagrams, technology radar, architectural fitness functions, and documentation-as-code.
Use when the user asks about architecture documenter, architecture documenter best practices, or needs guidance on architecture documenter implementation.
Do NOT use when the user needs a different specialized skill or is asking about an unrelated technology domain.
Expert architecture documentation covering ADR (Architecture Decision Records) format, C4 model diagrams, system context diagrams, sequence diagrams, deployment diagrams, technology radar, architectural fitness functions, and documentation-as-code.
Use when the user asks about architecture documenter, architecture documenter best practices, or needs guidance on architecture documenter implementation.
Do NOT use when the user needs a different specialized skill or is asking about an unrelated technology domain.
This skill provides comprehensive expertise in documenting software architecture. Effective architecture documentation communicates the system's structure, decisions, and rationale to both current and future team members. This skill covers industry-standard formats and models including ADRs, C4 diagrams, deployment views, and the documentation-as-code approach that keeps architecture docs living and accurate.
Architecture Decision Records (ADRs)
ADR Template (Michael Nygard Format)
# ADR-0015: Use PostgreSQL as Primary Database## Status
Accepted (2025-01-15)
Supersedes: ADR-0003 (Use MongoDB)
## Context
We need a persistent data store for our product catalog and order management
system. The data has strong relational characteristics (products belong to
categories, orders contain line items, users have addresses). We expect:
10M+ product records
50K+ orders per day
Complex queries joining 3-5 tables
Strong consistency requirements for financial data
Full-text search on product names and descriptions
We evaluated: PostgreSQL, MySQL, MongoDB, and CockroachDB.
If we exceed 1TB of data, we may need to evaluate sharding strategies
or move to a distributed database. We will re-evaluate at 500GB.
[ ] Set up PostgreSQL 16 in staging environment
[ ] Create database migration pipeline with Flyway
[ ] Establish backup and point-in-time recovery procedures
[ ] Document connection pooling strategy (PgBouncer)
-
-
-
-
-
# ... (condensed) ...
-
## Follow-Up Actions
-
-
-
-
ADR Numbering and Lifecycle
ADR States:
├── Proposed → Under discussion, not yet decided
├── Accepted → Decision made, implementation proceeding
├── Deprecated → No longer applies but was once valid
├── Superseded → Replaced by a newer ADR (link to replacement)
└── Rejected → Considered but not adopted (document why)
File Naming: docs/adr/XXXX-title-with-dashes.md
Example: docs/adr/0015-use-postgresql-as-primary-database.md
Index File: docs/adr/README.md
- List all ADRs with status, date, and one-line summary
- Group by domain (data, infrastructure, frontend, etc.)
When to Write an ADR
Write an ADR when:
├── Choosing a technology (database, framework, cloud provider)
├── Selecting an architecture pattern (microservices, CQRS, event sourcing)
├── Making a trade-off (consistency vs. availability, build vs. buy)
├── Establishing a standard (API style, error format, auth mechanism)
├── Changing a previous decision (must supersede the old ADR)
└── Making a decision that future team members will question
Do NOT write an ADR for:
├── Implementation details that can change without impact
├── Coding style preferences (use a linter config instead)
├── Trivial decisions with obvious answers
└── Temporary decisions (use a TODO or ticket instead)
C4 Model
Four Levels of Abstraction
C4 Model Levels:
Level 1: System Context → "What is this system and who uses it?"
Level 2: Container → "What are the major building blocks?"
Level 3: Component → "What is inside each container?"
Level 4: Code → "How is a component implemented?" (rarely needed)
Key Principle: Each level zooms in on the previous level.
Audience shifts from business stakeholders (L1) to developers (L4).
Level 1: System Context Diagram
System Context Diagram Template (as code using Structurizr DSL):
workspace {
model {
customer = person "Customer" "A user who browses and purchases products"
admin = person "Admin" "Internal staff who manage the product catalog"
productSystem = softwareSystem "Product Catalog System" "Manages product listings, search, and inventory" {
tags "Primary"
}
paymentGateway = softwareSystem "Payment Gateway" "Processes credit card payments" {
tags "External"
}
emailService = softwareSystem "Email Service" "Sends transactional emails" {
tags "External"
}
analytics = softwareSystem "Analytics Platform" "Tracks user behavior" {
tags "External"
}
customer -> productSystem "Browses products, places orders"
admin -> productSystem "Manages catalog and inventory"
productSystem -> paymentGateway "Processes payments" "HTTPS/REST"
productSystem -> emailService "Sends order confirmations" "SMTP"
productSystem -> analytics "Sends events" "HTTPS"
}
views {
systemContext productSystem "SystemContext" {
include *
autoLayout
}
}
}
## Order Placement Flow
\```mermaid
sequenceDiagram
actor Customer
participant Web as Web App
participant API as API Gateway
participant Order as Order Service
participant Product as Product Service
participant Payment as Payment Gateway
participant Email as Email Service
Customer->>Web: Click "Place Order"
Web->>API: POST /orders
API->>Order: Create order
Order->>Product: Check inventory
Product-->>Order: Inventory confirmed
Order->>Payment: Charge card
Payment-->>Order: Payment successful
Order->>Product: Decrement inventory
Order->>Email: Send confirmation
Email-->>Customer: Order confirmation email
Order-->>API: Order created (201)
API-->>Web: Order response
Web-->>Customer: Show confirmation page
\```
When to Use Sequence Diagrams
Use sequence diagrams for:
├── Multi-service request flows (API calls across microservices)
├── Authentication/authorization flows (OAuth, JWT refresh)
├── Error handling flows (what happens when service X fails?)
├── Async workflows (event-driven processes)
└── Third-party integration flows (payment, shipping, etc.)
Keep diagrams focused:
├── Maximum 6-8 participants per diagram
├── Maximum 15-20 interactions per diagram
├── Split complex flows into sub-diagrams
└── Name the diagram after the scenario, not the system
# Technology Radar - Q1 2025## Adopt (Use in production with confidence)
| Technology | Category | Notes |
|-----------|----------|-------|
| TypeScript 5.x | Language | Standard for all new services |
| PostgreSQL 16 | Database | Primary relational store |
| React 19 | Frontend | Web application framework |
| GitHub Actions | CI/CD | All pipelines migrated |
| Terraform | Infrastructure | IaC standard |
## Trial (Use in non-critical projects to gain experience)
| Technology | Category | Notes |
|-----------|----------|-------|
| Bun | Runtime | Evaluate for build tooling |
| Drizzle ORM | Database | Evaluate vs. Prisma |
| htmx | Frontend | Evaluate for admin tools |
| OpenTelemetry | Observability | Pilot in one service |
## Assess (Research and prototype, not production yet)# ... (condensed) ...## Hold (Do not start new projects with these)
| Technology | Category | Notes |
|-----------|----------|-------|
| MongoDB | Database | Migrating away; poor fit for relational data |
| Express.js | Framework | Replaced by Fastify for new services |
| Jenkins | CI/CD | Fully replaced by GitHub Actions |
| Webpack | Bundler | Replaced by Vite |
Architectural Fitness Functions
Definition and Examples
# Architectural Fitness Functions
Automated checks that verify the system conforms to architectural decisions.
## Dependency Rules**Rule**: Domain layer must not depend on infrastructure layer.
\```python
# ArchUnit-style test (Python with import-linter)
# .importlinter config
[importlinter:contract:domain-independence]
name = Domain must not import from infrastructure
type = forbidden
source_modules =
app.domain
forbidden_modules =
app.infrastructure
sqlalchemy
redis
httpx
\```# ... (condensed) ...**Rule**: Frontend bundle must be under 250KB gzipped.
\```javascript
// webpack-bundle-analyzer or vite-plugin-inspect
// CI check:
// gzip -c dist/assets/*.js | wc -c must be < 256000
\```
The question is about a fundamentally different technology domain
A more specific sibling skill covers the exact topic needed
The user needs a complete hands-on tutorial rather than expert guidance
Output Format
# Architecture Documenter Analysis## Context Assessment
[Situation summary and constraints]
## Recommended Approach
[Primary recommendation with rationale]
## Implementation Steps1. [Step with specific details]
2. [Step with specific details]
3. [Step with specific details]
## Trade-offs and Considerations- [Key trade-off 1]
- [Key trade-off 2]
## Next Steps- [Immediate action item]
- [Follow-up action item]
Example
Input: "Help me implement architecture documenter for a medium-scale production application"
Output: A structured analysis covering current state assessment, recommended architecture documenter approach with specific patterns, implementation roadmap with milestones, and risk mitigation strategies tailored to the application scale and constraints.
Edge Cases
Legacy system integration: When architecture documenter must coexist with legacy approaches, provide a gradual migration path rather than a complete rewrite
Scale mismatch: When the solution complexity exceeds the project scale, recommend a simpler approach and note when to revisit
Team skill gaps: When the team lacks experience with the recommended approach, include learning resources and simpler alternatives
Conflicting requirements: When constraints conflict (e.g., performance vs. maintainability), explicitly state the trade-off and recommend based on stated priorities
