janukshans/r26-se-026

Purpose and boundaries

Kaduna.lk is a monorepo for Sri Lankan roadside assistance and automotive services. It separates independently deliverable backend research components from two client applications. HTTP/JSON OpenAPI contracts are the required integration boundary; apps should not import component internals. Key shared interfaces: contracts/dispatch.openapi.yaml, contracts/geo-intelligence.openapi.yaml, contracts/predictive-maintenance.openapi.yaml.

Client entry points

The web operations dashboard is a Next.js application rooted at apps/dashboard-web/src/app/layout.tsx and apps/dashboard-web/src/app/page.tsx. It renders map, incident, dispatch, validation, and simulation views; currently it also ships static dashboard datasets under apps/dashboard-web/public/data/.

The mobile client is an Expo/React Native app entered through apps/mobile/app/_layout.tsx and apps/mobile/app/index.tsx. Expo Router partitions workflows by role and journey: driver, emergency triage, provider, and onboarding under apps/mobile/app/(driver)/, apps/mobile/app/(emergency)/, and apps/mobile/app/(provider)/.

Dispatch and emergency triage

The dispatch service is a Node/TypeScript REST backend entered at components/dispatch/src/index.ts. Its route layer exposes incident, provider, dispatch, and triage operations via components/dispatch/src/routes/dispatch.routes.ts and components/dispatch/src/routes/triage.routes.ts.

Core control flow is incident/vehicle symptoms → decision-tree or triage classification → capability matching and dispatch optimization → provider/recovery recommendation. The logic is concentrated in components/dispatch/src/services/decision-tree-engine.ts, components/dispatch/src/services/triage-engine.ts, and components/dispatch/src/services/dispatch-optimizer.ts. It persists its operational catalog through Prisma (components/dispatch/prisma/schema.prisma) and calls geo intelligence through components/dispatch/src/services/geo-client.ts.

Geo-intelligence and traffic impact

Geo intelligence is a Python service whose API and scoring boundary are components/geo-intelligence/src/api.py and components/geo-intelligence/src/impact_scoring.py. It supplies traffic-impact scoring and geo-derived dispatch inputs, with persisted/sample analytical artifacts in components/geo-intelligence/data/dispatch.json and components/geo-intelligence/data/model.json.

The dashboard’s map-facing adapter is apps/dashboard-web/src/lib/geoData.ts, while shared geo service mapping is represented by contracts/geo-service-mapping.ts. This keeps location/scoring semantics outside the web UI and available to dispatch.

Vehicle health and predictive maintenance

Predictive maintenance is a Python API rooted at components/predictive-maintenance/app/main.py, with separate ingestion and prediction endpoints in components/predictive-maintenance/app/routers/ingest.py and components/predictive-maintenance/app/routers/predict.py. Its flow is telemetry/service data ingestion → stored vehicle state → model inference → maintenance recommendation. Trained model artifacts are packaged in components/predictive-maintenance/models/, and the API contract is contracts/predictive-maintenance.openapi.yaml.

The mobile app integrates vehicle, maintenance, and emergency concerns through API/context modules such as apps/mobile/lib/vehicleApi.ts, apps/mobile/lib/maintenanceApi.ts, and apps/mobile/lib/emergencyContext.tsx. It includes ELM327 BLE and simulator adapters (apps/mobile/lib/elm327.ble.ts, apps/mobile/lib/elm327.sim.ts) as a hardware boundary.

Identity, vehicles, and claims privacy

Authentication and vehicle ownership are served by a TypeScript/Prisma component with entry point components/auth/src/index.ts, auth middleware components/auth/src/middleware/auth.ts, and route APIs in components/auth/src/routes/auth.routes.ts and components/auth/src/routes/vehicle.routes.ts. The mobile client’s Supabase configuration and auth API adapter live in apps/mobile/lib/supabase.ts and apps/mobile/lib/authApi.ts.

Claims/privacy is a separate Python service organized around application startup, repository access, schemas, and storage: components/claims-privacy/app/main.py, components/claims-privacy/app/repository.py, and components/claims-privacy/app/storage.py. A separate Node vehicle service also exists at components/vehicle-service/src/app.js; its overlap with the auth component’s vehicle routes is an integration boundary requiring ownership clarification.

Runtime and deployment shape

The system combines Next.js, Expo/React Native, Node/TypeScript REST services, Python APIs, Prisma-backed service databases, packaged ML models, and Supabase for mobile authentication. Containerized backend components include components/dispatch/Dockerfile, components/geo-intelligence/Dockerfile, and components/predictive-maintenance/Dockerfile; repository-level orchestration is docker-compose.yml. CI quality checks are defined in .github/workflows/geo-spine-quality.yml.