RideBeacon™ — Master Product Specification

Version: 1.0 · Pilot Alpha Last updated: July 6, 2026 Owner: Product / Engineering Status: Single source of truth. If code and this document disagree, this document is the intent — reconcile the code.

Trademark note: RideBeacon™, RideBeacon Academy™, Bronze Rider™, Silver Rider™, Gold Rider™, Certified Safe Rider™, and Certified Community Rider™ use ™ (never ®).

Table of Contents

1. Product Framing 2. Customer Journey (13 Milestones) 3. Parent Experience 4. Child Experience 5. Bicycle Journey 6. Mechanic Journey 7. Shipping Journey 8. Customer Communications Matrix 9. Admin Experience 10. Current Development Status 11. Remaining Roadmap 12. Appendices

1. Product Framing

1.1 What RideBeacon is

RideBeacon is a Rider Development Platform built on three equal pillars:

1. Registration — every bicycle becomes a permanent, traceable, transferrable record. 2. RideBeacon Academy™ — a 5-tier rider development curriculum (Bronze → Silver → Gold → Certified Safe Rider → Certified Community Rider). 3. Ride Monitoring — safety scoring, violations, interventions, and (optionally) GPS.

Freedom → Responsibility → Awareness → Community → Better Decisions. Coaching, not punishment.

1.2 What RideBeacon is NOT

• It is not a GPS tracker. GPS enhances RideBeacon; it does not define it. The product must remain valuable without GPS.
• It is not a punishment system. Language is Responsibility, Awareness, Improvement, Coaching.
• It is not a demo-first company. The presentation environment is a sales tool; production is where the value lives.

1.3 The bicycle is the permanent record

RideBeacon ID, manufacturer, model, serial number, and ownership history persist forever. The owner, parent, rider, GPS device, and even the school can change over time. The badge follows the bicycle, not the rider.

1.4 The 30-second dashboard rule

Every dashboard answers two questions in under 30 seconds:

• What do I need to know?
• What should I do next?

Overview pages are launch pads, not destinations.

2. Customer Journey (13 Milestones)

This is the canonical spine. Every email, SMS, dashboard change, and admin alert must resolve to one of these step IDs. Source of truth: src/lib/journey/milestones.ts and src/lib/onboarding-journey.functions.ts.

Each row lists: Trigger (what fires the transition), Customer sees (parent-facing surface), System does (server side effects).

Step 1 — purchase

• Trigger: Cart → /checkout submitted successfully.
• Customer sees: Redirect to /welcome-setup. Order confirmation email in inbox within seconds.
• System does:
• onboarding_drafts row created.
• profiles.created_at timestamp.
• recordJourneyTransition('purchase', 'complete') writes to journey_events.
• Email: Order Confirmation (order-confirmation template).
• Dashboard: n/a (parent not yet in dashboard).

Step 2 — account_created

• Trigger: supabase.auth.signUp completes inside welcome-setup.
• Customer sees: Silent — the wizard advances to family details.
• System does:
• profiles.user_id row inserted via handle_new_user trigger.
• Default user_roles row: parent.
• journey_events transition logged.

Step 3 — family_ready

• Trigger: Parent submits full name + phone (E.164) + SMS opt-in inside welcome-setup.
• Customer sees: Wizard advances. Welcome email lands in inbox.
• System does:
• profiles.notify_phone_e164 populated.
• Email: Welcome to RideBeacon (welcome-to-journey).
• No SMS at this step (SMS starts at Academy invitation).

Step 4 — rider_added

• Trigger: First riders row created inside runOnboardingForUser.
• Customer sees: Wizard shows the child card populated.
• System does: riders row with parent_user_id. Silent to parent.

Step 5 — bike_registered

• Trigger: First bikes insert. claim_next_ridebeacon_id() claims a permanent RB ID.
• Customer sees: Wizard shows bike card + RideBeacon ID.
• System does:
• bikes.ridebeacon_id populated.
• bike_timeline_events row: registered.
• entity_status_events: bike / registered.

Step 6 — tier_assigned

• Trigger: bikes.monitoring_tier set at insert (premium_gps | basic_location | none).
• Customer sees: Silent — tier is visible on the dashboard in the next step.
• System does: Determines whether a Plus work order will be created (premium_gps only).

