motorsignal
/
MotorSignal-App
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
MotorSignal-App/docs/design/motorsignal-hybrid-v1/HANDOFF.md

5.2 KiB
Raw Blame History

HANDOFF.md — MotorSignal Hybrid v1 Architecture & Implementation Notice

1. Prototype Scope & Verification Disclaimer

This handoff package contains visual and interaction design prototypes retrieved from Stitch project 5138779337547529796 ("MotorSignal UI/UX Redesign Exploration"). These specifications establish layout hierarchy, typography, touch target boundaries, and user experience flows for the MotorSignal mobile client (target viewport: 390 × 844 px).

CRITICAL IMPLEMENTATION PRINCIPLE: Mockups represent target client UI. Repository code and backend APIs are authoritative regarding:

  1. Actual binary telemetry storage formats (authoritative SQLite Drift Schema 7, R2 telemetry bundles).
  2. Authoritative Telemetry Acquisition (frozen at 20 Hz / 50 ms via TelemetryService).
  3. Sensor fusion (frozen in SensorFusionService; no independent lean-angle calculations).
  4. Ride lifecycle and motion semantics (frozen in RideStateMachine; 3.0 MPH moving gate, kickstand isolation).
  5. Cloud synchronization and offline sync architecture (SyncManager, SyncOutbox, FirebaseSyncProvider).
  6. Authentication providers and entitlements (free vs pro capabilities).
  7. Existing group ride visibility, roles, and join policies.

Do not implement speculative backend mechanisms or invent hardware capabilities based on UI mockups.

2. Inconsistency Resolutions & Corrections

  1. Replay Telemetry Retrieval Wording:

    • Stitch Replay mockups contain the label "100% Buffered (Local cache)" or references to "100% buffered in-memory".
    • Resolution: In production code and documentation, loading and status wording must reflect the actual telemetry retrieval pipeline (retrieving points from the local SQLite database or streaming/downloading the complete bundle from cloud storage/R2). Do not present speculative "100% buffered in-memory" messaging.

  2. Account Screen Sample Rates and Pro Restrictions:

    • An older mockup displayed Internal Phone IMU: Active (100Hz Gyro / Accel) and claimed Multi-sensor telemetry sync requires Pro subscription.
    • Resolution: Discarded. The authoritative acquisition cadence is 20 Hz (50 ms). Basic telemetry acquisition and synchronization are not restricted by unsupported Pro paywalls; current entitlements and free/pro models documented in the repository are strictly preserved.

  3. Ride Visibility and Join Policies:

    • Preserve all existing group ride visibility, membership, and join policies (public, unlisted, club-only, invite-only, host-approved join requests, participant lists, and role permissions). UI components adapt to these existing models without redefining policies.

  4. Canonical Token Reconciliation (#0B1326 vs #081326):

    • Stitch HTML templates occasionally used #081326 or #0B111E for dark backgrounds.
    • Resolution: Canonical night surface canvas is strictly #0B1326 as defined in DESIGN.md.

  5. Accessibility and Runtime Claims:

    • Visual mockups demonstrate 200% text scaling and proclaim "Contrast Ratio: 18.2:1 (Calc sRGB)" and "Design Target: 48×48px Minimum Target Discipline".
    • Resolution: All accessibility, contrast, and runtime performance claims are treated as unverified until validated with unit/widget tests and on-device / emulator verification.

3. Phased Implementation Roadmap

Phase 1: Mobile App Only (Current Implementation Target)

  1. Shared Day/Night Theme and Reusable Components:
    • Canonical tokens (#0B1326 night canvas, #F8FAFC day canvas, #06B6D4 / #0284C7 brand cyan, #10B981 static green, #F59E0B / #D97706 amber, #EF4444 / #DC2626 red).
    • Reusable cockpit telemetry card containers with 1px border.
    • Pinned riding action buttons with minimum 56dp height and 48dp touch bounds.
    • 6-destination bottom navigation bar with ≥48×48dp hitboxes.
    • Static (non-pulsing) recording status indicator.
  2. Riding Dashboard:
    • High-contrast Speed hero with unit pill.
    • Telemetry metrics (Trip Distance, Elapsed Time, Lean Dynamics with neutral max lean, Elevation Gain, Braking G).
    • Live binding to authoritative telemetryStreamProvider, rideStateMachineProvider, and vehicle profile.
    • Scrollable telemetry container for accessibility text scales, maintaining pinned Pause and Finish controls.
  3. Authenticated Group Ride Hub:
    • Decoupled meeting logistics row (Date, Time, Staging point) to prevent collision with action buttons.
    • Segmented Feed / Hub switcher with ≥48dp touch targets.
    • Ride cards supporting Host ("Manage Ride", "Open Hub") and Member ("Ride Details", "Leave Pack") states.
    • Binding to live groupRideServiceProvider and user state.

Phase 2: Planned Client Roadmap (Future Implementation)

  • 2-step Create Group Ride wizard (staging typeahead, date/time pickers, access review, QR rendezvous code).
  • Route calculation engine loading and fallback states ("direct distance—not a road route").
  • Share ride sheet with recipient dispatch (Clubs, rider DMs, GPX export).
  • Explicit scoped deletion dialog (Local cache only vs Cloud & local deletion).

Phase 3: Capabilities Requiring Further Discovery

  • External BLE sensor GATT protocol integration.
  • Two-factor authentication (2FA) setup flows.
  • Dynamic telemetry streaming throttles.