zhongwei/gh-human-frontier-labs-inc-human-frontier-labs-marketplace-plugins-bubbletea-designer

Fork 0

Files

Zhongwei Li 48d6099939 Initial commit

2025-11-29 18:47:30 +08:00

4.4 KiB

Raw Blame History

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:

analyze_requirements() - NLP requirement extraction
map_components() - Component scoring and selection
select_patterns() - Example file matching
design_architecture() - Structure generation
generate_workflow() - Implementation planning
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