Step 7 — dashboard_ready

• Trigger: Parent lands on /parent, welcome overlay renders.
• Customer sees: Full parent dashboard, welcome overlay, Journey card showing Steps 1–7 complete.
• System does: In-app welcome overlay via use-welcome-gate. Steps 3–6 must be satisfied.

Step 8 — academy_invited

• Trigger: runOnboardingForUser step 5 fires Academy kickoff for each new rider.
• Customer sees:
• Email: Bronze Rider™ lesson is ready.
• SMS: Passwordless magic link to /l/lesson/:riderId.
• Dashboard Journey card shows "Your child's first lesson is ready."
• System does:
• messaging_log.message_type = 'academy_kickoff' with dedupe_key = 'academy_kickoff:<rider_id>'.
• comm_events row tagged with journey_step_id = 'academy_invited'.
• Academy access token minted with ACADEMY_LINK_SECRET.

Step 9 — mechanic_scheduled

• Trigger: installation_work_orders.status = 'appointment_scheduled' OR scheduled_at set.
• Customer sees:
• Email: Inspection scheduled with date/time.
• SMS: Appointment reminder.
• Dashboard: "Safety inspection scheduled for {date}."
• System does:
• Internal alert to mechanic dashboard (new_appointment).
• work_order_status_events row.

Step 10 — kit_shipped

• Trigger: installation_work_orders.tracking_number + shipped_at populated. tr_wo_shipping_state flips status to shipped.
• Customer sees:
• Email: Kit shipped, tracking link.
• SMS: Delivery-day SMS.
• Dashboard: "Your RideBeacon kit is on the way."
• System does: Trigger-driven status transition; downstream flip to mechanic_ready_to_schedule when expected_delivery_at lands.

Step 11 — installation_complete

• Trigger: Work order reaches installation_complete (or ridebeacon_installed).
• Customer sees: Dashboard "Installation complete." (SMS/email per rules engine — currently silent by default at this step.)
• System does:
• bike_timeline_events: plus_installed for Plus WOs.
• sync_service_request_from_wo moves the related service_requests to in_progress.

Step 12 — bike_certified

• Trigger: Safety check overall_status = 'ridebeacon_certified' OR WO reaches ridebeacon_certified.
• Customer sees: Dashboard "Your bicycle is Certified Safe."
• System does:
• bike_timeline_events: certified.
• safety_checks.completed_at sets bikes.last_inspection_at via sync_bike_last_inspection.

Step 13 — first_ride

• Trigger: First rides row OR first gps_events arrival/departure.
• Customer sees:
• Email: First-ride recap.
• Dashboard: "You're riding with RideBeacon."
• System does: Closes the onboarding arc. All subsequent lifecycle events (services, maintenance, transfers, theft reports, certifications) attach to the permanent bike record.

3. Parent Experience

3.1 Purchase → Welcome

• Purchase completes on /checkout.
• Redirect to /welcome-setup (resume token in URL — survives tab close).
• Wizard steps: family details → child(ren) → bike(s) → dashboard handoff.
• Atomic bootstrap: runOnboardingForUser creates rider + bike + Plus WO (if applicable) + fires Academy kickoff in a single server-fn call.

3.2 Family Setup

• Full name, notification phone (E.164), SMS opt-in.
• Populates profiles; unblocks steps 3–7.

3.3 Child Registration

