206 lines
5.1 KiB
Markdown
206 lines
5.1 KiB
Markdown
# 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
|
|
|
|
```dsl
|
|
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
|