Skip to content

mobile-driver — CONTEXT.md

Ionic 8 / Angular 20 driver-facing mobile app. Trip management, GPS tracking, checkpoint clearing, QR boarding, and earnings withdrawal. Deployed via Capacitor. For global conventions (branding, Angular patterns, GIS overview), see /CLAUDE.md.

1. Routes

Path Component Notes
/login LoginPage OTP login (phone number)
/home HomePage Trip list + drawer navigation
/active-trip/:id ActiveTripComponent Active trip map, GPS tracking, checkpoint alerts
/self-dispatch SelfDispatchPage Select line → route → vehicle → create trip
/profile ProfilePage Driver profile, bank accounts, earnings
/my-vehicles MyVehiclesPage Assigned vehicles
/ Redirects to /login —
** Redirects to /login —

Guard: ActiveTripGuard (canDeactivate) on /active-trip/:id — prevents accidental route leave.

2. OTP Login Flow

  1. Driver enters phone number → POST /auth/request-otp
  2. Backend saves OTP to DB; skips Twilio when TWILIO_FORCE_REAL_SEND=false
  3. Dev bypass: OTP_MASTER_KEY=000000 fires before driver status guard
  4. On verify → JWT issued with driverId in payload
  5. Token stored via TokenService (Capacitor Preferences, key syncc_access_token)

3. Active Trip GPS Flow

  1. LocationService starts background GPS tracking on trip start
  2. Position emitted via Socket.IO every 30s (heartbeat)
  3. Haversine distance calculated against each route checkpoint
  4. Checkpoint cleared when driver is within radiusMeters (default 50m)
  5. Backend confirms via ST_DWithin PostGIS query in location.service.ts
  6. Trip.actualCheckpoints (Json) updated — never remove historical entries
  7. Local notification sent to driver on checkpoint clear
  8. Trip auto-completes when all checkpoints cleared

4. Core Services

All services in src/app/core/services/, providedIn: 'root'.

Service Purpose
SocketService Socket.IO connection; emit/on events; auto-reconnect (10 attempts)
TokenService JWT read/write/clear via Capacitor Preferences
LocationService Background GPS, checkpoint proximity (Haversine), heartbeat emission
PermissionService Location, camera, notification, battery optimization requests
PaymentService Earnings withdrawal flow (OTP → verify → withdraw)
PaymentNotificationService Real-time payment_received listener; local notifications
TripsService Trip CRUD, checkpoint management, passenger QR scanning, bank account CRUD

5. Capacitor Config

  • appId: com.syncc.driver
  • appName: Syncc Conductor
  • webDir: www
  • Android scheme: https
  • BackgroundGeolocation: title "Rastreo de Viaje", text "Syncc está compartiendo tu ubicación..."
  • LocalNotifications: icon color #32737E, sound beep.wav

6. QR / Payment Feature — Restore Instructions

Trigger: "implement the QR functionality" or "activate the QR functionality".

src/app/active-trip/active-trip.component.html — Three blocks:

  1. QR / Check-in / Check-out buttons (line ~87): HTML comment block — delete <!-- NOT LAUNCHING YET: ... and END NOT LAUNCHING YET --> lines. Restores "Mi QR" and "Escanear" action buttons in the trip control row.

  2. Trip QR overlay (line ~116): *ngIf="false" → *ngIf="tripQrVisible" Full-screen modal showing trip QR code with line name, vehicle plate, boarding count.

  3. Passenger QR scanner overlay (line ~166): *ngIf="false" → *ngIf="scannerVisible" Full-screen scanner with Abordaje/Salida mode toggle and state machine (scanning → success → duplicate → error).

src/app/profile/profile.page.html — Four blocks:

  1. Balance card + withdrawal (line ~103): HTML comment block — delete wrapper lines. Shows "Mi Saldo" with Bs. amount and "Retirar saldo" button.

  2. Cuentas tab button (line ~135): HTML comment block — delete wrapper lines. Adds "Cuentas" tab to the tab bar.

  3. Cuentas tab content (line ~201): *ngIf="false" → *ngIf="!loading && driver && activeTab === 'cuentas'" Bank accounts management: list, add, set default, delete.

  4. Withdrawal bottom sheet (line ~620): *ngIf="false" → *ngIf="withdrawOpen" Multi-step withdrawal: amount → requesting → OTP → verifying → success/error.

After restoring

npx ionic build && npx cap sync

No backend changes needed — all API endpoints are already live.

7. Dev Workflow

cd apps/mobile-driver
npm install
npm start                  # Dev server at http://localhost:8100
npm run build:prod         # Production build
npx cap sync               # Sync Capacitor native projects
npx cap run android        # Run on Android
npx cap run ios            # Run on iOS

8. Key File Paths

What Path
Routes src/app/app.routes.ts
Active trip src/app/active-trip/
Login page src/app/login/
Home page src/app/home/
Profile page src/app/profile/
Self-dispatch src/app/self-dispatch/
Services src/app/core/services/
Capacitor config capacitor.config.ts
Tailwind config tailwind.config.js

Last updated: 2026-06-05.