Skip to content

MVP Scope

Jump to bottom
arudaev edited this page Apr 7, 2026 · 5 revisions

MVP Scope

Status: Defined - Ready for implementation

Target: Prove core concepts (device linking, skill tree progression, conditional builds, on-device CV)

MVP Features

Platform Coverage

  • Mobile (iOS + Android via React Native)
  • Desktop (Windows/Mac/Linux via Tauri)
  • No Web (defer to v2)

Why both platforms?

  • Mobile = primary UI, camera, daily tasks
  • Desktop = processing hub for CV/ML, proves device linking

Core Features

1. Device Linking (QR + BLE Auto-Discovery)

User Flow (BLE):

  1. User opens Desktop app — BLE advertising starts automatically
  2. User opens Mobile app — BLE scan starts automatically in background
  3. Mobile discovers Desktop via BLE, auto-connects via WSS — no user action required
  4. Connection persists across sessions; auto-reconnects on network drop

User Flow (QR fallback):

  1. User opens Desktop app → generates QR code
  2. User opens Mobile app → scans QR code
  3. Devices pair over local network (direct connection, no cloud)

Technical:

  • QR code contains: IP address, port, pairing token
  • BLE advertisement contains: IP address + port (company ID 0xFFFE, 6-byte payload)
  • TLS encryption for all device-to-device WSS communication
  • BLE is discovery-only (proximity trust); QR uses pairing tokens
  • BLE: Windows-first (WinRT); macOS/Linux pluggable later

2. Recycling Validation (Starter Task)

User Flow:

  1. User takes photo of paper bag with recyclables (Mobile camera)
  2. Mobile sends image to linked Desktop
  3. Desktop runs ML model (ONNX Runtime + Rust)
    • Classify: Is this a paper bag? (vs plastic)
    • Detect: Does it contain recyclable items?
  4. Desktop returns validation result to Mobile
  5. If valid → award points, mark task complete

Technical:

  • Pre-trained ONNX model (bag classification)
  • Lightweight model optimized for edge
  • Fallback: If no Desktop linked, prompt user to pair

3. Point System

Mechanics:

  • Recycling task success = 10 points
  • Points stored locally (~/.zelara/progress.json or platform equivalent)
  • Unlock threshold: 50 points → Finance module unlocks

UI:

  • Point counter in app header
  • Progress bar toward next unlock
  • Notification when module unlocked

4. Finance Module (First Unlockable)

Unlocks at: 50 points in Zelara main app → shows "Download Zelara Finance" link

Architecture update (2026-04-05): Finance is a standalone app (apps/finance-mobile/, ai.zelara.finance) built as an independent React Native project from v0.6.0. There is no embed-then-extract step. All business logic lives in src/packages/finance/ (@zelara/finance, pure TS). Full design: Zelara-Finance.md.

v0.6.0 features (see Zelara-Finance.md for full design):

  • Expense logging: Manual entry + receipt OCR via Zelara Core (PaddleOCR v5)
  • Auto-categorization: DistilBERT ONNX on Core, rule-based fallback standalone
  • 4-tab layout: Overview / Transactions / Analytics / Reports
  • Animated charts: Procedural donut, line trend, forecast (Revolut-style)
  • Spend coach: Rule-based insights ("Coffee up 40% vs last month")
  • Forecasting: Linear regression → projected month-end spend
  • Biometric lock: Face ID / fingerprint on every foreground
  • Banking report import: OFX, CSV, PDF, XLSX (mobile + desktop)
  • Android SMS auto-import: READ_SMS → regex bank transaction parsing
  • Donation suggestion: surplus × 5% → green cause
  • Desktop dashboard: full-screen analytics in Zelara Core, drag-and-drop import

Technical:

  • @zelara/finance shared TS package: all business logic, adapters, types, SQL schema
  • Local SQLite — data never leaves the device
  • AI inference (OCR, categorization) delegated to Zelara Core via ai_task WSS messages

5. Conditional Builds

Mechanics:

  1. User's unlock state stored in ~/.zelara/progress.json: 
    {
  "points": 60,
  "unlocked_modules": ["green"],
  "available_unlocks": ["finance"]
}
  2. When user unlocks finance (reaches 50 points):
    • App shows "Update Available" notification
    • User clicks "Update App"
    • Build system pulls module-finance submodule
    • App rebuilds/reloads with finance module
  3. Finance module now appears in navigation

Technical:

  • Manual rebuild for MVP (user-triggered)
  • Git submodule pulling on update
  • Module registry system in core
  • Hot-reload/restart after update

What's NOT in MVP

  • ❌ Web platform (Desktop + Mobile only)
  • ✅ BLE auto-discovery (Windows Desktop → Android Mobile, implemented v0.5.0)
  • ❌ Cloud sync (all data local, no backend)
  • ❌ Productivity module (defer to v2)
  • ❌ Homeowner module (defer to v2)
  • ❌ Marketplace/skins (defer to v2)
  • ❌ Nested submodules (flat module structure only)
  • ❌ Automatic app updates (manual rebuild only)
  • ❌ Complex finance features (no tax prep, no investment tracking)
  • ❌ Multiple recycling tasks (paper bag validation only)

MVP Success Criteria

Core concept validation:

  1. ✅ Device linking works (Mobile ↔ Desktop pairing)
  2. ✅ Task offloading works (Mobile sends image, Desktop processes, returns result)
  3. ✅ ML validation works (on-device classification with acceptable accuracy)
  4. ✅ Point system works (tasks award points, unlock threshold triggers)
  5. ✅ Conditional builds work (finance module appears after unlock)
  6. ✅ Green initiative integration works (donation suggestion accepted/declined)

User experience:

  1. ✅ Pairing is simple (QR code scan)
  2. ✅ Recycling validation feels responsive (< 3 seconds)
  3. ✅ Finance module feels useful (expense logging valuable on its own)
  4. ✅ Unlocking feels rewarding (progress visible, new features exciting)

Technical validation:

  1. ✅ React Native + Tauri architecture works
  2. ✅ TypeScript + Rust hybrid works
  3. ✅ ONNX Runtime performs well on-device
  4. ✅ Git submodule build system works
  5. ✅ Local-first data storage works

This document defines MVP scope. See Architecture.md for the full implementation log.

Clone this wiki locally