Epic: Grounded C4 Architecture Modeling System

[iheitlager]

Epic: Grounded C4 Architecture Modeling System

Integrate architecture modeling with OpenSpec using the Grounded C4 approach.

Overview

Extend OpenSpec to include architectural modeling alongside behavioral specifications. This enables:

• Modeling system architecture with concrete resources (not abstract C4 containers)
• Progressive zoom from landscape → domain → service → interface
• Behavioral modeling with sequences and state machines
• Traceability from specs → architecture → implementation
• Reverse engineering to extract architecture from codebases

Key Innovation

Concrete-first modeling: Model actual resources with specific types (e.g., rds-postgresql, elasticache-redis) instead of abstract classifications (Container, Component).

Phases

Phase 1: Core Modeling (MVP) - ~19 days

• Define YAML schemas for resources and relationships
• Implement arch CLI tool with basic commands
• Validate models (schema + referential integrity)
• Generate Mermaid diagrams
• Model dotfiles architecture as proof-of-concept

Phase 2: Behavioral Modeling - ~11 days

• Add sequence and state machine definitions
• Link sequences to spec scenarios
• Generate UML sequence diagrams and state diagrams

Phase 3: Reverse Engineering - ~7 days

• Extract resources from config files
• Detect interfaces from code
• Coverage tracking (documented vs. actual)

Phase 4: Advanced Tooling - ~8 days

• Interactive fzf browser
• Dependency visualization
• Impact analysis
• ADR integration

Total Estimate

~47 days (approximately 9-10 weeks for solo developer)

References

• Proposal: .openspec/changes/grounded-c4-architecture/proposal.md
• Tasks: .openspec/changes/grounded-c4-architecture/tasks.md
• Spec: .openspec/specs/008-grounded-c4-architecture/spec.md
• Design Doc: docs/grounded-c4.md
• Branch: feat/grounded-c4-architecture

Success Criteria

1. ✅ Spec-Architecture Traceability: Every spec requirement can link to architecture resources
2. ✅ Code Traceability: Every architecture resource can link to implementation code
3. ✅ Validation: Architecture models are validated for consistency and completeness
4. ✅ Visualization: Can generate C4-style diagrams at multiple zoom levels
5. ✅ Reverse Engineering: Can extract architecture from existing codebases
6. ✅ Adoption: Successfully model dotfiles system architecture and link to existing specs

---

🤖 Created by Claude