Objective
Create comprehensive ARCHITECTURE.md documentation that explains the codebase's 5 distinct architectural patterns and design decisions.
Context
The schema consistency analysis identified 5 well-organized architectural patterns that govern how features are implemented:
- Complex Feature Architecture (5+ files per feature)
- Passthrough Extraction (14 simple fields)
- Core Infrastructure (37 foundation files)
- Feature-Specific (1-2 files per feature)
- Safe-Output Operations (30+ operation files)
This documentation will help new contributors understand when to use each pattern and maintain architectural consistency.
Approach
- Create
ARCHITECTURE.md in repository root
- Document each of the 5 architectural patterns with:
- Description and use cases
- Examples from codebase
- Decision tree for when to use
- File organization guidelines
- Document file naming conventions (dash in YAML/schema, underscore in Go files)
- Explain safe-output operation structure and registration pattern
- Include metrics: 194 implementation files, 2.4:1 test ratio
- Add examples for each pattern from existing code
Files to Modify
- Create:
ARCHITECTURE.md (new documentation file)
- Update:
README.md (add link to ARCHITECTURE.md)
- Update:
CONTRIBUTING.md (reference architectural patterns)
Acceptance Criteria
Reference
See discussion #8372 for detailed pattern breakdown and file statistics.
Related to #8374
AI generated by Plan Command for discussion #8372
Objective
Create comprehensive ARCHITECTURE.md documentation that explains the codebase's 5 distinct architectural patterns and design decisions.
Context
The schema consistency analysis identified 5 well-organized architectural patterns that govern how features are implemented:
This documentation will help new contributors understand when to use each pattern and maintain architectural consistency.
Approach
ARCHITECTURE.mdin repository rootFiles to Modify
ARCHITECTURE.md(new documentation file)README.md(add link to ARCHITECTURE.md)CONTRIBUTING.md(reference architectural patterns)Acceptance Criteria
Reference
See discussion #8372 for detailed pattern breakdown and file statistics.
Related to #8374