• First name, birth year (drives Academy age gating).
• Optional: school (from list_schools_public_picker).
• Optional: school_identification_opt_in (controls whether school staff can see the child's device/badge on their premises).

3.4 Bike Registration

• Manufacturer, model, serial, vehicle type/class, max speed band.
• Permanent RideBeacon ID claimed from ridebeacon_inventory.
• Monitoring tier picked at insert; drives Plus WO creation.

3.5 Parent Dashboard (/parent)

The dashboard answers "What do I need to know? What should I do next?"

• Journey card — live 13-step timeline. Active step shows reassurance line if requiresParentAction === false, single CTA if true.
• Rider cards — Academy progress, safety score, certification tier.
• Bike cards — RB ID, monitoring tier, last inspection, last service.
• Alerts — sourced from notifications, internal_alerts, comm_events.
• What's next — top action for the next incomplete milestone.

3.6 GPS (Plus tier only)

• Live location for opted-in bikes.
• Zone rules (school, home) drive zone_events and parent notifications.
• GPS is presented as awareness not tracking.

3.7 Mechanic Interaction

• Parent sees mechanic assignment, appointment date, inspection results, and service history — never mechanic contact info until an appointment is confirmed.
• mechanic_reviews after service.

3.8 Ongoing Ownership

• Maintenance reminders (maintenance_reminders).
• Annual re-certification (planned).
• Bike transfer (bike_transfers) — the record moves; the child/parent/GPS device can change.
• Theft report (theft_reports) — public "found" listings, bike_lookup_requests from third parties.

4. Child Experience

4.1 Passwordless Academy Access

• Child receives an SMS/email link (magic link, HMAC-signed with ACADEMY_LINK_SECRET) that lands at /l/lesson/:riderId.
• No account required. Token expires; single-use for state-changing actions.
• Works on a phone or tablet with zero friction.

4.2 Bronze Rider™ Lesson Flow

1. Land on lesson intro (video + narrator lead-in). 2. Complete module content (video, key points, safety scenarios). 3. Take module quiz. Pass threshold: 80%. 4. Score written to academy_attempts.module_quiz_scores (jsonb map of module_code → percent). 5. Trigger tr_academy_try_award_bronze calls award_bronze_if_ready — awards Bronze once all required modules pass. 6. Celebration toast + optional celebration SMS to parent.

4.3 Bronze Rider™ Certification

• On award: rider_certification_history insert with tier_code = 'bronze', is_current = true.
• rider_lesson_events: certification_awarded.
• Pending Plus WOs advance from bronze_pending → ready_to_ship.

4.4 Silver Rider™ (planned)

• Traffic patterns, intersections, real-road scenarios.
• Available after Bronze; age-gated by academy_courses.min_age.
• Same passwordless flow.

4.5 Gold Rider™ (planned)

• Advanced e-bike handling, higher speed bands.
• Requires vehicle_class and max_speed_band eligibility (assigned_courses_for_rider).

4.6 Certified Safe Rider™ / Certified Community Rider™ (future)

• Composite certifications combining Academy tiers, safety score, intervention history, and community contributions.

4.7 Progress Tracking

• academy_attempts (per-course), rider_lesson_events (timeline), rider_achievements (badges), safety_scores (behavior-derived).
• safe_rider_level(rider_id) returns the current tier badge for display.

5. Bicycle Journey

The bicycle is the permanent record. Every event below writes to bike_timeline_events — the "Complete Bicycle Record" that follows the bike for its entire life.

5.1 Registration

• claim_next_ridebeacon_id() mints a permanent RB ID.
• bikes row created with parent, rider, tier, verification level.
• entity_status_events: bike / registered.
• Timeline: registered event.

5.2 RideBeacon Registered (baseline)

• Minimum tier. RB ID + badge shipped; no GPS, no inspection.
• Public registry entry (searchable by RB ID or serial for theft recovery).

5.3 RideBeacon Certified

• Certified via safety check (safety_checks.overall_status = 'ridebeacon_certified').
• Sets bikes.last_inspection_at.
• Timeline: safety_check + certified.

5.4 RideBeacon Plus

• Premium tier: includes professional installation, initial Safety Check, GPS device, subscription.
• Creates installation_work_orders at bike registration.
• Timeline: plus_installed.

5.5 GPS Activation

• Mechanic scans/pairs GPS device → gps_devices row → bikes.gps_device_id.
• Work order status flips through gps_activated.
• Timeline: gps_activated.
• First ping arrival flips gps_devices.activation_status = 'active'.

5.6 Certified Inspection

• Structured checklist (bike_inspection_items) + photo evidence (bike_inspection_photos).
• Stored in bike_inspections with items, notes, and overall status.
• Available to all future owners of the bike.

5.7 Maintenance & Service

• Every service writes to bike_service_records (category, parts, cost, mechanic).
• sync_bike_last_service updates bikes.last_service_at.
• Timeline: service event per record.
• maintenance_reminders for upcoming needs.

5.8 Ownership Transfer

• bike_transfers records the handoff. bike_ownership_history retains the full lineage.
• New owner inherits the timeline; identifying rider details are scoped per owner.

5.9 Theft & Recovery

• theft_reports public listing.
• bike_lookup_requests for third-party scans.
• Recovery workflow uses RB ID as the anchor.

5.10 The Complete Bicycle Record

Any authenticated owner (current or past, with scope) can see: registration date, every service, every inspection, every certification, every transfer, every theft/recovery event, and the current safety status.

6. Mechanic Journey

6.1 Assignment

• Admin (or auto-assignment) assigns a mechanic to a work order (mechanic_assignments, installation_work_orders.assigned_mechanic_id).
• Status transitions to mechanic_assigned.
• Internal alert: mechanic dashboard.

6.2 Scheduling

• Mechanic contacts parent → parent_contacted.
• Appointment scheduled → appointment_scheduled (fires Step 9 mechanic_scheduled).
• mechanic_appointments row.

6.3 Inspection

• Mechanic performs full checklist via bike_inspections + bike_inspection_items + bike_inspection_photos.
• safety_checks row records overall status.
• Status: safety_check_complete.

6.4 Installation (Plus)

• Mechanic mounts badge/GPS device.
• Status: installation_started → ridebeacon_installed.
• Timeline: plus_installed.

6.5 GPS Activation

• Mechanic pairs device serial to the bike.
• First ping confirms activation.
• Status: gps_activated.

6.6 Certification

• Overall status set to ridebeacon_certified.
• Status: ridebeacon_certified → review_complete → installation_complete.
• Fires Step 12 bike_certified.

6.7 Ongoing Maintenance

• Preferred mechanic relationship (preferred_mechanics).
• Future service requests route to the preferred mechanic first.
• bike_service_records accumulate as the permanent service history.

6.8 Future Inspections

• Annual re-certification (planned).
• Triggered by maintenance_reminders or subscription anniversary.

7. Shipping Journey

Work order statuses in installation_work_orders:

Every transition writes to work_order_status_events and (where applicable) bike_timeline_events.

8. Customer Communications Matrix

Every send must resolve to a Journey step ID. Templates live in src/lib/email-templates/. SMS templates in src/lib/messaging/. Journey step tagged on messaging_log.journey_step_id and comm_events.journey_step_id.

Also live: celebration SMS on Bronze certification (celebration-sms.functions.ts), lesson-2 reminder cron (queue_lesson2_reminders), inbound SMS routing (ingest_inbound_sms), suppression handling (suppressed_emails).

Idempotency: every send uses a per-step dedupe_key. Replaying a step never double-sends.

9. Admin Experience

Admin routes live under src/routes/_authenticated.admin.*.

9.1 Parent Management

• /admin/pilot-ops/families — list all parent accounts, filter by pilot/test, drill into /admin/pilot-ops/families/:userId.
• /admin/accounts/:userId — full account inspector.
• /admin/pilot-accounts — pilot cohort management.

9.2 School Management

• /admin/pilot-ops/schools — schools directory (list_schools_directory), edit contact info, geofences, parking hours.
• /admin/school-test-center — school-side test harness.

9.3 Mechanic Management

• /admin/mechanic-ops — mechanic roster, assignments, availability.
• /admin/service-ops and /admin/service-requests — work order dispatch.
• /admin/fulfillment — shipping queue.

9.4 Communication History

• /admin/pilot-ops/messaging — full messaging log with dedupe keys, statuses, responses.
• /admin/pilot-ops/sms — SMS-specific view.
• /admin/pilot-ops/inbox — inbound SMS threads (sms_inbox_threads).

9.5 Journey Timeline (per family)

• /admin/pilot-ops/onboarding-journey — 13-step checklist per parent, with the timestamp each step landed. This is the tool used to verify Kevin's and Vanessa's families end-to-end.

9.6 Academy Management

• /admin/academy-producer — content authoring/preview.
• /admin/pilot-ops/academy — attempts, scores, module completion.

9.7 GPS Management

• /admin/gps-devices — inventory, activation, bike pairing.
• /admin/gps-live — live ping viewer.
• /admin/gps-test, /admin/gps-walkthrough — QA tooling.
• /admin/ble-calibration — BLE gateway calibration.

9.8 Cross-cutting

• /admin/pilot-ops/alerts — notifications and internal alerts.
• /admin/pilot-ops/beacons — beacon inventory (ble_beacons).
• /admin/pilot-ops/service — service ops overview.
• /admin/network-health — subsystem readiness board (subsystem_readiness).
• /admin/pilot-ops/learning-log — pilot learning log entries.

10. Current Development Status

Legend: ✅ Complete · 🚧 In Progress · ⏳ Planned · ❌ Not Started

10.1 Journey Infrastructure

10.2 Parent Experience

10.3 Child / Academy

10.4 Bicycle

10.5 Mechanic

10.6 GPS

10.7 Communications

10.8 Admin

10.9 School (deferred until Phase 5)

• School admin dashboard, roster, badge scanning, parking compliance, geofence config — all scaffolded, deferred until parent Journey is validated end-to-end.

11. Remaining Roadmap

Phase 2 — First Customer Experience Complete (CURRENT)

Goal: A parent purchases RideBeacon and everything just happens. Validated with Kevin's, Vanessa's, and Tessa's families.

1. Wire the six missing Journey triggers through recordJourneyTransition (checkout, family_ready, rider_added, bike_registered, mechanic_scheduled, kit_shipped, installation_complete, bike_certified, first_ride). 2. Build the two missing email templates (order-confirmation, welcome-to-journey) and connect the other four (academy-lesson-ready, inspection-scheduled, kit-shipped, first-ride-recap). 3. Confirm passwordless Academy link opens without login. 4. Build Admin Replay Journey for account_kind = 'test' accounts — wipe app-level data, keep the auth user, replay the full flow. 5. Mark Vanessa and Tessa as account_kind = 'test'. Run each account through the full flow end-to-end and validate every trigger, every email, every SMS, every dashboard change lands.

Exit criteria: Both test families complete Steps 1–8 without manual intervention; steps 9–13 simulated via admin controls.

Phase 3 — GPS Integration

• Finalize hardware selection (Traccar-compatible).
• Complete Flespi webhook + Traccar pipeline.
• Parent live view.
• Zone events tie back into Journey (first_ride).

Phase 4 — Mechanic Workflow

• Full mechanic dashboard.
• GPS pairing UI.
• Return-service scheduling.
• Payment/invoice surfaces (work_order_invoices).

Phase 5 — Pilot Launch (Corona del Mar)

• Onboard first real families (10–20 households).
• 30-day observation window with weekly Journey audits.
• Iterate on communication cadence, dashboard clarity, Academy engagement.

Phase 6 — School Pilot

• Enable school admin surfaces.
• Roster import, badge scanning, parking compliance.
• School accountability reporting.

Phase 7 — Public Release

• Marketing site conversion optimization (already in polish mode).
• Silver Rider™ course launch.
• Bike transfer / theft recovery public flows.
• Annual re-certification cadence.

12. Appendices

A. Key Files

B. Key Database Objects

• Tables: journey_events, messaging_log, comm_events, notifications, bikes, riders, profiles, installation_work_orders, bike_timeline_events, work_order_status_events, entity_status_events, academy_attempts, rider_certification_history, safety_checks, gps_devices, mechanic_assignments.
• Functions: record_entity_status, award_bronze_if_ready, claim_next_ridebeacon_id, has_role, is_test_account, ingest_inbound_sms, queue_lesson2_reminders.
• Triggers: tl_bike_registered, tl_safety_check_completed, tl_service_record, tl_work_order_status, tr_wo_shipping_state, tr_academy_try_award_bronze, sync_service_request_from_wo.

C. Language Standards

• ™ (never ®) on all marks; do not double-append.
• Prefer: Responsibility, Awareness, Community, Improvement, Education, Coaching, Progress.
• Avoid overusing: Violations, Infractions, Punishment, Discipline.
• Never call app emails "transactional emails" to a customer.
• Never call the backend "Supabase" to a customer — say "backend" / "database".

D. Change Control

Any change to the 13-step Journey requires simultaneous updates to: 1. This document. 2. docs/journeys/parent-onboarding.md. 3. src/lib/journey/milestones.ts. 4. src/lib/onboarding-journey.functions.ts. 5. /admin/pilot-ops/onboarding-journey display. 6. Any comm templates citing the moved step.

Do not change one without the others.

End of specification. Review, annotate, and return with edits before Phase 2 wiring resumes.