73 lines
5.2 KiB
Markdown
73 lines
5.2 KiB
Markdown
# 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.
|