diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..d83a6e3 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,86 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Build & Test Commands + +```bash +# Build +xcodebuild -project PlantGuide.xcodeproj -scheme PlantGuide -configuration Debug + +# Run all tests +xcodebuild test -project PlantGuide.xcodeproj -scheme PlantGuide -destination 'platform=iOS Simulator,name=iPhone 16' + +# Run a single test class +xcodebuild test -project PlantGuide.xcodeproj -scheme PlantGuide -destination 'platform=iOS Simulator,name=iPhone 16' -only-testing:PlantGuideTests/HybridIdentificationUseCaseTests + +# Run a single test method +xcodebuild test -project PlantGuide.xcodeproj -scheme PlantGuide -destination 'platform=iOS Simulator,name=iPhone 16' -only-testing:PlantGuideTests/SavePlantUseCaseTests/testSavePlant_Success +``` + +## Architecture + +**Clean Architecture + MVVM** with three main layers: + +``` +Presentation (SwiftUI Views + ViewModels) + ↓ +Domain (Use Cases + Entities + Repository Protocols) + ↓ +Data (Repository Implementations + Data Sources) +``` + +### Key Patterns + +- **Dependency Injection**: `DIContainer` (singleton) provides all dependencies via `LazyService` wrappers +- **Use Cases**: Each user action is a separate use case class (e.g., `SavePlantUseCase`, `HybridIdentificationUseCase`) +- **Repository Pattern**: Protocols in Domain layer, implementations in Data layer +- **Actor-based Concurrency**: `PlantClassificationService` and Core Data access use actors for thread safety +- **ViewModels**: `@MainActor @Observable` classes, created via `DIContainer.makeXxxViewModel()` + +### Data Flow Example + +``` +CameraView → IdentificationViewModel → HybridIdentificationUseCase + → PlantClassificationService (on-device ML) + → PlantNetAPIService (online fallback) + → IdentificationView (results) +``` + +### Directory Structure + +- `App/` - Entry point, configuration, API keys +- `Core/DI/` - DIContainer and LazyService +- `Domain/` - Business logic: Entities, UseCases, RepositoryInterfaces +- `Data/` - Persistence: CoreData, Repositories, API services, Mappers +- `ML/` - Core ML inference service and image preprocessing +- `Presentation/` - SwiftUI views, ViewModels, navigation + +## External Services + +- **PlantNet API** (`my.plantnet.org`) - Plant identification via image upload (500 free/day) +- **Trefle API** (`trefle.io`) - Botanical care data (400K+ species) +- **Local Database** - `Resources/houseplants_list.json` (2,278 species) + +API keys configured in `App/Configuration/APIKeys.swift` via environment variables. + +## ML Model + +PlantNet-300K ResNet50 for on-device plant classification: +- Input: 224x224 RGB image with ImageNet normalization +- Output: 1,081 plant species probabilities +- Conversion scripts in `scripts/` directory + +## Known Issues + +See `Docs/ARCHITECTURE_REMEDIATION_PLAN.md` for pre-production fixes: +- `InMemoryPlantRepository` doesn't conform to `PlantRepositoryProtocol` +- `CoreDataStack` lazy var initialization isn't thread-safe +- `DIContainer` uses `unowned self` in closures (crash risk) +- SwiftData initialized but unused (Core Data is the actual persistence layer) + +## Testing + +- Unit tests in `PlantGuideTests/` with mock implementations in `Mocks/` +- Test fixtures available for `Plant`, `CareTask`, `PlantCareSchedule` +- Mock services: `MockPlantCollectionRepository`, `MockNetworkService`, etc. diff --git a/Docs/COMPETITIVE_ANALYSIS.md b/Docs/COMPETITIVE_ANALYSIS.md new file mode 100644 index 0000000..1aea414 --- /dev/null +++ b/Docs/COMPETITIVE_ANALYSIS.md @@ -0,0 +1,359 @@ +# PlantGuide Competitive Analysis + +*Prepared: January 2026* + +## Executive Summary + +This analysis examines the top 5 iOS plant identification apps to identify opportunities for PlantGuide to differentiate and become the leading plant app for casual houseplant owners. The market is dominated by subscription-based apps with aggressive paywalls. **PlantGuide's free model represents a significant competitive advantage** if paired with strong identification accuracy and thoughtful care features. + +--- + +## Market Overview + +### Pricing Landscape + +| App | Pricing Model | Annual Cost | Free Limitations | +|-----|--------------|-------------|------------------| +| **PlantIn** | Subscription | $19.99/yr ($7.99/wk) | Very limited scans | +| **PictureThis** | Subscription | $29.99/yr | ~3 free IDs | +| **Planta** | Subscription | $35.99/yr | Limited plants & reminders | +| **Blossom** | Subscription | $29.99/yr ($4.99/mo) | 3 IDs, 2 reminders only | +| **Seek by iNaturalist** | **Free** | $0 | None (fully free) | +| **PlantGuide** | **Free** | $0 | None (fully free) | + +**Key Insight**: Users consistently complain about aggressive paywalls, forced subscriptions, and limited free tiers. A free, fully-featured app addresses the #1 user frustration in this market. + +--- + +## Competitor Deep Dive + +### 1. PlantIn +**Rating**: 4.6 stars | **Species Database**: 17,000+ + +**Standout Features**: +- AR light meter (measures actual light levels for plant placement) +- Smart watering schedules adjusted by season, rainfall, and species +- 24/7 botanist consultations +- Automatic outdoor plant watering skip when it rains + +**What Users Love**: +- Intelligent, personalized care schedules +- Clean, modern interface +- Botanist access for tricky questions + +**What Users Hate**: +- Expensive weekly pricing ($7.99/week = $415/year if not careful) +- Bonsai/specialty plant identification is poor +- Aggressive upselling + +**Accuracy**: Struggles with specialty plants, bonsai, regional varieties + +--- + +### 2. PictureThis +**Rating**: 4.6 stars | **Species Database**: 400,000+ | **Claimed Accuracy**: 98% + +**Standout Features**: +- Largest species database +- Disease/pest diagnosis with treatment recommendations +- Light meter functionality +- Detailed plant care encyclopedia + +**What Users Love**: +- Highest tested accuracy (78% in independent testing) +- Comprehensive plant information +- Disease identification + +**What Users Hate**: +- $29.99/year paywall hits quickly +- Accuracy claims (98%) don't match real-world testing (78%) +- Struggles with pepper varieties, regional plants + +**Accuracy**: Best in class at 78% in independent 234-image test + +--- + +### 3. Planta +**Rating**: 4.8 stars | **App Store Editor's Choice 2022** + +**Standout Features**: +- Most comprehensive care scheduling system +- Room-by-room plant organization +- Seasonal care adjustments +- Beautiful, polished UI + +**What Users Love**: +- Editor's Choice quality UI/UX +- Detailed, specific care instructions +- Plant journal/progress tracking + +**What Users Hate**: +- Most expensive at $35.99/year +- Free version is extremely limited +- Heavy focus on care over identification + +**Positioning**: Care-first app, identification secondary + +--- + +### 4. Seek by iNaturalist +**Rating**: 4.8 stars | **Fully Free** + +**Standout Features**: +- Kid-safe (no account required, no data collection) +- Gamification with badges, challenges, achievements +- Backed by California Academy of Sciences & National Geographic +- Citizen science contribution +- Works offline with pre-downloaded data + +**What Users Love**: +- Completely free with no paywalls +- Educational and fun for families +- Privacy-focused +- No ads + +**What Users Hate**: +- Camera can't zoom (must use phone camera separately) +- GPS/location sometimes inaccurate +- Need very clear photos for identification +- No care features (identification only) + +**Accuracy**: Good for common species, struggles with regional specificity + +--- + +### 5. Blossom +**Rating**: 4.7 stars | **Species Database**: 30,000+ + +**Standout Features**: +- Care content sourced from The Spruce (trusted gardening resource) +- Integrated plant/tool shopping +- Flexible schedule adjustments (snooze, custom intervals) +- Health diagnosis + +**What Users Love**: +- Beginner-friendly design +- Trusted care content +- Schedule flexibility + +**What Users Hate**: +- Forced questionnaire for every plant added +- iOS version missing light meter (Android has it) +- Only 3 free IDs, then hard paywall +- Pop-up upgrade prompts + +**Accuracy**: Quick and effective, 30K plant database + +--- + +## Common User Complaints Across All Apps + +### Identification Issues +1. **Pepper varieties** - Apps consistently identify all peppers as "cayenne" +2. **Specialty/exotic plants** - Bonsai, southern hemisphere plants, rare species +3. **Similar species confusion** - Related plants default to more common choice +4. **Photo quality dependency** - Shadows, lighting, zoom cause failures + +### Feature Complaints +1. **Aggressive paywalls** - Limited free IDs, constant upgrade prompts +2. **Inaccurate GPS** - Wrong region affects suggestions +3. **Forced data entry** - Mandatory questionnaires annoy users +4. **Ad frequency** - Even paid tiers have promotional content + +### Safety Concerns +- **Toxic plant misidentification** - Apps should never be sole ID source for foraging +- Medical researchers found apps "not ready for stand-alone identification" of toxic plants + +--- + +## PlantGuide Current State + +### Existing Features +| Feature | Status | Notes | +|---------|--------|-------| +| Plant Identification | Hybrid (On-device ML + PlantNet API) | Dual-approach for accuracy | +| Plant Collection | Implemented | Favorites, notes, filtering | +| Care Schedules | Implemented | Auto-generated from Trefle API | +| Care Reminders | Implemented | Local notifications | +| Camera Capture | Implemented | Photo library + camera | +| Offline Support | Partial | On-device ML, cached care info | +| Image Storage | Implemented | Local with Core Data | + +### Strengths +- **Free with no paywalls** - Major differentiator +- **Hybrid identification** - On-device ML + API fallback +- **Clean architecture** - Well-structured for future features +- **Care info caching** - Reduced API calls, better UX + +### Gaps vs. Competitors +- No light meter +- No disease/pest diagnosis +- No gamification/achievements +- No weather-based schedule adjustments +- Limited species database (vs. PictureThis 400K) +- No plant shopping integration + +--- + +## Strategic Recommendations + +### Priority 1: Identification Accuracy (Critical) + +**Why**: Accuracy is the #1 factor for user satisfaction. Independent testing shows even "98% accurate" claims only achieve 78% in practice. + +**Recommendations**: +1. **Expand on-device model** - Consider PlantNet's 300K+ species dataset +2. **Multi-result display** - Show top 3-5 matches with confidence scores (users want options, not single answers) +3. **Manual correction flow** - Let users correct misidentifications (improves trust) +4. **Regional optimization** - Use location to prioritize likely species +5. **Photo guidance** - Real-time hints for better photos (lighting, angle, zoom) + +### Priority 2: Care Features Enhancement (High) + +**Why**: Care features drive daily engagement and retention. + +**Recommendations**: +1. **Weather-aware scheduling** - Skip watering reminders when it rains (PlantIn's top feature) +2. **Seasonal adjustments** - Auto-adjust care schedules by season +3. **Flexible snoozing** - Let users delay tasks without penalty +4. **Progress photos** - Time-lapse/growth tracking journal +5. **Batch actions** - "Water all" button for multiple plants + +### Priority 3: UI/UX Polish (Medium-High) + +**Why**: Planta won Editor's Choice purely on UI quality. + +**Recommendations**: +1. **Plant rooms/zones** - Organize by location (kitchen, bedroom, patio) +2. **Quick add flow** - Minimal required fields, optional deep-dive +3. **Today view** - Dashboard of today's care tasks +4. **Subtle animations** - Plant growth, watering feedback +5. **Dark mode** - Essential for modern apps + +### Priority 4: Differentiation Features (Medium) + +**Features to Consider**: +| Feature | Effort | Impact | Notes | +|---------|--------|--------|-------| +| Light Meter (AR) | High | High | PlantIn's killer feature | +| Disease Diagnosis | High | High | PictureThis differentiator | +| Achievements/Badges | Low | Medium | Seek's engagement driver | +| Offline Mode | Medium | Medium | Already partial | +| Widget Support | Low | Medium | Quick task view | +| Plant Sitter Mode | Low | Medium | Vacation instructions for others | + +### Priority 5: Features to AVOID + +Based on user requirements and competitive analysis: + +| Feature | Reason to Avoid | +|---------|-----------------| +| Social Network | User explicitly excluded; adds complexity | +| Marketplace/Shopping | User explicitly excluded; distracts from core | +| Subscription Model | Free model is the differentiator | +| Mandatory Questionnaires | #1 Blossom complaint | +| Aggressive Prompts | Major user frustration across all apps | + +--- + +## Competitive Positioning Strategy + +### Target Positioning +**"The free plant app that actually works"** + +### Key Messages +1. **Free forever** - No paywalls, no limited trials, no "premium" features +2. **Honest accuracy** - Multi-result display, never claim 98% +3. **Respect users** - No forced sign-ups, no mandatory questionnaires +4. **Privacy-first** - Minimal data collection (like Seek) + +### vs. Each Competitor + +| Competitor | PlantGuide Advantage | +|------------|---------------------| +| PlantIn | Free vs. $20-415/year; no aggressive upselling | +| PictureThis | Free vs. $30/year; honest about accuracy | +| Planta | Free vs. $36/year; full features in free tier | +| Blossom | Free vs. $30/year; no forced questionnaires | +| Seek | Better care features; identification + care combo | + +--- + +## Implementation Roadmap + +### Phase 1: Foundation (Current) +- [x] Plant identification (hybrid approach) +- [x] Collection management +- [x] Care schedules with reminders +- [x] Offline caching + +### Phase 2: Accuracy & Polish +- [ ] Multi-result identification display +- [ ] Photo capture guidance +- [ ] Quick add flow optimization +- [ ] Today dashboard view +- [ ] Room/zone organization + +### Phase 3: Smart Care +- [ ] Weather-aware scheduling +- [ ] Seasonal care adjustments +- [ ] Flexible task snoozing +- [ ] Progress photo journal +- [ ] Batch care actions + +### Phase 4: Differentiation +- [ ] Light meter (AR-based) +- [ ] Disease/pest diagnosis +- [ ] Achievements & badges +- [ ] Widget support +- [ ] Plant sitter mode + +--- + +## Success Metrics + +### Identification Quality +- Target: 75%+ accuracy (match PictureThis benchmark) +- User correction rate < 20% +- Time to identification < 3 seconds + +### Engagement +- Daily active users returning for care tasks +- Average plants per collection > 5 +- Care task completion rate > 70% + +### Growth +- Organic App Store rating > 4.5 stars +- Word-of-mouth referral mentions +- "Free plant app" search ranking + +--- + +## Conclusion + +The plant app market is ripe for disruption. Every major competitor uses aggressive subscription models that frustrate users. **PlantGuide's free model is its superpower** - but only if paired with competitive accuracy and thoughtful features. + +Focus on: +1. **Identification accuracy** - The foundation of trust +2. **Smart care features** - Weather-aware, seasonal, flexible +3. **Respectful UX** - No forced data entry, no dark patterns +4. **Gradual feature expansion** - Light meter and disease diagnosis as differentiators + +The goal isn't to copy competitors - it's to deliver what users actually want without the subscription tax. + +--- + +## Sources + +- [PlantIn App Review](https://skywork.ai/blog/plantin-app-review-2025/) +- [Best Plant Care Apps 2026 - PlantIn Blog](https://myplantin.com/blog/best-plant-care-apps) +- [Best Plant Identification Apps 2026](https://myplantin.com/blog/best-plant-identification-apps) +- [CNN Underscored - Best Plant Identification Apps](https://www.cnn.com/cnn-underscored/reviews/best-plant-identification-app) +- [Seek by iNaturalist - App Store](https://apps.apple.com/us/app/seek-by-inaturalist/id1353224144) +- [Seek by iNaturalist - Common Sense Media Review](https://www.commonsensemedia.org/app-reviews/seek-by-inaturalist) +- [Blossom - App Store](https://apps.apple.com/us/app/blossom-plant-care-guide/id1487453649) +- [Best Plant Care Apps 2025 - Tested & Compared](https://plantapp-reviews.com/blog/best-plant-care-apps) +- [Plant ID Apps Tested - GrowIt BuildIt](https://growitbuildit.com/plant-identification-apps-tested/) +- [Digital Trends - Plant ID App Accuracy Test](https://www.digitaltrends.com/phones/i-tried-three-plant-identification-apps-and-one-was-deadly/) +- [PMC - Plant ID App Accuracy for Toxic Plants](https://pmc.ncbi.nlm.nih.gov/articles/PMC7785603/) +- [iGeeksBlog - Best Plant Care Apps 2026](https://www.igeeksblog.com/best-plant-care-apps/)