/create-architecture-documentation

allowed-tools: Read, Write, Edit, Bash
argument-hint: "[framework] | --c4-model | --arc42 | --adr | --plantuml | --full-suite"
description: Generate comprehensive architecture documentation with diagrams, ADRs, and interactive visualization

Architecture Documentation Generator

Generate comprehensive architecture documentation: $ARGUMENTS

Current Architecture Context

• Project structure: !`find . -type f -name "*.json" -o -name "*.yaml" -o -name "*.toml" | head -5`
• Documentation exists: @docs/ or @README.md (if exists)
• Architecture files: !`find . -name "*architecture*" -o -name "*design*" -o -name "*.puml" | head -3`
• Services/containers: @docker-compose.yml or @k8s/ (if exists)
• API definitions: !`find . -name "*api*" -o -name "*openapi*" -o -name "*swagger*" | head -3`

Task

Generate comprehensive architecture documentation with modern tooling and best practices:

1. **Architecture Analysis and Discovery**

• Analyze current system architecture and component relationships
• Identify key architectural patterns and design decisions
• Document system boundaries, interfaces, and dependencies
• Assess data flow and communication patterns
• Identify architectural debt and improvement opportunities

2. **Architecture Documentation Framework**

• Choose appropriate documentation framework and tools:
• **C4 Model**: Context, Containers, Components, Code diagrams
• **Arc42**: Comprehensive architecture documentation template
• **Architecture Decision Records (ADRs)**: Decision documentation
• **PlantUML/Mermaid**: Diagram-as-code documentation
• **Structurizr**: C4 model tooling and visualization
• **Draw.io/Lucidchart**: Visual diagramming tools

3. **System Context Documentation**

• Create high-level system context diagrams
• Document external systems and integrations
• Define system boundaries and responsibilities
• Document user personas and stakeholders
• Create system landscape and ecosystem overview

4. **Container and Service Architecture**

• Document container/service architecture and deployment view
• Create service dependency maps and communication patterns
• Document deployment architecture and infrastructure
• Define service boundaries and API contracts
• Document data persistence and storage architecture

5. **Component and Module Documentation**

• Create detailed component architecture diagrams
• Document internal module structure and relationships
• Define component responsibilities and interfaces
• Document design patterns and architectural styles
• Create code organization and package structure documentation

6. **Data Architecture Documentation**

• Document data models and database schemas
• Create data flow diagrams and processing pipelines
• Document data storage strategies and technologies
• Define data governance and lifecycle management
• Create data integration and synchronization documentation

7. **Security and Compliance Architecture**

• Document security architecture and threat model
• Create authentication and authorization flow diagrams
• Document compliance requirements and controls
• Define security boundaries and trust zones
• Create incident response and security monitoring documentation

8. **Quality Attributes and Cross-Cutting Concerns**

• Document performance characteristics and scalability patterns
• Create reliability and availability architecture documentation
• Document monitoring and observability architecture
• Define maintainability and evolution strategies
• Create disaster recovery and business continuity documentation

9. **Architecture Decision Records (ADRs)**

• Create comprehensive ADR template and process
• Document historical architectural decisions and rationale
• Create decision tracking and review process
• Document trade-offs and alternatives considered
• Set up ADR maintenance and evolution procedures

10. **Documentation Automation and Maintenance**

• Set up automated diagram generation from code annotations
• Configure documentation pipeline and publishing automation
• Set up documentation validation and consistency checking
• Create documentation review and approval process
• Train team on architecture documentation practices and tools
• Set up documentation versioning and change management