architecture-design

name	architecture-design
description	Generate comprehensive software architecture documentation (ARCHITECTURE.md) with C4 diagrams, OpenAPI specs, and technology-specific guidance. This skill should be used when creating architecture documentation for new projects, documenting existing systems, or updating architectural specifications.

Architecture Design

Generate professional software architecture documentation with visual diagrams and API specifications through structured interviews. Create complete ARCHITECTURE.md files covering all required sections with technology-specific patterns, C4 model diagrams, and OpenAPI 3.0 specifications.

Core Workflow

Step 1: Assess Project Type

Determine the project type by asking the user:

• New project? Gather requirements and design architecture
• Existing system? Document current state
• Update needed? Identify changed components

Step 2: Gather Essential Information

Conduct a brief interview (5-7 questions maximum) to collect:

1. Architecture pattern: Monolith, microservices, or serverless?
2. Primary technology: Node.js, Python, Java, or other?
3. Key components: Main services or modules?
4. Data stores: Databases and caches?
5. Cloud provider: AWS, GCP, Azure, or on-premise?
6. Deployment: How is it deployed?
7. External integrations: Third-party services?

Step 3: Select Template and Load References

Choose template based on architecture pattern:

• Monolith → Use assets/ARCHITECTURE-monolith.md
• Microservices → Use assets/ARCHITECTURE-microservices.md
• Uncertain → Use assets/ARCHITECTURE.md

Load technology-specific references:

• Node.js projects → Load references/nodejs.md for Express, NestJS, Fastify patterns
• Python projects → Load references/python.md for Django, Flask, FastAPI patterns
• Java projects → Load references/java.md for Spring Boot, Jakarta EE patterns

Load pattern-specific references when applicable:

• Microservices → Load references/microservices.md for service boundaries and communication patterns
• Serverless → Load references/serverless.md for function organization and event sources

Step 4: Generate System Diagram

Generate appropriate diagrams using scripts/generate_diagram.py:

For monolithic architectures:

python scripts/generate_diagram.py layered

For microservices architectures:

python scripts/generate_diagram.py flow

For simple systems:

python scripts/generate_diagram.py simple

Customize diagrams with JSON configuration for specific components.

Step 5: Populate Template

Complete the template sections in the specified order:

1. Project Identification (Section 10) - Add project name, repository, contact, date
2. Project Structure (Section 1) - Define directory layout
3. System Diagram (Section 2) - Insert generated diagram
4. Core Components (Section 3) - Document components from interview
5. Data Stores (Section 4) - Describe databases and caches
6. External Integrations (Section 5) - List third-party services
7. Deployment (Section 6) - Detail infrastructure setup
8. Security (Section 7) - Specify authentication and encryption
9. Development (Section 8) - Outline setup and testing procedures
10. Future Considerations (Section 9) - Document roadmap items
11. Glossary (Section 11) - Define domain terminology

Apply technology-specific patterns from loaded references to enhance each section.

Step 6: Validate

Execute the validation script to ensure quality:

python scripts/validate_architecture.py ARCHITECTURE.md

Address any issues or warnings before delivering the documentation.

Interview Best Practices

Maintain focused questioning:

• Ask 2-3 questions at a time
• Build upon previous answers
• Skip redundant questions

Adapt communication style:

• Technical users: Use precise terminology
• Non-technical users: Simplify language
• Uncertain users: Offer defaults or placeholders

Handle information gaps:

• Mark uncertain items for review
• Add [TODO] for missing information
• Suggest reasonable defaults based on context

Technology-Specific Guidance

Reference Loading Guidelines

Load references/nodejs.md for:

• Express, NestJS, Fastify projects
• Node.js microservices
• Serverless Node functions

Load references/python.md for:

• Django, Flask, FastAPI projects
• Python microservices
• Data pipelines and ML systems

Load references/java.md for:

• Spring Boot applications
• Jakarta EE systems
• Java microservices

Load references/workflows.md for:

• Complex interview scenarios
• Detailed process guidance
• Documentation update workflows

Applying Technology Patterns

After loading references, apply the patterns to enhance:

• Project structure recommendations
• Deployment configurations
• Framework-specific best practices
• Common library suggestions
• Testing strategies and approaches

Pattern-Specific Guidance

Microservices Architecture

Load references/microservices.md and include these elements:

• Service boundaries and responsibilities
• Communication patterns (synchronous vs asynchronous)
• API gateway configuration
• Service discovery mechanism
• Data management approach
• Observability and monitoring setup

Use the microservices template (assets/ARCHITECTURE-microservices.md) for proper structure.

Serverless Architecture

Load references/serverless.md and include these elements:

• Function organization and boundaries
• Event sources and triggers
• State management approach
• Cold start mitigation techniques
• Cost optimization strategies

Monolithic Architecture

Use the monolith template (assets/ARCHITECTURE-monolith.md) and emphasize:

• Layered architecture patterns
• Module organization principles
• Potential future refactoring paths
• Scaling strategy and approaches

Diagram Generation Examples

Simple Architecture Diagram

python scripts/generate_diagram.py simple '{"components": ["User", "API", "DB"], "connections": [["User", "API"], ["API", "DB"]]}'

Layered Architecture Diagram

python scripts/generate_diagram.py layered '{"Presentation": ["Web UI"], "Business": ["API"], "Data": ["PostgreSQL"]}'

Flow Architecture Diagram

