Edit and maintain architecture documentation based on arc42 template via Backlog.md
Maintain and update architecture documentation following the arc42 standard through the Backlog.md MCP system. Arc42 provides a proven, comprehensive template for documenting software and system architecture in a structured, consistent manner.
Arc42 is organized into 12 mandatory sections plus optional glossary. Each section serves a specific purpose:
| Section | Purpose |
|---|
| Introduction & Goals | Requirements, quality goals, and stakeholder expectations |
| Architecture Constraints | Technical, organizational, and regulatory constraints |
| Context & Scope | Business and technical system boundaries |
| Solution Strategy | High-level approach to achieve quality goals |
| Building Block View | System decomposition (3 hierarchical levels) |
| Runtime View | System behavior during execution (scenarios) |
| Deployment View | Infrastructure and deployment topology |
| Cross-cutting Concepts | Reusable patterns (logging, security, persistence, etc.) |
| Architecture Decisions | Rationale for key architectural choices |
| Quality Requirements | Non-functional requirements and scenarios |
| Risks & Technical Debt | Known issues and improvement opportunities |
| Glossary | Domain-specific terminology definitions |
Architecture documentation is managed as a Backlog.md document:
# View current documentation
backlog document view doc-003
# Update documentation (via CLI or direct edit)
# The document is stored as: backlog/docs/doc-003 - Architecture-Documentation.md
backlog document view doc-003 --plain
This shows the complete arc42 template with all sections.
General approach: Edit sections in the document while maintaining arc42 structure and order.
Example quality goals:
List each constraint with brief explanation of impact.
Create tables or diagrams (ASCII art or links to external diagrams) to show system boundaries.
Example: "We use microservices to achieve scalability and deployment independence; containerized via Docker/Kubernetes for operational efficiency."
Hierarchical decomposition in 3 levels:
For each block, document:
Example block:
### Authentication Service
Purpose: Handle user identity, token generation, and permission validation
Interface:
- POST /auth/login - returns JWT token
- GET /auth/validate - verifies token, returns user context
Quality: <5ms latency, 99.9% availability
Location: src/auth-service/
Fulfilled Requirements: REQ-001 (user identity), REQ-003 (security)
Document important execution scenarios:
For each scenario:
Infrastructure and deployment topology:
Document:
Document reusable patterns and concerns:
Example:
### Asynchronous Processing
All long-running operations (reports, exports, external integrations) use message queues
(RabbitMQ) to decouple producers from consumers. Retry logic: exponential backoff,
max 3 retries. Dead-letter queue for failed messages after retries.
Link or embed important ADRs (Architecture Decision Records):
Example entry:
- **Database Technology:** PostgreSQL chosen for ACID compliance over NoSQL.
See ADR-002 for full rationale and alternatives.
- **API Style:** RESTful with JSON for simplicity and broad tooling support.
Non-functional requirements and quality scenarios:
Include concrete scenarios:
Performance Scenario:
- Given: 1000 concurrent users browsing products
- When: User searches with filters
- Then: Result page loads in < 500ms (95th percentile)
Known issues and improvement opportunities:
Risk: Database query performance on large datasets
Technical Debt: Legacy payment module (deprecated API)
The glossary is in its own document (backlog/docs/doc-004 - Glossary.md) to keep the main architecture document concise. Link to glossary from the architecture documentation.
backlog/decisions/backlog/decisions/backlog/docs/doc-003 - Architecture-Documentation.mdbacklog/decisions/ for detailed ADRs