Go Happy Cab
Driver Dashboard
Mobile-first Expo Router app for special needs children transportation drivers in Marin County, CA.
Stage: Late development, approaching field testing. Core driver workflows are functional with real data from Convex. Authentication, daily route management, monthly calendar, localization (EN/ES/PT-BR), and push notification infrastructure are in place. No production drivers yet — next step is TestFlight distribution and real-world validation.
Shared backend: Same Convex deployment (colorful-wildcat-524) as the Dispatch web app. Changes made by dispatchers appear in real-time on driver devices.
Key Dependencies
Architecture Snapshot
Recent Activity
28 commits over the past 3 months. Only 1 commit in the 2-week window (Mar 4). Most activity was Jan–Feb.
getDriverDateRange Convex query.Decision Log
Clerk for auth, not custom PIN
Original design used a PIN+biometric flow. Switched to Clerk (email/phone + password) for production-grade session management, password hashing, and account administration. ClerkId links to the Convex drivers table. Decision made Oct 2025, validated across all screens by Nov 2025.
Shared Convex deployment with Dispatch app
Both apps share colorful-wildcat-524.convex.cloud. This ensures dispatch schedule changes appear instantly on driver devices via Convex real-time subscriptions. Single schema (668 lines) covers both apps with clear section markers. Trade-off: tight coupling, but acceptable for a single-company product.
One route per child (not per stop)
The routes table has a 1:1 child-to-route relationship for dispatch simplicity. Stops table exists for detailed route execution but dispatch operates at the route level. This was a dispatch simplification that the driver app inherited.
Convex generated files checked into git
EAS builds don't run convex codegen, so generated types (convex/_generated/) are committed. Two commits addressed this: first adding to .gitignore, then reverting. Final decision: keep in git for build reliability.
Three-language localization from day one
EN, ES, PT-BR supported via i18next. Driver demographic in Marin County includes Spanish and Portuguese speakers. Every UI string goes through the translation pipeline — no hardcoded English.
State of Things
Working
- Clerk authentication (email + phone)
- Daily route display with carpool grouping
- Monthly calendar with AM/PM badges
- Status actions (Pickup, No-Show, Pre-Cancel, Late Cancel, N/A)
- 30-minute undo timer on actions
- Map navigation to pickup/dropoff
- Localization (EN / ES / PT-BR)
- Push notification token registration
In Progress
- Untracked
data/directory with driver-accounts.csv (possible import prep)
Blocked / Waiting
- TestFlight distribution — needs EAS build + Apple review
- Push notification triggers — dispatch actions need to fire notifications
- Production data population — drivers need Clerk accounts linked to Convex records
Known Issues
- Undo/reset status mutation missing — routes/index.tsx:234 has TODO for backend mutation to reset status to 'assigned'
Mental Model Essentials
Auth gates everything
Every query is scoped by the authenticated driver's clerkId. No driver sees another driver's data. The root layout wraps everything in ClerkProvider → ConvexProviderWithClerk.
Routes = one child per row
Each route record is one child + one driver + one date + one period (AM/PM). Carpool groups are built client-side by grouping routes with the same driver+date+period.
Shared schema, two apps
The 668-line Convex schema serves both Dispatch (web) and Driver (mobile). Tables have clear section comments. dispatchEvents and scheduleTemplates are dispatch-only additions.
View-only for past dates
When browsing historical dates via DateNavigationHeader, isViewOnly=true is passed to EnhancedRouteCard and CarpoolGroup, disabling status action buttons.
File-based routing with tabs
app/(tabs)/ contains routes, messages, directory, profile. Auth screens are at app/auth/. Modals at app/modals/. Badge screen at app/badge.tsx.
Hooks are the data layer
12 custom hooks abstract all Convex queries. Components consume hooks, not raw Convex API calls. useDriverRoutes, useDriverCalendar, useDriverActions are the core three.
EAS builds need generated files
convex/_generated/ is checked into git because EAS build doesn't run codegen. If you change the schema, run convex dev locally and commit the regenerated files.
All strings go through i18n
i18n/config.ts initializes i18next. Locale files in i18n/locales/. Every user-facing string uses t() — no hardcoded English in components.
Cognitive Debt Hotspots
routes/index.tsx — 773 lines, single file
The main routes screen is the most complex file in the app. Contains daily view, calendar toggle, status actions, date navigation, and carpool grouping logic. The calendar was partially extracted (CalendarView, MonthCalendar) but the daily route list and all status-change logic remain in this single file. Splitting into smaller components would improve maintainability.
Missing undo/reset mutation
routes/index.tsx:234 — TODO: Create backend mutation to reset status to 'assigned'. The undo timer UI exists but the backend mutation to actually reset a route's status is not implemented. If a driver taps undo, it may not persist the reversal.
No test coverage
Jest and Detox are configured but the tests/ directory (from the original TDD plan) appears to have only scaffold files. The README promises TDD but no tests have been written for the current functional code. As features stabilize for launch, critical paths (auth flow, status actions, carpool grouping) should have test coverage.
Stale documentation
README.md references React Native 0.73 and Expo Router v3 — actual versions are RN 0.81 and Expo Router v6. STATUS.md was last updated Nov 2025. CHILD_INFO_MODAL.md, DIRECTORY_FEATURE.md, REAL_TIME_PICKUP_VALIDATION.md, and PUSH_NOTIFICATIONS_PLAN.md may be outdated. Consider archiving or updating to prevent confusion.
schema.ts.OLD sitting in convex/
An old schema file exists alongside the current one. Should be deleted to avoid confusion about which schema is active.
Next Steps
Inferred from recent activity, executive summary, and TODO comments. This is where momentum was pointing.