# dhanush-10-1/spdrha architecture

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

- Interactive diagram: https://gitdiagram.com/dhanush-10-1/spdrha
- Repository: https://github.com/dhanush-10-1/spdrha

## Overview

SPDRHA is a road-hazard detection product: a phone gathers motion and GPS data, classifies sensor windows on-device, stores non-normal detections, and synchronizes them to a FastAPI backend. The backend also exposes anomaly and health APIs and has a separate model-training workflow. The README identifies the root app as active; sampled runtime excerpts are chiefly from the parallel irads-mobile app, so unsampled root-app and backend internals are represented only where the README or SOURCE INDEX supports them.

Main entry points: [`src/ai/aiService.ts`](https://github.com/dhanush-10-1/spdrha/blob/main/src/ai/aiService.ts) (Inference and policy), [`irads-backend/backend/main.py`](https://github.com/dhanush-10-1/spdrha/blob/main/irads-backend/backend/main.py) (FastAPI application), [`irads-backend/backend/routers/anomalies.py`](https://github.com/dhanush-10-1/spdrha/blob/main/irads-backend/backend/routers/anomalies.py) (Anomaly API), [`src/storage/syncService.ts`](https://github.com/dhanush-10-1/spdrha/blob/main/src/storage/syncService.ts) (Upload and retry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mobile["Mobile collection"]
  node_rootapp["Active mobile app<br/>[App.tsx]"]
  node_sensor["Motion and GPS capture<br/>[SensorManager.ts]"]
  node_sensor_types["Sensor reading types<br/>[types.ts]"]
end

subgraph group_inference["On-device detection"]
  node_windows["Window builder<br/>[windowManager.ts]"]
  node_ai["Inference and policy<br/>[aiService.ts]"]
  node_tflite["TFLite inference"]
  node_normalization["Input normalization<br/>[normalization.ts]"]
  node_lifecycle["Inference lifecycle"]
  node_persistence_policy["Persistence policy"]
end

subgraph group_sync["Persistence and sync"]
  node_localdb[("Anomaly event store<br/>[database.ts]")]
  node_identity["Device identity<br/>[deviceIdentity.ts]"]
  node_syncservice["Upload and retry<br/>[syncService.ts]"]
end

subgraph group_backend["Backend services"]
  node_backendapp["FastAPI application<br/>[main.py]"]
  node_anomalyapi["Anomaly API<br/>[anomalies.py]"]
  node_healthapi["Health API<br/>[health.py]"]
  node_devauth["Development auth<br/>[dev_auth.py]"]
  node_pg[("Backend database connection<br/>[connection.py]")]
  node_kafka["Kafka producer<br/>[producer.py]"]
  node_consumer["Anomaly consumer"]
  node_dbwriter["Consumer DB writer<br/>[db_writer.py]"]
end

subgraph group_ml["Model development"]
  node_preprocess["Training preprocessing"]
  node_dataset["Training dataset<br/>[dataset.py]"]
  node_training["Model training<br/>[train.py]"]
  node_mlmodel["Training model<br/>[model.py]"]
end

node_driver(("Phone user"))
node_phone_sensors(("Phone sensors and GPS"))
node_api_client(("Backend HTTP API"))

node_driver -->|"uses"| node_rootapp
node_phone_sensors -->|"provides readings"| node_sensor
node_sensor -.->|"collects data for"| node_rootapp
node_rootapp -.->|"submits readings"| node_ai
node_ai -->|"builds windows"| node_windows
node_ai -->|"predicts with"| node_tflite
node_tflite -->|"normalizes input"| node_normalization
node_ai -->|"manages inference"| node_lifecycle
node_ai -->|"checks persistence"| node_persistence_policy
node_ai -->|"saves hazards"| node_localdb
node_ai -->|"gets device ID"| node_identity
node_ai -->|"starts sync"| node_syncservice
node_syncservice -->|"reads and marks"| node_localdb
node_syncservice -->|"posts events"| node_api_client
node_api_client -.->|"sends events"| node_anomalyapi
node_backendapp -->|"registers router"| node_anomalyapi
node_backendapp -->|"registers router"| node_healthapi
node_backendapp -->|"registers router"| node_devauth
node_backendapp -->|"opens and closes"| node_pg
node_backendapp -->|"starts and stops"| node_kafka
node_anomalyapi -->|"accesses database"| node_pg
node_anomalyapi -->|"uses producer"| node_kafka
node_consumer -.->|"delegates writes"| node_dbwriter
node_preprocess -->|"prepares data for"| node_dataset
node_training -->|"uses dataset"| node_dataset
node_training -->|"uses model"| node_mlmodel

click node_rootapp "https://github.com/dhanush-10-1/spdrha/blob/main/App.tsx"
click node_sensor "https://github.com/dhanush-10-1/spdrha/blob/main/src/sensors/SensorManager.ts"
click node_sensor_types "https://github.com/dhanush-10-1/spdrha/blob/main/src/sensors/types.ts"
click node_windows "https://github.com/dhanush-10-1/spdrha/blob/main/src/ai/windowManager.ts"
click node_ai "https://github.com/dhanush-10-1/spdrha/blob/main/src/ai/aiService.ts"
click node_tflite "https://github.com/dhanush-10-1/spdrha/blob/main/src/ai/tflite_inference.ts"
click node_normalization "https://github.com/dhanush-10-1/spdrha/blob/main/src/ai/normalization.ts"
click node_lifecycle "https://github.com/dhanush-10-1/spdrha/blob/main/src/ai/inferenceLifecycle.ts"
click node_persistence_policy "https://github.com/dhanush-10-1/spdrha/blob/main/src/ai/anomalyPersistencePolicy.ts"
click node_localdb "https://github.com/dhanush-10-1/spdrha/blob/main/src/storage/database.ts"
click node_identity "https://github.com/dhanush-10-1/spdrha/blob/main/src/storage/deviceIdentity.ts"
click node_syncservice "https://github.com/dhanush-10-1/spdrha/blob/main/src/storage/syncService.ts"
click node_backendapp "https://github.com/dhanush-10-1/spdrha/blob/main/irads-backend/backend/main.py"
click node_anomalyapi "https://github.com/dhanush-10-1/spdrha/blob/main/irads-backend/backend/routers/anomalies.py"
click node_healthapi "https://github.com/dhanush-10-1/spdrha/blob/main/irads-backend/backend/routers/health.py"
click node_devauth "https://github.com/dhanush-10-1/spdrha/blob/main/irads-backend/backend/routers/dev_auth.py"
click node_pg "https://github.com/dhanush-10-1/spdrha/blob/main/irads-backend/backend/db/connection.py"
click node_kafka "https://github.com/dhanush-10-1/spdrha/blob/main/irads-backend/backend/kafka/producer.py"
click node_consumer "https://github.com/dhanush-10-1/spdrha/blob/main/irads-backend/consumer/anomaly_consumer.py"
click node_dbwriter "https://github.com/dhanush-10-1/spdrha/blob/main/irads-backend/consumer/db_writer.py"
click node_preprocess "https://github.com/dhanush-10-1/spdrha/tree/main/irads-backend/ml/preprocessing"
click node_dataset "https://github.com/dhanush-10-1/spdrha/blob/main/irads-backend/ml/training/dataset.py"
click node_training "https://github.com/dhanush-10-1/spdrha/blob/main/irads-backend/ml/training/train.py"
click node_mlmodel "https://github.com/dhanush-10-1/spdrha/blob/main/irads-backend/ml/training/model.py"

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_rootapp,node_sensor,node_sensor_types,node_driver toneBlue
class node_windows,node_ai,node_tflite,node_normalization,node_lifecycle,node_persistence_policy toneAmber
class node_localdb,node_identity,node_syncservice,node_api_client toneMint
class node_backendapp,node_anomalyapi,node_healthapi,node_devauth,node_pg,node_kafka,node_consumer,node_dbwriter toneRose
class node_preprocess,node_dataset,node_training,node_mlmodel,node_phone_sensors toneIndigo
```

## Components

### Mobile collection

- [Active mobile app](https://github.com/dhanush-10-1/spdrha/blob/main/App.tsx): `App.tsx`
- [Motion and GPS capture](https://github.com/dhanush-10-1/spdrha/blob/main/src/sensors/SensorManager.ts): `src/sensors/SensorManager.ts`
- [Sensor reading types](https://github.com/dhanush-10-1/spdrha/blob/main/src/sensors/types.ts): `src/sensors/types.ts`

### On-device detection

- [Window builder](https://github.com/dhanush-10-1/spdrha/blob/main/src/ai/windowManager.ts): `src/ai/windowManager.ts`
- [Inference and policy](https://github.com/dhanush-10-1/spdrha/blob/main/src/ai/aiService.ts): `src/ai/aiService.ts`
- [TFLite inference](https://github.com/dhanush-10-1/spdrha/blob/main/src/ai/tflite_inference.ts): `src/ai/tflite_inference.ts`
- [Input normalization](https://github.com/dhanush-10-1/spdrha/blob/main/src/ai/normalization.ts): `src/ai/normalization.ts`
- [Inference lifecycle](https://github.com/dhanush-10-1/spdrha/blob/main/src/ai/inferenceLifecycle.ts): `src/ai/inferenceLifecycle.ts`
- [Persistence policy](https://github.com/dhanush-10-1/spdrha/blob/main/src/ai/anomalyPersistencePolicy.ts): `src/ai/anomalyPersistencePolicy.ts`

### Persistence and sync

- [Anomaly event store](https://github.com/dhanush-10-1/spdrha/blob/main/src/storage/database.ts): `src/storage/database.ts`
- [Device identity](https://github.com/dhanush-10-1/spdrha/blob/main/src/storage/deviceIdentity.ts): `src/storage/deviceIdentity.ts`
- [Upload and retry](https://github.com/dhanush-10-1/spdrha/blob/main/src/storage/syncService.ts): `src/storage/syncService.ts`

### Backend services

- [FastAPI application](https://github.com/dhanush-10-1/spdrha/blob/main/irads-backend/backend/main.py): `irads-backend/backend/main.py`
- [Anomaly API](https://github.com/dhanush-10-1/spdrha/blob/main/irads-backend/backend/routers/anomalies.py): `irads-backend/backend/routers/anomalies.py`
- [Health API](https://github.com/dhanush-10-1/spdrha/blob/main/irads-backend/backend/routers/health.py): `irads-backend/backend/routers/health.py`
- [Development auth](https://github.com/dhanush-10-1/spdrha/blob/main/irads-backend/backend/routers/dev_auth.py): `irads-backend/backend/routers/dev_auth.py`
- [Backend database connection](https://github.com/dhanush-10-1/spdrha/blob/main/irads-backend/backend/db/connection.py): `irads-backend/backend/db/connection.py`
- [Kafka producer](https://github.com/dhanush-10-1/spdrha/blob/main/irads-backend/backend/kafka/producer.py): `irads-backend/backend/kafka/producer.py`
- [Anomaly consumer](https://github.com/dhanush-10-1/spdrha/blob/main/irads-backend/consumer/anomaly_consumer.py): `irads-backend/consumer/anomaly_consumer.py`
- [Consumer DB writer](https://github.com/dhanush-10-1/spdrha/blob/main/irads-backend/consumer/db_writer.py): `irads-backend/consumer/db_writer.py`

### Model development

- [Training preprocessing](https://github.com/dhanush-10-1/spdrha/tree/main/irads-backend/ml/preprocessing): `irads-backend/ml/preprocessing`
- [Training dataset](https://github.com/dhanush-10-1/spdrha/blob/main/irads-backend/ml/training/dataset.py): `irads-backend/ml/training/dataset.py`
- [Model training](https://github.com/dhanush-10-1/spdrha/blob/main/irads-backend/ml/training/train.py): `irads-backend/ml/training/train.py`
- [Training model](https://github.com/dhanush-10-1/spdrha/blob/main/irads-backend/ml/training/model.py): `irads-backend/ml/training/model.py`

### Other components

- **Phone user**
- **Phone sensors and GPS**
- **Backend HTTP API**

## Connections

- Phone user → Active mobile app: uses (evidence: `README.md`)
- Phone sensors and GPS → Motion and GPS capture: provides readings (evidence: `README.md`)
- Motion and GPS capture → Active mobile app: collects data for (evidence: `App.tsx`)
- Active mobile app → Inference and policy: submits readings
- Inference and policy → Window builder: builds windows (evidence: `src/ai/aiService.ts`)
- Inference and policy → TFLite inference: predicts with (evidence: `src/ai/aiService.ts`)
- TFLite inference → Input normalization: normalizes input (evidence: `src/ai/tflite_inference.ts`)
- Inference and policy → Inference lifecycle: manages inference (evidence: `src/ai/aiService.ts`)
- Inference and policy → Persistence policy: checks persistence (evidence: `src/ai/aiService.ts`)
- Inference and policy → Anomaly event store: saves hazards (evidence: `src/ai/aiService.ts`)
- Inference and policy → Device identity: gets device ID (evidence: `src/ai/aiService.ts`)
- Inference and policy → Upload and retry: starts sync (evidence: `src/ai/aiService.ts`)
- Upload and retry → Anomaly event store: reads and marks (evidence: `src/storage/syncService.ts`)
- Upload and retry → Backend HTTP API: posts events (evidence: `src/storage/syncService.ts`)
- Backend HTTP API → Anomaly API: sends events (evidence: `README.md`)
- FastAPI application → Anomaly API: registers router (evidence: `irads-backend/backend/main.py`)
- FastAPI application → Health API: registers router (evidence: `irads-backend/backend/main.py`)
- FastAPI application → Development auth: registers router (evidence: `irads-backend/backend/main.py`)
- FastAPI application → Backend database connection: opens and closes (evidence: `irads-backend/backend/main.py`)
- FastAPI application → Kafka producer: starts and stops (evidence: `irads-backend/backend/main.py`)
- Anomaly API → Backend database connection: accesses database (evidence: `irads-backend/backend/routers/anomalies.py`)
- Anomaly API → Kafka producer: uses producer (evidence: `irads-backend/backend/routers/anomalies.py`)
- Anomaly consumer → Consumer DB writer: delegates writes
- Training preprocessing → Training dataset: prepares data for (evidence: `irads-backend/ml/training/dataset.py`)
- Model training → Training dataset: uses dataset (evidence: `irads-backend/ml/training/train.py`)
- Model training → Training model: uses model (evidence: `irads-backend/ml/training/train.py`)