python scripts/generate_diagram.py flow '[{"from": "Client", "to": "Gateway", "label": "HTTP"}, {"from": "Gateway", "to": "Service", "label": "route"}]'

C4 Context Diagram

python scripts/generate_diagram.py c4 '{"system": "E-commerce Platform", "actors": ["Customer", "Admin"], "external_systems": ["Payment Gateway", "Email Service"]}'

Integrate generated diagrams into Section 2 (System Diagram) of the ARCHITECTURE.md template.

Validation

Execute validation before delivering documentation:

python scripts/validate_architecture.py ARCHITECTURE.md

Validation checks performed:

• Verify all 11 sections are present
• Confirm required fields in Project Identification section
• Ensure minimal content in each section
• Count and report placeholder usage

Address any warnings about missing content or excessive placeholders.

Documentation Update Workflow

For incremental updates:

1. Identify what has changed
2. Update only affected sections
3. Update the date in Section 10 (Project Identification)
4. Re-run validation to ensure quality

For major updates:

1. Review the entire document
2. Regenerate diagrams if structure has changed
3. Update multiple sections as needed
4. Consider adding version notes

Mermaid Diagram Generation

After creating ARCHITECTURE.md, generate the complete set of 5 Mermaid diagrams.

Load Mermaid Instructions

When users request diagrams or complete documentation packages:

Load references/mermaid-diagrams.md

Generate Complete Diagram Set

Create all 5 diagrams following the guidance in mermaid-diagrams.md:

1. C4 Context (Level 1) - System in its broader context
2. C4 Container (Level 2) - Main application containers
3. C4 Component (Level 3) - Internal component structure
4. Data Flow - How data moves through the system
5. C4 Deployment - Infrastructure topology and deployment

Use scripts/generate_mermaid.py with system JSON configuration.

Save diagrams as separate .mmd files:

• 01-context.mmd
• 02-container.mmd
• 03-component.mmd
• 04-dataflow.mmd
• 05-deployment.mmd

Embed diagrams in ARCHITECTURE.md Section 2 as code blocks for easy viewing and editing.

OpenAPI Specification Generation

For systems with REST APIs, generate comprehensive OpenAPI 3.0 specifications.

Generate API Specifications

Use scripts/generate_openapi.py with appropriate parameters:

For simple CRUD operations:

python scripts/generate_openapi.py "ResourceName"

For custom API specifications:

python scripts/generate_openapi.py '{"system_name": "...", "endpoints": [...]}'

Save the generated specification as openapi.json in the project directory.

Complete Documentation Workflow

Follow this end-to-end workflow for comprehensive architecture documentation:

1. Conduct structured interview (5-7 questions maximum)
2. Select appropriate template and load relevant references
3. Setup work directory: Use current working directory $(pwd)
4. Generate ARCHITECTURE.md with all 11 sections completed
5. Generate Mermaid diagrams (5 separate .mmd files) in work directory root
6. Generate OpenAPI specification (if applicable) in work directory
7. Deliver all generated artifacts to the user

Deliverable Organization

Organize generated documentation files as follows:

├── ARCHITECTURE.md              # Main architecture document
├── openapi.json                 # API specification (if applicable)
├── *.mmd (5 files)             # Mermaid diagram sources
│   ├── 01-context.mmd
│   ├── 02-container.mmd
│   ├── 03-component.mmd
│   ├── 04-dataflow.mmd
│   └── 05-deployment.mmd
└── diagrams/ (created during packaging)
    └── *.png (5 files, if rendered to images)

Example Usage

User request: "Create architecture documentation for my Node.js microservices project"

Execution approach:

1. Select microservices template (assets/ARCHITECTURE-microservices.md)
2. Load references/nodejs.md and references/microservices.md
3. Conduct focused interview: services, databases, communication patterns, deployment
4. Generate flow diagram using scripts/generate_diagram.py flow
5. Populate all sections with Node.js and microservices-specific patterns
6. Validate using scripts/validate_architecture.py
7. Create comprehensive ARCHITECTURE.md in work directory

Common Usage Scenarios

New Greenfield Projects

• Use base template (assets/ARCHITECTURE.md)
• Focus on design decisions and architecture rationale
• Include justification for technology choices
• Emphasize planned architecture and future scalability

Existing System Documentation

• Ask about current pain points and challenges
• Document the as-is state accurately
• Note planned improvements in Section 9 (Future Considerations)
• Capture current technology stack and limitations

Legacy System Analysis

• Identify undocumented or poorly understood areas
• Mark uncertain items for further investigation
• Suggest areas requiring clarification from stakeholders
• Document assumptions and risks

Architecture Reviews and Updates

• Update only sections that have changed
• Preserve information that remains accurate
• Add new components and relationships
• Update date in Section 10 and note changes

Best Practices

Efficient documentation creation:

• Begin with known information and build incrementally
• Use placeholders for unknown items to maintain momentum
• Leverage technology references to save time and ensure accuracy
• Validate frequently to catch issues early

High-quality output standards:

• Provide specific, concrete details rather than generic descriptions
• Include actual technology stack versions and configurations
• Use real service names, purposes, and data flows
• Document concrete deployment infrastructure and environments

Positive user experience:

• Avoid overwhelming users with excessive questions
• Explain the documentation process and next steps
• Show progress through the 11 sections clearly
• Offer refinement and improvement after initial delivery