Important
This repository has been archived. All exercises are now consolidated in the Software-Architecture repository for easier navigation.
Find MateMate exercises at:
- Evening 3: Service-Based Architecture (MateMate02)
- Evening 3: Service Elicitation Results
Extended Architecture Framework combining C4 Model, arc42, and governance-oriented views for complete system documentation.
Project: MateMate - Desktop Chess Application Framework Version: 1.0 Date: November 13, 2025
This architectural documentation demonstrates an extended framework that surpasses both C4 Model and arc42 individually by combining their strengths and adding critical governance dimensions.
From C4 Model (2 of 4 levels):
- ✅ C1: System Context - System boundary and external actors
- ✅ C2: Container View - Deployable units and technology choices
- ❌ C3: Component - Redundant with subsystem decomposition
- ❌ C4: Code - Too low-level, maintained by IDE
From arc42 (7 of 12 chapters):
- ✅ Chapter 1: Introduction & Goals - Purpose, quality goals, stakeholders
- ✅ Chapter 3: Context & Scope - Business and technical context
- ✅ Chapter 5: Building Blocks - Component decomposition
- ✅ Chapter 6: Runtime View - Dynamic behavior and use cases
- ✅ Chapter 8: Cross-Cutting Concepts - Architectural patterns
- ✅ Chapter 9: Design Decisions - Architecture Decision Records (ADRs)
- ✅ Chapter 10: Quality Requirements - Quality tree and scenarios
Governance Extensions (6 additions beyond C4 and arc42):
- Allowed-to-Use Matrix - Binary dependency permission matrix with automated checking
- Change Impact Heatmap - Scenario-based blast radius analysis
- Sustainability View - Runtime resource footprint per subsystem
- FinOps View - Cost drivers and scaling behavior
- Metamodel - Explicit architectural concepts and relationships
- Blood Type Architecture - T/A/0 classification for change management
All diagram elements use meaningful visual encoding:
Color Semantics:
- 🟦 Blue (TYPE T) - Technical subsystems (change driver: technology evolution)
- 🟪 Purple (TYPE A) - Application subsystems (change driver: business rules)
- 🟧 Orange (TYPE 0) - Core subsystems (universal concepts, rarely change)
- Note: All colored boxes use black text for optimal readability
Frame Style Semantics:
- Solid border - Stable subsystem (< 5 changes/year)
- Dashed border - Evolving subsystem (5-20 changes/year)
- Dotted border - Volatile subsystem (> 20 changes/year)
- Thick border (4px) - Security/architectural boundary
Size Semantics:
- Width - Lines of Code (LOC)
- Height - Number of dependencies (fan-in + fan-out)
Arrow Semantics:
- Solid arrow - Compile-time dependency (direct imports/calls)
- Dashed arrow - Runtime dependency (events, messages)
- Green arrow - Allowed dependency (passes Allowed-to-Use Matrix)
- Red arrow - Forbidden dependency (violation)
- Thickness - Coupling strength (number of calls)
This extended framework enables more precise and actionable architecture reviews than C4 or arc42 alone:
1. Context & Constraints Review
- Verify system boundary (C4 System Context)
- Validate external interfaces
- Check technology constraints
2. Building Blocks & Boundaries Review
- Verify subsystem decomposition (arc42 Building Blocks)
- Check blood type classification (T/A/0)
- Validate separation of concerns
3. Dependency Correctness Review
- Check Allowed-to-Use Matrix compliance
- Detect forbidden dependencies (automated)
- Measure coupling metrics
4. Runtime Behavior Review
- Analyze sequence diagrams (arc42 Runtime View)
- Verify error handling paths
- Check performance characteristics
5. Change Resilience Review
- Analyze Change Impact Heatmap
- Estimate blast radius for scenarios
- Identify architectural fragility
6. Operational Footprint Review
- Check Sustainability View metrics
- Validate resource consumption
- Assess carbon footprint
7. Cost Scalability Review
- Analyze FinOps View
- Identify cost drivers
- Validate scaling assumptions
8. Visual Semantic Review
- Verify color/frame/size consistency
- Detect boundary violations visually
- Check diagram comprehensibility
Each review produces:
- ✅ Pass/Fail status per subsystem
- 📊 Quantified metrics (not subjective assessments)
- 🔴 Violations list with remediation steps
- 📈 Trend analysis (improving/stable/degrading)
- Subsystems - K1-K5 with blood types, responsibilities, and services
- Services - 20 services mapped to subsystems
- Allowed-to-Use Specification - Dependency rules and data flows
- C1: System Context - MateMate system boundary
- C2: Container View - K1-K5 subsystems with dependencies
- Chapter 1: Introduction - Purpose, quality goals, stakeholders
- Chapter 3: Context & Scope - Business and technical context
- Chapter 5: Building Blocks - Subsystem decomposition
- Chapter 6: Runtime View - Use case sequences and state machines
- Chapter 8: Cross-Cutting - Architectural patterns
- Chapter 9: Design Decisions - ADRs with rationale
- Chapter 10: Quality Requirements - Quality tree and scenarios
- Metamodel - Architectural concepts and relationships
- Allowed-to-Use Matrix - Dependency permission matrix
- Change Impact Heatmap - Scenario-based blast radius
- Sustainability & Resource Impact - Runtime footprint
- FinOps & Cost Governance - Cost drivers
- New Concepts - Summary of framework extensions
Desktop chess application with full FIDE rule compliance and graphical user interface.
| ID | Name | Blood Type | Role | Services | LOC |
|---|---|---|---|---|---|
| K1 | InputAdapter | T | Captures mouse/keyboard events | 2 | ~500 |
| K2 | RenderingEngine | T | Renders board and pieces to screen | 4 | ~1,200 |
| K3 | InteractionController | A | Orchestrates game flow and UI logic | 2 | ~800 |
| K4 | AnalysisService | A | Chess rules, move validation, evaluation | 6 | ~2,500 |
| K5 | PositionStore | 0 | Immutable game state and history | 6 | ~600 |
Total: 5 subsystems, 20 services, ~5,600 LOC
Blood Type Separation:
- TYPE T subsystems (K1, K2) change when technology evolves
- TYPE A subsystems (K3, K4) change when business rules evolve
- TYPE 0 subsystems (K5) rarely change (universal concepts)
Dependency Direction:
- K3 orchestrates K1, K2, K4 (application layer)
- K4 depends only on K5 (rules engine isolated from UI)
- K5 has zero dependencies (pure core)
Allowed Dependencies:
- K3 → K1, K2, K4 ✅
- K4 → K5 ✅
- All others forbidden ❌
- ✅ Adds dependency enforcement (Allowed-to-Use Matrix)
- ✅ Adds change impact analysis (Heatmap)
- ✅ Adds cost/resource tracking (FinOps, Sustainability)
- ✅ Adds quality scenarios (not just structure)
- ✅ Adds visual semantics (color, frame, size have meaning)
- ✅ Adds automated checks (dependency violations)
- ✅ Adds governance views (cost, sustainability)
- ✅ More concise (7 chapters vs 12, zero redundancy)
- ✅ Combines structural clarity (C4) with completeness (arc42)
- ✅ Adds governance dimensions neither framework has
- ✅ Enables automated architecture reviews
- ✅ Optimizes for evolution, not just documentation
- Read this README
- View C1: System Context
- Review Quality Requirements
- All of the above
- Study C2: Container View
- Read Building Blocks
- Review Design Decisions
- Check Allowed-to-Use Matrix
- All of the above
- Study Runtime View
- Read Cross-Cutting Concepts
- Review Metamodel
- Check Services Mapping
- Check Allowed-to-Use Matrix - Any violations?
- Review Change Impact Heatmap - Blast radius acceptable?
- Check Quality Requirements - Scenarios verified?
- Review Sustainability View - Resource usage reasonable?
Note: Metric values represent design targets and analytical estimates based on architectural analysis, not runtime measurements from automated tooling. Values are manually maintained and updated with each architectural change.
| Metric | Target | Actual | Status |
|---|---|---|---|
| Dependency Violations | 0 | 0 | ✅ Pass |
| Subsystem Count | 3-7 | 5 | ✅ Pass |
| Avg Dependencies per Subsystem | < 5 | 3.6 | ✅ Pass |
| Total LOC | < 10,000 | ~5,600 | ✅ Pass |
| Blood Type Separation | 100% | 100% | ✅ Pass |
| Scenario | Affected Subsystems | Effort | Risk |
|---|---|---|---|
| Renderer swap | K2, K3 | 80h | High |
| Chess rule change | K4, K5 | 16h | Medium |
| Input device change | K1, K3 | 24h | Medium |
| Subsystem | CPU | Memory | Storage Growth | Cost/Month* |
|---|---|---|---|---|
| K1 | 1-2% | 50 MB | None | $2 |
| K2 | 5-15% (GPU 20-40%) | 200 MB | None | $15 |
| K3 | 2-5% | 100 MB | None | $5 |
| K4 | 40-80% | 500 MB | None | $80 |
| K5 | 1-2% | 100 MB | +50 MB/1000 games | $50 |
*For the FinOps governance extension, we model a hypothetical cloud/SaaS deployment scenario with 10,000 concurrent users to illustrate cost behavior and scaling characteristics. The current implementation is a local desktop application.
| Feature | C4 | arc42 | This Framework |
|---|---|---|---|
| System Context | ✅ | ✅ | ✅ C1 |
| Container View | ✅ | ❌ | ✅ C2 |
| Runtime View | ❌ | ✅ | ✅ Ch6 |
| Quality Scenarios | ❌ | ✅ | ✅ Ch10 |
| ADRs | ❌ | ✅ | ✅ Ch9 |
| Dependency Enforcement | ❌ | ❌ | ✅ Allowed-to-Use Matrix |
| Change Impact | ❌ | ❌ | ✅ Heatmap |
| Cost/Resource Tracking | ❌ | ❌ | ✅ FinOps + Sustainability |
| Visual Semantics | ❌ | ✅ Color + Frame + Size | |
| Automated Checks | ❌ | ❌ | ✅ Dependency violations |
This documentation can be automatically converted to PDF:
# Uses GitHub Actions workflow (.github/workflows/mdtopdf.yml)
git push
# PDF generated in /images/ folder