BMAD-METHOD/expansion-packs/bmad-c4-architecture/data/c4-model-guidelines.md

C4 Model Guidelines

Overview

The C4 model is a hierarchical approach to visualizing software architecture through four levels of abstraction.

Level 1: System Context Diagram

• Purpose: Shows how the system fits into the world around it
• Audience: Technical and non-technical people
• Elements: Users, software systems, external systems
• Key Questions:
  • Who uses the system?
  • What external systems does it interact with?
  • What are the main user goals?

Level 2: Container Diagram

• Purpose: Zooms into the system boundary, showing high-level technical building blocks
• Audience: Software developers and architects
• Elements: Containers (applications, databases, file systems, etc.)
• Key Questions:
  • What are the main functional areas?
  • What technology choices have been made?
  • How do containers communicate?

Level 3: Component Diagram

• Purpose: Zooms into a container to show the components within it
• Audience: Software developers
• Elements: Components, interfaces, data models
• Key Questions:
  • What are the main components?
  • How do components interact?
  • What are the key interfaces?

Level 4: Code Diagram

• Purpose: Zooms into a component to show how it is implemented
• Audience: Software developers
• Elements: Classes, interfaces, packages
• Note: Usually created using UML or similar tools

Best Practices

Naming Conventions

• Use clear, descriptive names
• Be consistent across all diagrams
• Use business terminology where appropriate
• Avoid technical jargon in context diagrams

Relationship Labels

• Use active voice ("Uses", "Sends data to")
• Be specific about protocols and technologies
• Include data flow direction
• Use consistent terminology

Diagram Layout

• Use autolayout for consistency
• Group related elements
• Minimize crossing lines
• Use appropriate colors and styling

Technology Choices

• Be specific about technologies
• Justify technology decisions
• Consider scalability and maintainability
• Document technology constraints

Common Anti-Patterns

Context Diagram

• ❌ Too many external systems
• ❌ Missing key users
• ❌ Unclear relationships
• ❌ Technical details in context diagram

Container Diagram

• ❌ Too many containers
• ❌ Missing communication protocols
• ❌ Unclear responsibilities
• ❌ Missing security boundaries

Component Diagram

• ❌ Too much detail
• ❌ Missing interfaces
• ❌ Unclear data flow
• ❌ Missing error handling

Structurizr DSL Best Practices

Workspace Structure

workspace "Name" "Description" {
    model {
        // All model elements
    }
    views {
        // All views
    }
}

Element Definitions

• Always provide descriptions for elements
• Use consistent naming conventions
• Group related elements logically
• Apply appropriate tags and properties

Relationship Definitions

• Use descriptive labels
• Include technology information
• Specify data flow direction
• Avoid circular dependencies

View Configuration

• Use autolayout for consistency
• Include all relevant elements
• Apply appropriate themes
• Test view layouts

Quality Checklist

Context Diagram

• All key users are represented
• All external systems are identified
• Relationships are clearly defined
• Technology choices are appropriate
• Diagram is understandable to non-technical stakeholders

Container Diagram

• All major components are represented
• Technology choices are justified
• Data flow is clear
• Security boundaries are defined
• Scalability considerations are addressed

Component Diagram

• All major components are represented
• Interfaces are clearly defined
• Data flow is logical
• Dependencies are minimal
• Error handling is considered

Common Issues and Solutions

Issue: Too Many Elements

Solution: Focus on the most important elements and relationships. Use multiple diagrams if needed.

Issue: Unclear Relationships

Solution: Use descriptive labels and include technology information. Show data flow direction.

Issue: Inconsistent Naming

Solution: Establish naming conventions and apply them consistently across all diagrams.

Issue: Missing Context

Solution: Ensure each diagram level provides appropriate context for its audience.

Issue: Technical Details in Context Diagram

Solution: Keep context diagrams high-level and business-focused. Move technical details to container diagrams.

Integration with Development Process

Planning Phase

• Create context diagrams to understand system scope
• Use diagrams for stakeholder communication
• Validate requirements against architecture

Design Phase

• Create container diagrams for technical design
• Use component diagrams for detailed design
• Validate design decisions

Implementation Phase

• Keep diagrams updated with implementation
• Use diagrams for developer onboarding
• Document architectural decisions

Maintenance Phase

• Regular diagram updates
• Version control diagram changes
• Use diagrams for impact analysis