# souma061/instaride architecture

> Architecture diagram of the GitHub repository souma061/instaride, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/souma061/instaride
- Repository: https://github.com/souma061/instaride

## Overview

InstaRide is a real-time ride-matching platform with a React operations dashboard, a TypeScript service, and optional native C++ spatial acceleration. The main flow is driver location ingestion and indexing, rider request and nearest-driver search, leased driver locking and offer dispatch, then trip-state updates and completion. Redis-backed lock and trip persistence support that lifecycle; WebSockets carry live events to rider, driver, and observer clients. The README documents the dual spatial engines and dashboard capabilities; several backend and UI relationships below rely on its architecture description and the SOURCE INDEX, since those implementations were not fully excerpted.

Main entry points: [`src/core/matching_service.ts`](https://github.com/souma061/instaride/blob/main/src/core/matching_service.ts) (Candidate dispatch), [`frontend/src/App.tsx`](https://github.com/souma061/instaride/blob/main/frontend/src/App.tsx) (Dashboard shell), [`src/server.ts`](https://github.com/souma061/instaride/blob/main/src/server.ts) (REST API), [`src/core/driver_registry.ts`](https://github.com/souma061/instaride/blob/main/src/core/driver_registry.ts) (Driver registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Rider and operations UI"]
  node_app["Dashboard shell<br/>[App.tsx]"]
  node_rider_ui["Rider cockpit<br/>[RiderCockpit.tsx]"]
  node_driver_ui["Driver cockpit<br/>[DriverCockpit.tsx]"]
  node_map["Spatial map"]
  node_ops_ui["Operations dashboard"]
  node_chaos_ui["Chaos testing panel"]
  node_audit_ui["Audit stream<br/>[AuditLogStream.tsx]"]
  node_metrics_ui["Header metrics<br/>[HeaderMetrics.tsx]"]
  node_socket_hook["Socket client"]
end

subgraph group_api["Gateway and live events"]
  node_http["REST API<br/>[server.ts]"]
  node_ws["WebSocket manager<br/>[ws_manager.ts]"]
  node_sim["Driver simulation"]
end

subgraph group_matching["Matching and trip lifecycle"]
  node_matching_service["Candidate dispatch"]
  node_registry["Driver registry<br/>[driver_registry.ts]"]
  node_fsm["Trip state machine"]
end

subgraph group_spatial["Spatial engines"]
  node_spatial_ts["TypeScript QuadTree<br/>[quadtree.ts]"]
  node_cpp_bridge["C++ IPC bridge"]
  node_cpp_engine["Native QuadTree<br/>[Quadtree.hpp]"]
end

subgraph group_state["State and telemetry"]
  node_driver_lock["Driver lock leases"]
  node_trip_store["Trip persistence"]
  node_redis[("Redis client<br/>[redis_client.ts]")]
  node_metrics["Service metrics<br/>[metrics.ts]"]
  node_validation["Input validation<br/>[validation.ts]"]
end

node_rider(("Rider"))
node_driver(("Driver"))
node_operator(("Operator"))

node_rider -->|"books rides"| node_rider_ui
node_driver -->|"sends updates"| node_driver_ui
node_operator -->|"monitors service"| node_ops_ui
node_app -->|"renders"| node_rider_ui
node_app -->|"renders"| node_driver_ui
node_app -->|"renders"| node_map
node_app -->|"renders"| node_ops_ui
node_app -->|"renders"| node_chaos_ui
node_app -->|"renders"| node_audit_ui
node_app -->|"renders"| node_metrics_ui
node_rider_ui -.->|"uses live events"| node_socket_hook
node_driver_ui -.->|"uses live events"| node_socket_hook
node_map -.->|"uses telemetry"| node_socket_hook
node_socket_hook -->|"exchanges events"| node_ws
node_rider -->|"submits requests"| node_http
node_driver -->|"posts trip actions"| node_http
node_chaos_ui -->|"runs scenarios"| node_http
node_http -.->|"routes requests"| node_matching_service
node_http -->|"broadcasts updates"| node_ws
node_http -.->|"queries simulation"| node_sim
node_http -->|"selects engine"| node_cpp_bridge
node_ws -->|"dispatches actions"| node_matching_service
node_ws -->|"updates driver status"| node_registry
node_ws -->|"reads active trip"| node_fsm
node_matching_service -->|"searches candidates"| node_spatial_ts
node_matching_service -->|"locks candidates"| node_registry
node_matching_service -->|"creates and updates trips"| node_fsm
node_matching_service -->|"persists trip state"| node_trip_store
node_registry -->|"indexes drivers"| node_spatial_ts
node_registry -->|"acquires leases"| node_driver_lock
node_registry -->|"records metrics"| node_metrics
node_sim -->|"updates locations"| node_registry
node_sim -->|"exercises matching"| node_matching_service
node_sim -->|"exercises trip flow"| node_fsm
node_sim -->|"uses spatial index"| node_spatial_ts
node_driver_lock -->|"stores leases"| node_redis
node_trip_store -->|"stores trips"| node_redis
node_trip_store -->|"uses trip model"| node_fsm
node_fsm -->|"validates coordinates"| node_validation
node_cpp_bridge -->|"uses native engine"| node_cpp_engine
node_matching_service -.->|"optional spatial search"| node_cpp_bridge

click node_app "https://github.com/souma061/instaride/blob/main/frontend/src/App.tsx"
click node_rider_ui "https://github.com/souma061/instaride/blob/main/frontend/src/components/RiderCockpit.tsx"
click node_driver_ui "https://github.com/souma061/instaride/blob/main/frontend/src/components/DriverCockpit.tsx"
click node_map "https://github.com/souma061/instaride/blob/main/frontend/src/components/DynamicSpatialMap.tsx"
click node_ops_ui "https://github.com/souma061/instaride/blob/main/frontend/src/components/OperationsDashboard.tsx"
click node_chaos_ui "https://github.com/souma061/instaride/blob/main/frontend/src/components/ChaosTestingPanel.tsx"
click node_audit_ui "https://github.com/souma061/instaride/blob/main/frontend/src/components/AuditLogStream.tsx"
click node_metrics_ui "https://github.com/souma061/instaride/blob/main/frontend/src/components/HeaderMetrics.tsx"
click node_socket_hook "https://github.com/souma061/instaride/blob/main/frontend/src/hooks/useInstaRideSocket.ts"
click node_http "https://github.com/souma061/instaride/blob/main/src/server.ts"
click node_ws "https://github.com/souma061/instaride/blob/main/src/gateway/ws_manager.ts"
click node_sim "https://github.com/souma061/instaride/blob/main/src/simulation/driver_simulator.ts"
click node_matching_service "https://github.com/souma061/instaride/blob/main/src/core/matching_service.ts"
click node_registry "https://github.com/souma061/instaride/blob/main/src/core/driver_registry.ts"
click node_fsm "https://github.com/souma061/instaride/blob/main/src/core/trip_state_machine.ts"
click node_spatial_ts "https://github.com/souma061/instaride/blob/main/src/spatial/quadtree.ts"
click node_cpp_bridge "https://github.com/souma061/instaride/blob/main/src/spatial/cpp_spatial_bridge.ts"
click node_cpp_engine "https://github.com/souma061/instaride/blob/main/cpp-engine/Quadtree.hpp"
click node_driver_lock "https://github.com/souma061/instaride/blob/main/src/core/redis_driver_lock.ts"
click node_trip_store "https://github.com/souma061/instaride/blob/main/src/core/redis_trip_store.ts"
click node_redis "https://github.com/souma061/instaride/blob/main/src/infra/redis_client.ts"
click node_metrics "https://github.com/souma061/instaride/blob/main/src/metrics/metrics.ts"
click node_validation "https://github.com/souma061/instaride/blob/main/src/utils/validation.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_rider_ui,node_driver_ui,node_map,node_ops_ui,node_chaos_ui,node_audit_ui,node_metrics_ui,node_socket_hook toneBlue
class node_http,node_ws,node_sim toneAmber
class node_matching_service,node_registry,node_fsm toneMint
class node_spatial_ts,node_cpp_bridge,node_cpp_engine toneRose
class node_driver_lock,node_trip_store,node_redis,node_metrics,node_validation,node_rider,node_driver,node_operator toneIndigo
```

## Components

### Rider and operations UI

- [Dashboard shell](https://github.com/souma061/instaride/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Rider cockpit](https://github.com/souma061/instaride/blob/main/frontend/src/components/RiderCockpit.tsx): `frontend/src/components/RiderCockpit.tsx`
- [Driver cockpit](https://github.com/souma061/instaride/blob/main/frontend/src/components/DriverCockpit.tsx): `frontend/src/components/DriverCockpit.tsx`
- [Spatial map](https://github.com/souma061/instaride/blob/main/frontend/src/components/DynamicSpatialMap.tsx): `frontend/src/components/DynamicSpatialMap.tsx`
- [Operations dashboard](https://github.com/souma061/instaride/blob/main/frontend/src/components/OperationsDashboard.tsx): `frontend/src/components/OperationsDashboard.tsx`
- [Chaos testing panel](https://github.com/souma061/instaride/blob/main/frontend/src/components/ChaosTestingPanel.tsx): `frontend/src/components/ChaosTestingPanel.tsx`
- [Audit stream](https://github.com/souma061/instaride/blob/main/frontend/src/components/AuditLogStream.tsx): `frontend/src/components/AuditLogStream.tsx`
- [Header metrics](https://github.com/souma061/instaride/blob/main/frontend/src/components/HeaderMetrics.tsx): `frontend/src/components/HeaderMetrics.tsx`
- [Socket client](https://github.com/souma061/instaride/blob/main/frontend/src/hooks/useInstaRideSocket.ts): `frontend/src/hooks/useInstaRideSocket.ts`

### Gateway and live events

- [REST API](https://github.com/souma061/instaride/blob/main/src/server.ts): `src/server.ts`
- [WebSocket manager](https://github.com/souma061/instaride/blob/main/src/gateway/ws_manager.ts): `src/gateway/ws_manager.ts`
- [Driver simulation](https://github.com/souma061/instaride/blob/main/src/simulation/driver_simulator.ts): `src/simulation/driver_simulator.ts`

### Matching and trip lifecycle

- [Candidate dispatch](https://github.com/souma061/instaride/blob/main/src/core/matching_service.ts): `src/core/matching_service.ts`
- [Driver registry](https://github.com/souma061/instaride/blob/main/src/core/driver_registry.ts): `src/core/driver_registry.ts`
- [Trip state machine](https://github.com/souma061/instaride/blob/main/src/core/trip_state_machine.ts): `src/core/trip_state_machine.ts`

### Spatial engines

- [TypeScript QuadTree](https://github.com/souma061/instaride/blob/main/src/spatial/quadtree.ts): `src/spatial/quadtree.ts`
- [C++ IPC bridge](https://github.com/souma061/instaride/blob/main/src/spatial/cpp_spatial_bridge.ts): `src/spatial/cpp_spatial_bridge.ts`
- [Native QuadTree](https://github.com/souma061/instaride/blob/main/cpp-engine/Quadtree.hpp): `cpp-engine/Quadtree.hpp`

### State and telemetry

- [Driver lock leases](https://github.com/souma061/instaride/blob/main/src/core/redis_driver_lock.ts): `src/core/redis_driver_lock.ts`
- [Trip persistence](https://github.com/souma061/instaride/blob/main/src/core/redis_trip_store.ts): `src/core/redis_trip_store.ts`
- [Redis client](https://github.com/souma061/instaride/blob/main/src/infra/redis_client.ts): `src/infra/redis_client.ts`
- [Service metrics](https://github.com/souma061/instaride/blob/main/src/metrics/metrics.ts): `src/metrics/metrics.ts`
- [Input validation](https://github.com/souma061/instaride/blob/main/src/utils/validation.ts): `src/utils/validation.ts`

### Other components

- **Rider**
- **Driver**
- **Operator**

## Connections

- Rider → Rider cockpit: books rides (evidence: `README.md`)
- Driver → Driver cockpit: sends updates (evidence: `README.md`)
- Operator → Operations dashboard: monitors service (evidence: `README.md`)
- Dashboard shell → Rider cockpit: renders (evidence: `frontend/src/App.tsx`)
- Dashboard shell → Driver cockpit: renders (evidence: `frontend/src/App.tsx`)
- Dashboard shell → Spatial map: renders (evidence: `frontend/src/App.tsx`)
- Dashboard shell → Operations dashboard: renders (evidence: `frontend/src/App.tsx`)
- Dashboard shell → Chaos testing panel: renders (evidence: `frontend/src/App.tsx`)
- Dashboard shell → Audit stream: renders (evidence: `frontend/src/App.tsx`)
- Dashboard shell → Header metrics: renders (evidence: `frontend/src/App.tsx`)
- Rider cockpit → Socket client: uses live events
- Driver cockpit → Socket client: uses live events
- Spatial map → Socket client: uses telemetry
- Socket client → WebSocket manager: exchanges events (evidence: `README.md`)
- Rider → REST API: submits requests (evidence: `README.md`)
- Driver → REST API: posts trip actions (evidence: `README.md`)
- Chaos testing panel → REST API: runs scenarios (evidence: `README.md`)
- REST API → Candidate dispatch: routes requests (evidence: `src/server.ts`)
- REST API → WebSocket manager: broadcasts updates (evidence: `src/server.ts`)
- REST API → Driver simulation: queries simulation (evidence: `src/server.ts`)
- REST API → C++ IPC bridge: selects engine (evidence: `src/server.ts`)
- WebSocket manager → Candidate dispatch: dispatches actions (evidence: `src/gateway/ws_manager.ts`)
- WebSocket manager → Driver registry: updates driver status (evidence: `src/gateway/ws_manager.ts`)
- WebSocket manager → Trip state machine: reads active trip (evidence: `src/gateway/ws_manager.ts`)
- Candidate dispatch → TypeScript QuadTree: searches candidates (evidence: `src/core/matching_service.ts`)
- Candidate dispatch → Driver registry: locks candidates (evidence: `src/core/matching_service.ts`)
- Candidate dispatch → Trip state machine: creates and updates trips (evidence: `src/core/matching_service.ts`)
- Candidate dispatch → Trip persistence: persists trip state (evidence: `src/core/matching_service.ts`)
- Driver registry → TypeScript QuadTree: indexes drivers (evidence: `src/core/driver_registry.ts`)
- Driver registry → Driver lock leases: acquires leases (evidence: `src/core/driver_registry.ts`)
- Driver registry → Service metrics: records metrics (evidence: `src/core/driver_registry.ts`)
- Driver simulation → Driver registry: updates locations (evidence: `src/simulation/driver_simulator.ts`)
- Driver simulation → Candidate dispatch: exercises matching (evidence: `src/simulation/driver_simulator.ts`)
- Driver simulation → Trip state machine: exercises trip flow (evidence: `src/simulation/driver_simulator.ts`)
- Driver simulation → TypeScript QuadTree: uses spatial index (evidence: `src/simulation/driver_simulator.ts`)
- Driver lock leases → Redis client: stores leases (evidence: `src/core/redis_driver_lock.ts`)
- Trip persistence → Redis client: stores trips (evidence: `src/core/redis_trip_store.ts`)
- Trip persistence → Trip state machine: uses trip model (evidence: `src/core/redis_trip_store.ts`)
- Trip state machine → Input validation: validates coordinates (evidence: `src/core/trip_state_machine.ts`)
- C++ IPC bridge → Native QuadTree: uses native engine (evidence: `README.md`)
- Candidate dispatch → C++ IPC bridge: optional spatial search (evidence: `README.md`)
