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:

• 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

• 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

• 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

• 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

• 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

• 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

• 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

• 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

• 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

• 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