Charon — High-Level Architecture

Authors: Vergel Esteban & Robert Evans Version: 1.0 | December 2025

1. Overview

Charon is a travel companion platform that connects passengers with drivers already commuting along the same corridor. Unlike traditional ride-hailing (which adds cars), Charon fills empty seats—reducing congestion, emissions, and commute costs.

2. System Components

2.1 Client Applications

LayerTechnologyPurpose
MobileReact Native + ExpoPassenger & Driver apps (iOS/Android)
WebReact + Vite + TypeScriptPassenger booking, Driver publishing
Employer PortalReact (shared components)Cohort management, mobility credits
Ops DashboardReact + Admin SDKMicro-stop curation, incident handling

2.2 API Layer

ComponentTechnologyPurpose
API GatewayCloudflare Workers / HonoEdge routing, rate limiting, geo-routing
REST APIHono (Workers) or Express (fallback)Core business logic endpoints
WebSocketDurable Objects / PusherReal-time trip tracking, chat

2.3 Core Services

  • Matching Engine — Corridor matching, time-band alignment, detour budget
  • Trip Service — Trip CRUD, booking flow, state machine, backup assign
  • Fare Engine — Flag-down, per-km/min, surge/peak, audit logs
  • Micro-stop Service — Curb curation, capacity mgmt, auto-switch, safety scores
  • Safety Service — SOS pipeline, KYC verify, BLE/QR verify, deviation detection
  • Payments — Hold/capture, splits, refunds, credits

2.4 Data Layer

StoreTechnologyUse Case
Primary DBPostgreSQL + PostGISRelational data, geo-queries, corridors
CacheRedis / UpstashSession, rate limits, hot data
Edge KVCloudflare KVConfig, micro-stop cache, feature flags
Blob StorageR2 / S3KYC docs, receipts, audit exports
AnalyticsClickHouse / BigQueryDashboards, ML training data

3. Data Model (Core Entities)

Passengers

  • id, name, phone, kyc_status, cohorts[]

Drivers

  • id, name, license, vehicle, route_id, seats, detour_budget

Corridors

  • id, name, cells[], time_bands, ev_ready

MicroStops

  • id, corridor, gps, capacity, safety_score, schedule

Trips

  • id, driver, corridor, stops[], depart_time, state

Bookings

  • id, trip_id, passenger_id, pickup, status, payment

Fares

  • trip_id, flag_down, per_km, per_min, fixed_fee, total

Incidents

  • id, trip_id, type, severity, outcome, resolved

4. Key Flows

4.1 Passenger Booking Flow

  • Select Corridor & Time Band
  • View Drivers & Fares
  • Get Assigned MicroStop & Slot
  • Walk to Pickup
  • Board & Confirm (BLE/QR)
  • Trip Started → Payment Captured

    • 4.2 Driver Publish & Pickup Flow

  • Publish Route & Seats
  • Receive Pickup Suggestions
  • Accept Pickup (within detour budget)
  • Arrive & Verify Passenger
  • Complete Trip & Receive Payout

    • 5. Infrastructure & Hosting

    LayerChoiceRationale
    Edge ComputeCloudflare WorkersGlobal edge, low latency, auto-scaling
    CDN/StaticCloudflare PagesWeb app, fast deploys, preview branches
    Primary DBNeon (Postgres)Serverless Postgres + PostGIS, branching
    RealtimeDurable Objects + WebSocketStateful connections at edge
    CacheUpstash RedisServerless Redis, global replication
    BlobCloudflare R2Zero-egress storage for docs/receipts
    AuthClerkManaged auth, number masking, mobile SDK
    PaymentsPayMongo / Stripe ConnectLocal + global payment rails
    MapsMapboxRouting, ETA, corridor visualization
    MonitoringSentry + AxiomError tracking, structured logs

    6. Security Architecture

    Authentication & Authorization

    • Gov't ID scan + selfie match (KYC)
    • Proxy phone numbers (number masking)
    • TLS 1.3 everywhere, encryption at rest

    Trust & Safety

    • BLE/QR "right car" handshake
    • Route deviation & dwell detection
    • Geofenced risk nudges
    • Immutable audit logs

    7. API Design

    Core Events

    • booking.created, booking.assigned
    • driver.arrived, trip.started, trip.completed
    • sos.triggered, microstop.switched

    REST Endpoints

    MethodPathDescription
    GET/corridorsList available corridors
    GET/corridors/:id/driversDrivers on a corridor
    POST/tripsPublish a driver route
    POST/bookingsPre-book a seat
    POST/bookings/:id/confirmBLE/QR handshake
    GET/microstopsList micro-stops
    POST/sosTrigger emergency

    8. Technology Decision Matrix

    DecisionChoiceRationale
    RuntimeNode + CF WorkersEcosystem maturity, edge support
    FrameworkHonoEdge-native, lightweight, typed
    DBNeon PostgresPostGIS, branching, serverless
    ORMDrizzleEdge-compatible, type-safe
    MobileReact Native (Expo)Code sharing, ecosystem
    MapsMapboxPricing, customization, offline
    AuthClerkDX, number masking, mobile SDK
    PaymentsPayMongo + StripeLocal rails + global scale

    9. Non-Functional Requirements

    AttributeTargetApproach
    Latencyp95 < 200msEdge compute, regional DBs
    Availability99.9%Multi-region, graceful degradation
    Scalability100k concurrentServerless, auto-scaling
    SecuritySOC 2 readyEncryption, audit logs, KYC

    10. Roadmap

    PhaseFocusDuration
    MVPCorridors, matching, booking, micro-stopsWeeks 1-4
    SafetySOS, BLE/QR, deviation alerts, backup routingWeeks 5-8
    ScalePayments, cohorts, dashboards, EV corridorsWeeks 9-12
    GlobalMulti-region, localization, complianceMonths 4-6
    Last updated: December 29, 2025