Architecture Documentation

Home › Tutorials › Specialized Topics › Architecture Documentation

Status: Placeholder - Content coming soon

Prerequisites: Your First Module, understanding of C4 model

Planned Content

This tutorial teaches you how to create and maintain architecture documentation using the C4 model and Structurizr, with AI-assisted diagram generation.

What You'll Learn

• Understand the C4 model (Context, Container, Component, Code)
• Create workspace.dsl files for modules
• Generate architecture diagrams with AI: r2r create design
• Validate DSL syntax: r2r validate design
• View diagrams in browser: r2r serve design
• Update diagrams as architecture evolves: r2r update design
• Keep documentation synchronized with code

Tutorial Structure

1. C4 model fundamentals
2. Context: System in environment
3. Container: Deployable units
4. Component: Groupings of code
5. Code: Class diagrams (optional)

6. Choosing the right level

7. Structurizr DSL basics

8. Workspace structure
9. Define systems, containers, components
10. Relationships and dependencies

11. Styling and layout

12. Creating architecture documentation

13. Generate with AI: r2r create design <module>
14. AI analyzes code and generates workspace.dsl
15. Review and refine generated documentation

16. Understand generated structure

17. Validating architecture

18. Check syntax: r2r validate design
19. Uses Structurizr CLI (Docker)
20. Fix validation errors

21. Ensure diagrams render

22. Viewing diagrams

23. Start server: r2r serve design
24. Open in browser (Structurizr Lite)
25. Navigate between views

26. Export diagrams (PNG, SVG)

27. Updating documentation

28. Code changes → Architecture changes
29. Update with AI: r2r update design <module>
30. Manual edits for precision

31. Version control diagrams

32. Best practices

33. Keep diagrams simple and focused
34. Update when architecture changes
35. Use consistent naming
36. Document key decisions
37. Link to decision records

Example: Module Architecture

The tutorial documents the architecture of a module:

Generated workspace.dsl:

workspace "EAC Commands" {

    model {
        user = person "Developer" "Uses r2r CLI"

        system = softwareSystem "EAC Commands" {
            cli = container "CLI" "Command-line interface" "Go" {
                cmd = component "Commands" "Cobra command handlers"
                contracts = component "Contracts" "Repository contracts"
                pipeline = component "Pipeline" "CI/CD orchestration"
            }
        }

        user -> cli "Executes commands"
        cmd -> contracts "Reads"
        cmd -> pipeline "Orchestrates"
    }

    views {
        systemContext system {
            include *
            autolayout lr
        }

        container system {
            include *
            autolayout lr
        }

        component cli {
            include *
            autolayout lr
        }
    }
}

Key Concepts Covered

• C4 model levels
• Structurizr DSL syntax
• AI-assisted documentation generation
• Architecture validation
• Living documentation practices

Creating Architecture Documentation

# Generate architecture from code
r2r create design eac-commands

# Review generated workspace.dsl
cat go/eac/commands/design/workspace.dsl

# Validate DSL syntax
r2r validate design

# View in browser
r2r serve design
# Opens http://localhost:8080

# Update after code changes
r2r update design eac-commands

C4 Model Levels

Level 1 - Context: - System and its users - External dependencies - High-level overview

Level 2 - Container: - Deployable units (apps, services, databases) - Communication protocols - Technology choices

Level 3 - Component: - Major code structures - Responsibilities - Interactions

Level 4 - Code: - Class diagrams (rarely used) - Generated from code

Structurizr Lite

The tutorial uses Structurizr Lite (Docker) to view diagrams:

• Lightweight diagram viewer
• No account required
• Runs locally
• Export diagrams

Documentation Workflow

1. Initial creation
2. Generate with AI: r2r create design
3. Review and refine

4. Commit to version control

5. Ongoing maintenance

6. Code changes → Update documentation
7. Use AI or manual edits
8. Validate before committing

9. Review in pull requests

10. Consumption

11. View in browser during development
12. Export for presentations
13. Link from README
14. Include in onboarding

Best Practices

• Generate diagrams from code when possible
• Keep DSL files in module directories
• Version control all architecture documentation
• Update diagrams when architecture changes
• Use AI to bootstrap, refine manually
• Document key architectural decisions
• Link to decision records
• Keep diagrams simple and focused

Integration with Development

• Architecture reviews in PRs
• Link diagrams in documentation
• Use in onboarding new team members
• Reference in technical discussions
• Export for presentations

Tools Used

• Structurizr CLI: Validate DSL syntax (Docker)
• Structurizr Lite: View diagrams (Docker)
• AI (Claude): Generate and update DSL
• Git: Version control diagrams

Next Steps

After completing this tutorial, you'll maintain living architecture documentation. Explore other specialized topics: Effective BDD Scenarios, Security Scanning, or TypeScript Setup.

---

Tutorials | How-to Guides | Explanation | Reference

You are here: Tutorials — learning-oriented guides that take you through steps to complete a project.