159 lines
4.4 KiB
Markdown
159 lines
4.4 KiB
Markdown
# Architecture Decisions
|
|
|
|
Documentation of key design decisions for Bubble Tea Designer skill.
|
|
|
|
## Data Source Decision
|
|
|
|
**Decision**: Use local charm-examples-inventory instead of API
|
|
**Rationale**:
|
|
- ✅ No rate limits or authentication needed
|
|
- ✅ Fast lookups (local file system)
|
|
- ✅ Complete control over inventory structure
|
|
- ✅ Offline capability
|
|
- ✅ Inventory can be updated independently
|
|
|
|
**Alternatives Considered**:
|
|
- GitHub API: Rate limits, requires authentication
|
|
- Web scraping: Fragile, slow, unreliable
|
|
- Embedded database: Adds complexity, harder to update
|
|
|
|
**Trade-offs**:
|
|
- User needs to have inventory locally (optional but recommended)
|
|
- Updates require re-cloning repository
|
|
|
|
## Analysis Approach
|
|
|
|
**Decision**: 6 separate analysis functions + 1 comprehensive orchestrator
|
|
**Rationale**:
|
|
- ✅ Modularity - each function has single responsibility
|
|
- ✅ Testability - easy to test individual components
|
|
- ✅ Flexibility - users can call specific analyses
|
|
- ✅ Composability - orchestrator combines as needed
|
|
|
|
**Structure**:
|
|
1. analyze_requirements() - NLP requirement extraction
|
|
2. map_components() - Component scoring and selection
|
|
3. select_patterns() - Example file matching
|
|
4. design_architecture() - Structure generation
|
|
5. generate_workflow() - Implementation planning
|
|
6. comprehensive_tui_design_report() - All-in-one
|
|
|
|
## Component Matching Algorithm
|
|
|
|
**Decision**: Keyword-based scoring with manual taxonomy
|
|
**Rationale**:
|
|
- ✅ Transparent - users can see why components selected
|
|
- ✅ Predictable - consistent results
|
|
- ✅ Fast - O(n) search with indexing
|
|
- ✅ Maintainable - easy to add new components
|
|
|
|
**Alternatives Considered**:
|
|
- ML-based matching: Overkill, requires training data
|
|
- Fuzzy matching: Less accurate for technical terms
|
|
- Rule-based expert system: Too rigid
|
|
|
|
**Scoring System**:
|
|
- Keyword match: 60 points max
|
|
- Use case match: 40 points max
|
|
- Total: 0-100 score per component
|
|
|
|
## Architecture Generation Strategy
|
|
|
|
**Decision**: Template-based with customization
|
|
**Rationale**:
|
|
- ✅ Generates working code immediately
|
|
- ✅ Follows Bubble Tea best practices
|
|
- ✅ Customizable per archetype
|
|
- ✅ Educational - shows proper patterns
|
|
|
|
**Templates Include**:
|
|
- Model struct with components
|
|
- Init() with proper initialization
|
|
- Update() skeleton with message routing
|
|
- View() with component rendering
|
|
|
|
## Validation Strategy
|
|
|
|
**Decision**: Multi-layer validation (requirements, components, architecture, workflow)
|
|
**Rationale**:
|
|
- ✅ Early error detection
|
|
- ✅ Quality assurance
|
|
- ✅ Helpful feedback to users
|
|
- ✅ Catches incomplete designs
|
|
|
|
**Validation Levels**:
|
|
- CRITICAL: Must fix (empty description, no components)
|
|
- WARNING: Should review (low coverage, many components)
|
|
- INFO: Optional improvements
|
|
|
|
## File Organization
|
|
|
|
**Decision**: Modular scripts with shared utilities
|
|
**Rationale**:
|
|
- ✅ Clear separation of concerns
|
|
- ✅ Reusable utilities
|
|
- ✅ Easy to test
|
|
- ✅ Maintainable codebase
|
|
|
|
**Structure**:
|
|
```
|
|
scripts/
|
|
main analysis scripts (6)
|
|
utils/
|
|
shared utilities
|
|
validators/
|
|
validation logic
|
|
```
|
|
|
|
## Pattern Matching Approach
|
|
|
|
**Decision**: Inventory-based with ranking
|
|
**Rationale**:
|
|
- ✅ Leverages existing examples
|
|
- ✅ Provides concrete references
|
|
- ✅ Study order optimization
|
|
- ✅ Realistic time estimates
|
|
|
|
**Ranking Factors**:
|
|
- Component usage overlap
|
|
- Complexity match
|
|
- Code quality/clarity
|
|
|
|
## Documentation Strategy
|
|
|
|
**Decision**: Comprehensive references with patterns and best practices
|
|
**Rationale**:
|
|
- ✅ Educational value
|
|
- ✅ Self-contained skill
|
|
- ✅ Reduces external documentation dependency
|
|
- ✅ Examples for every pattern
|
|
|
|
**References Created**:
|
|
- Component guide (what each component does)
|
|
- Design patterns (common architectures)
|
|
- Best practices (dos and don'ts)
|
|
- Example designs (complete real-world cases)
|
|
|
|
## Performance Considerations
|
|
|
|
**Optimizations**:
|
|
- Inventory loaded once, cached in memory
|
|
- Pre-computed component taxonomy
|
|
- Fast keyword matching (no regex)
|
|
- Minimal allocations in hot paths
|
|
|
|
**Trade-offs**:
|
|
- Memory usage: ~5MB for loaded inventory
|
|
- Startup time: ~100ms for inventory loading
|
|
- Analysis time: <1 second for complete report
|
|
|
|
## Future Enhancements
|
|
|
|
Potential improvements for v2.0:
|
|
- Interactive mode for requirement refinement
|
|
- Code generation (full implementation, not just scaffolding)
|
|
- Live preview of designs
|
|
- Integration with Go module initialization
|
|
- Custom component definitions
|
|
- Save/load design sessions
|