# Architecture Decisions

Documentation of key design decisions for Bubble Tea Maintenance Agent.

## Core Purpose Decision

**Decision**: Focus on maintenance/debugging of existing Bubble Tea apps, not design

**Rationale**:
- ✅ Complements `bubbletea-designer` agent (design) with maintenance agent (upkeep)
- ✅ Different problem space: diagnosis vs creation
- ✅ Users have existing apps that need optimization
- ✅ Maintenance is ongoing, design is one-time

**Alternatives Considered**:
- Combined design+maintenance agent: Too broad, conflicting concerns
- Generic Go linter: Misses Bubble Tea-specific patterns

---

## Data Source Decision

**Decision**: Use local tip-bubbltea-apps.md file as knowledge base

**Rationale**:
- ✅ No internet required (offline capability)
- ✅ Fast access (local file system)
- ✅ Expert-curated knowledge (leg100.github.io)
- ✅ 11 specific, actionable tips
- ✅ Can be updated independently

**Alternatives Considered**:
- Web scraping: Fragile, requires internet, slow
- Embedded knowledge: Hard to update, limited
- API: Rate limits, auth, network dependency

**Trade-offs**:
- User needs to have tip file locally
- Updates require manual file replacement

---

## Analysis Approach Decision

**Decision**: 6 separate specialized functions + 1 orchestrator

**Rationale**:
- ✅ Single Responsibility Principle
- ✅ Composable - can use individually or together
- ✅ Testable - each function independently tested
- ✅ Flexible - run quick diagnosis or deep analysis

**Structure**:
1. `diagnose_issue()` - General problem identification
2. `apply_best_practices()` - Validate against 11 tips
3. `debug_performance()` - Performance bottleneck detection
4. `suggest_architecture()` - Refactoring recommendations
5. `fix_layout_issues()` - Lipgloss layout fixes
6. `comprehensive_analysis()` - Orchestrates all 5

**Alternatives Considered**:
- Single monolithic function: Hard to test, maintain, customize
- 20 micro-functions: Too granular, confusing
- Plugin architecture: Over-engineered for v1.0

---

## Code Parsing Strategy

**Decision**: Regex-based parsing instead of AST

**Rationale**:
- ✅ Fast - no parse tree construction
- ✅ Simple - easy to understand, maintain
- ✅ Good enough - catches 90% of issues
- ✅ No external dependencies (go/parser)
- ✅ Cross-platform - pure Python

**Alternatives Considered**:
- AST parsing (go/parser): More accurate but slow, complex
- Token-based: Middle ground, still complex
- LLM-based: Overkill, slow, requires API

**Trade-offs**:
- May miss edge cases (rare nested structures)
- Can't detect all semantic issues
- Good for pattern matching, not deep analysis

**When to upgrade to AST**:
- v2.0 if accuracy becomes critical
- If false positive rate >5%
- If complex refactoring automation is added

---

## Validation Strategy

**Decision**: Multi-layer validation with severity levels

**Rationale**:
- ✅ Early error detection
- ✅ Clear prioritization (CRITICAL > WARNING > INFO)
- ✅ Actionable feedback
- ✅ User can triage fixes

**Severity Levels**:
- **CRITICAL**: Breaks UI, must fix immediately
- **HIGH**: Significant performance/reliability impact
- **MEDIUM**: Noticeable but not critical
- **WARNING**: Best practice violation
- **LOW**: Minor optimization
- **INFO**: Suggestions, not problems

**Validation Layers**:
1. Input validation (paths exist, files readable)
2. Structure validation (result format correct)
3. Content validation (scores in range, fields present)
4. Semantic validation (recommendations make sense)

---

## Performance Threshold Decision

**Decision**: Update() <16ms, View() <3ms targets

**Rationale**:
- 16ms = 60 FPS (1000ms / 60 = 16.67ms)
- View() should be faster (called more often)
- Based on Bubble Tea best practices
- Leaves budget for framework overhead

**Measurement**:
- Static analysis (pattern detection, not timing)
- Identifies blocking operations
- Estimates based on operation type:
  - HTTP request: 50-200ms
  - File I/O: 1-100ms
  - Regex compile: 1-10ms
  - String concat: 0.1-1ms per operation

**Future**: v2.0 could integrate pprof for actual measurements

---

## Architecture Pattern Decision

**Decision**: Heuristic-based pattern detection and recommendations

