# er-sampoorn/rsai architecture

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

- Interactive diagram: https://gitdiagram.com/er-sampoorn/rsai
- Repository: https://github.com/er-sampoorn/rsai

## Overview

RoadSense is a crowd-sourced road-hazard monitoring and municipal response platform. Drivers’ phone telemetry is analyzed locally, reported through the events API, spatially deduplicated and stored; citizens and municipal staff then view hazards, personal reports, live maps and analytics. Authentication and audit trails support account and administrative workflows. The README documents additional map, rewards and native-sensor capabilities; excerpts confirm only selected route and page wiring, so uncertain connections are omitted.

Main entry points: [`web/lib/supabase.ts`](https://github.com/er-sampoorn/rsai/blob/main/web/lib/supabase.ts) (Supabase Client), [`web/app/tracker/page.tsx`](https://github.com/er-sampoorn/rsai/blob/main/web/app/tracker/page.tsx) (Sensor Tracker), [`web/lib/auth.ts`](https://github.com/er-sampoorn/rsai/blob/main/web/lib/auth.ts) (Auth Services), [`web/app/dashboard/page.tsx`](https://github.com/er-sampoorn/rsai/blob/main/web/app/dashboard/page.tsx) (Admin Dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Detection and Reporting"]
  node_tracker["Sensor Tracker<br/>[page.tsx]"]
  node_engine["Detection Engine<br/>[detection.ts]"]
  node_ios["iOS Sensor Bridge"]
end

subgraph group_data["Events and Identity"]
  node_events_api["Events API<br/>[route.ts]"]
  node_nearby_api["Nearby Events API<br/>[route.ts]"]
  node_supabase_client["Supabase Client<br/>[supabase.ts]"]
  node_db[("RoadSense Data")]
  node_auth["Auth Context<br/>[AuthContext.tsx]"]
  node_auth_lib["Auth Services<br/>[auth.ts]"]
  node_audit["Admin Audit<br/>[auth.ts]"]
end

subgraph group_public["Citizen Experience"]
  node_map["Hazard Map<br/>[page.tsx]"]
  node_my_reports["My Reports<br/>[page.tsx]"]
  node_rewards["Rewards<br/>[page.tsx]"]
  node_news_api["Road News API<br/>[route.ts]"]
end

subgraph group_ops["Municipal Operations"]
  node_analytics["Analytics<br/>[page.tsx]"]
  node_dashboard["Admin Dashboard<br/>[page.tsx]"]
end

node_driver(("Driver"))
node_phone(("Phone Sensors"))
node_supabase["Supabase"]
node_news_service["Times Now RSS"]

node_driver -->|"starts tracking"| node_tracker
node_phone -->|"sensor readings"| node_tracker
node_tracker -->|"processes readings"| node_engine
node_ios -.->|"native sensors"| node_tracker
node_tracker -->|"submits detections"| node_events_api
node_events_api -->|"queries and writes"| node_supabase_client
node_supabase_client -->|"database access"| node_supabase
node_supabase -->|"stores events and profiles"| node_db
node_auth -->|"loads profiles"| node_auth_lib
node_auth_lib -->|"uses client"| node_supabase_client
node_auth_lib -->|"auth and audit writes"| node_supabase
node_map -->|"loads nearby hazards"| node_nearby_api
node_nearby_api -->|"queries events"| node_supabase_client
node_my_reports -->|"loads user reports"| node_supabase_client
node_analytics -->|"loads event data"| node_supabase_client
node_dashboard -->|"reads and subscribes"| node_supabase_client
node_dashboard -->|"records admin actions"| node_audit
node_audit -->|"writes audit entries"| node_supabase
node_rewards -.->|"uses event data"| node_supabase_client
node_news_api -.->|"fetches headlines"| node_news_service

click node_tracker "https://github.com/er-sampoorn/rsai/blob/main/web/app/tracker/page.tsx"
click node_engine "https://github.com/er-sampoorn/rsai/blob/main/web/lib/detection.ts"
click node_ios "https://github.com/er-sampoorn/rsai/tree/main/web/lib/ios-bridge"
click node_events_api "https://github.com/er-sampoorn/rsai/blob/main/web/app/api/events/route.ts"
click node_nearby_api "https://github.com/er-sampoorn/rsai/blob/main/web/app/api/events/nearby/route.ts"
click node_supabase_client "https://github.com/er-sampoorn/rsai/blob/main/web/lib/supabase.ts"
click node_db "https://github.com/er-sampoorn/rsai/tree/main/backend/migrations"
click node_auth "https://github.com/er-sampoorn/rsai/blob/main/web/contexts/AuthContext.tsx"
click node_auth_lib "https://github.com/er-sampoorn/rsai/blob/main/web/lib/auth.ts"
click node_map "https://github.com/er-sampoorn/rsai/blob/main/web/app/map/page.tsx"
click node_my_reports "https://github.com/er-sampoorn/rsai/blob/main/web/app/my-reports/page.tsx"
click node_rewards "https://github.com/er-sampoorn/rsai/blob/main/web/app/rewards/page.tsx"
click node_analytics "https://github.com/er-sampoorn/rsai/blob/main/web/app/analytics/page.tsx"
click node_dashboard "https://github.com/er-sampoorn/rsai/blob/main/web/app/dashboard/page.tsx"
click node_audit "https://github.com/er-sampoorn/rsai/blob/main/web/lib/auth.ts"
click node_news_api "https://github.com/er-sampoorn/rsai/blob/main/web/app/api/news/route.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_tracker,node_engine,node_ios toneBlue
class node_events_api,node_nearby_api,node_supabase_client,node_db,node_auth,node_auth_lib,node_audit toneAmber
class node_map,node_my_reports,node_rewards,node_news_api toneMint
class node_analytics,node_dashboard toneRose
class node_driver,node_phone,node_supabase,node_news_service toneIndigo
```

## Components

### Detection and Reporting

- [Sensor Tracker](https://github.com/er-sampoorn/rsai/blob/main/web/app/tracker/page.tsx): `web/app/tracker/page.tsx`
- [Detection Engine](https://github.com/er-sampoorn/rsai/blob/main/web/lib/detection.ts): `web/lib/detection.ts`
- [iOS Sensor Bridge](https://github.com/er-sampoorn/rsai/tree/main/web/lib/ios-bridge): `web/lib/ios-bridge`

### Events and Identity

- [Events API](https://github.com/er-sampoorn/rsai/blob/main/web/app/api/events/route.ts): `web/app/api/events/route.ts`
- [Nearby Events API](https://github.com/er-sampoorn/rsai/blob/main/web/app/api/events/nearby/route.ts): `web/app/api/events/nearby/route.ts`
- [Supabase Client](https://github.com/er-sampoorn/rsai/blob/main/web/lib/supabase.ts): `web/lib/supabase.ts`
- [RoadSense Data](https://github.com/er-sampoorn/rsai/tree/main/backend/migrations): `backend/migrations`
- [Auth Context](https://github.com/er-sampoorn/rsai/blob/main/web/contexts/AuthContext.tsx): `web/contexts/AuthContext.tsx`
- [Auth Services](https://github.com/er-sampoorn/rsai/blob/main/web/lib/auth.ts): `web/lib/auth.ts`
- [Admin Audit](https://github.com/er-sampoorn/rsai/blob/main/web/lib/auth.ts): `web/lib/auth.ts`

### Citizen Experience

- [Hazard Map](https://github.com/er-sampoorn/rsai/blob/main/web/app/map/page.tsx): `web/app/map/page.tsx`
- [My Reports](https://github.com/er-sampoorn/rsai/blob/main/web/app/my-reports/page.tsx): `web/app/my-reports/page.tsx`
- [Rewards](https://github.com/er-sampoorn/rsai/blob/main/web/app/rewards/page.tsx): `web/app/rewards/page.tsx`
- [Road News API](https://github.com/er-sampoorn/rsai/blob/main/web/app/api/news/route.ts): `web/app/api/news/route.ts`

### Municipal Operations

- [Analytics](https://github.com/er-sampoorn/rsai/blob/main/web/app/analytics/page.tsx): `web/app/analytics/page.tsx`
- [Admin Dashboard](https://github.com/er-sampoorn/rsai/blob/main/web/app/dashboard/page.tsx): `web/app/dashboard/page.tsx`

### Other components

- **Driver**
- **Phone Sensors**
- **Supabase**
- **Times Now RSS**

## Connections

- Driver → Sensor Tracker: starts tracking
- Phone Sensors → Sensor Tracker: sensor readings
- Sensor Tracker → Detection Engine: processes readings
- iOS Sensor Bridge → Sensor Tracker: native sensors
- Sensor Tracker → Events API: submits detections
- Events API → Supabase Client: queries and writes
- Supabase Client → Supabase: database access
- Supabase → RoadSense Data: stores events and profiles
- Auth Context → Auth Services: loads profiles
- Auth Services → Supabase Client: uses client
- Auth Services → Supabase: auth and audit writes
- Hazard Map → Nearby Events API: loads nearby hazards
- Nearby Events API → Supabase Client: queries events
- My Reports → Supabase Client: loads user reports
- Analytics → Supabase Client: loads event data
- Admin Dashboard → Supabase Client: reads and subscribes
- Admin Dashboard → Admin Audit: records admin actions
- Admin Audit → Supabase: writes audit entries
- Rewards → Supabase Client: uses event data
- Road News API → Times Now RSS: fetches headlines