**Rationale**:
- ✅ Works without user input
- ✅ Based on complexity metrics
- ✅ Provides concrete steps
- ✅ Includes code templates

**Complexity Scoring** (0-100):
- File count (10 points max)
- Model field count (20 points)
- Update() case count (20 points)
- View() line count (15 points)
- Custom message count (10 points)
- View function count (15 points)
- Concurrency usage (10 points)

**Pattern Recommendations**:
- <30: flat_model (simple)
- 30-70: multi_view or component_based (medium)
- 70+: model_tree (complex)

---

## Best Practices Integration

**Decision**: Map each of 11 tips to automated checks

**Rationale**:
- ✅ Leverages expert knowledge
- ✅ Specific, actionable tips
- ✅ Comprehensive coverage
- ✅ Education + validation

**Tip Mapping**:
1. Fast event loop → Check for blocking ops in Update()
2. Debug dumping → Look for spew/io.Writer
3. Live reload → Check for air config
4. Receiver methods → Validate Update() receiver type
5. Message ordering → Check for state tracking
6. Model tree → Analyze model complexity
7. Layout arithmetic → Validate lipgloss.Height() usage
8. Terminal recovery → Check for defer/recover
9. teatest → Look for test files
10. VHS → Check for .tape files
11. Resources → Info-only

---

## Error Handling Strategy

**Decision**: Return errors in result dict, never raise exceptions

**Rationale**:
- ✅ Graceful degradation
- ✅ Partial results still useful
- ✅ Easy to aggregate errors
- ✅ Doesn't break orchestrator

**Format**:
```python
{
    "error": "Description",
    "validation": {
        "status": "error",
        "summary": "What went wrong"
    }
}
```

**Philosophy**:
- Better to return partial analysis than fail completely
- User can act on what was found
- Errors are just another data point

---

## Report Format Decision

**Decision**: JSON output with CLI-friendly summary

**Rationale**:
- ✅ Machine-readable (JSON for tools)
- ✅ Human-readable (CLI summary)
- ✅ Composable (can pipe to jq, etc.)
- ✅ Saveable (file output)

**Structure**:
```python
{
    "overall_health": 75,
    "sections": {
        "issues": {...},
        "best_practices": {...},
        "performance": {...},
        "architecture": {...},
        "layout": {...}
    },
    "priority_fixes": [...],
    "summary": "Executive summary",
    "estimated_fix_time": "2-4 hours",
    "validation": {...}
}
```

---

## Testing Strategy

**Decision**: Unit tests per function + integration tests

**Rationale**:
- ✅ Each function independently tested
- ✅ Integration tests verify orchestration
- ✅ Test fixtures for common scenarios
- ✅ ~90% code coverage target

**Test Structure**:
```
tests/
├── test_diagnose_issue.py       # diagnose_issue() tests
├── test_best_practices.py       # apply_best_practices() tests
├── test_performance.py          # debug_performance() tests
├── test_architecture.py         # suggest_architecture() tests
├── test_layout.py               # fix_layout_issues() tests
└── test_integration.py          # End-to-end tests
```

**Test Coverage**:
- Happy path (valid code)
- Edge cases (empty files, no functions)
- Error cases (invalid paths, bad Go code)
- Integration (orchestrator combines correctly)

---

## Documentation Strategy

**Decision**: Comprehensive SKILL.md + reference docs

**Rationale**:
- ✅ Self-contained (agent doesn't need external docs)
- ✅ Examples for every pattern
- ✅ Education + automation
- ✅ Quick reference guides

**Documentation Files**:
1. **SKILL.md** - Complete agent instructions (8,000 words)
2. **README.md** - Quick start guide
3. **common_issues.md** - Problem/solution catalog
4. **CHANGELOG.md** - Version history
5. **DECISIONS.md** - This file
6. **INSTALLATION.md** - Setup guide

---

## Future Enhancements

**v2.0 Ideas**:
- AST-based parsing for higher accuracy
- Integration with pprof for actual profiling data
- Automated fix application (not just suggestions)
- Custom rule definitions
- Visual reports
- CI/CD integration
- GitHub Action for PR checks
- VSCode extension integration

**Criteria for v2.0**:
- User feedback indicates accuracy issues
- False positive rate >5%
- Users request automated fixes
- Adoption reaches 100+ users

---

**Built with Claude Code agent-creator on 2025-10-19**