# pranjal1-1/urbanpulse-ai architecture

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

- Interactive diagram: https://gitdiagram.com/pranjal1-1/urbanpulse-ai
- Repository: https://github.com/pranjal1-1/urbanpulse-ai

## Overview

UrbanPulse AI is currently a RoadVision dataset-preparation, training, and evaluation foundation—not the full bus-sensing and GIS platform described as its longer-term pipeline. The main implemented workflow converts RDD2022 annotations into a prepared dataset, resolves and validates that dataset and training configuration, runs training, then evaluates a checkpoint and reports support-aware metrics. Contracts and Kaggle experiment tooling are additional branches. Future edge perception, multi-bus fusion, and authority-action stages are not represented as implemented components.

Main entry points: [`ai/roadvision/train.py`](https://github.com/pranjal1-1/urbanpulse-ai/blob/main/ai/roadvision/train.py) (Training orchestration), [`ai/roadvision/evaluate.py`](https://github.com/pranjal1-1/urbanpulse-ai/blob/main/ai/roadvision/evaluate.py) (Checkpoint evaluator), [`ai/data/rdd2022.py`](https://github.com/pranjal1-1/urbanpulse-ai/blob/main/ai/data/rdd2022.py) (RDD2022 converter), [`scripts/prepare_rdd2022.py`](https://github.com/pranjal1-1/urbanpulse-ai/blob/main/scripts/prepare_rdd2022.py) (Preparation CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_prepare_cli["Preparation CLI<br/>[prepare_rdd2022.py]"]
  node_rdd_converter["RDD2022 converter<br/>[rdd2022.py]"]
  node_prepared_data["Prepared dataset"]
end

subgraph group_contracts["AI contracts"]
  node_dataset_contract["Dataset contract<br/>[dataset.py]"]
  node_taxonomy["Canonical taxonomy<br/>[taxonomy.py]"]
  node_event_contract["Event schema<br/>[events.py]"]
  node_data_config["AI data config"]
end

subgraph group_roadvision["RoadVision lifecycle"]
  node_model_config["RoadVision config<br/>[config.py]"]
  node_dataset_resolver["Dataset resolver<br/>[dataset.py]"]
  node_train_cli["Training CLI"]
  node_trainer["Training orchestration<br/>[train.py]"]
  node_environment["Runtime capture<br/>[environment.py]"]
  node_run_manifest["Run provenance<br/>[manifest.py]"]
  node_checkpoint["Model checkpoint"]
  node_evaluate_cli["Evaluation CLI"]
  node_evaluator["Checkpoint evaluator<br/>[evaluate.py]"]
  node_metrics["Metric reporting<br/>[metrics.py]"]
end

subgraph group_experiments["Experiments"]
  node_kaggle_runner["Kaggle runner<br/>[kaggle_runner.py]"]
  node_speed_experiment["Speed experiment"]
  node_speed_telemetry["Speed telemetry<br/>[speed_telemetry.py]"]
end

node_engineer(("Engineer"))
node_source_data["RDD2022 source"]

node_engineer -->|"runs preparation"| node_prepare_cli
node_prepare_cli -->|"calls converter"| node_rdd_converter
node_source_data -->|"reads annotations"| node_rdd_converter
node_rdd_converter -->|"writes dataset"| node_prepared_data
node_prepare_cli -->|"validates contract"| node_dataset_contract
node_rdd_converter -->|"uses labels"| node_taxonomy
node_taxonomy -->|"loads taxonomy"| node_data_config
node_event_contract -->|"validates classes"| node_taxonomy
node_engineer -->|"runs training"| node_train_cli
node_train_cli -->|"loads settings"| node_model_config
node_train_cli -->|"invokes training"| node_trainer
node_trainer -->|"resolves dataset"| node_dataset_resolver
node_dataset_resolver -->|"reads dataset"| node_prepared_data
node_trainer -->|"captures runtime"| node_environment
node_trainer -->|"records run"| node_run_manifest
node_trainer -->|"writes weights"| node_checkpoint
node_engineer -->|"runs evaluation"| node_evaluate_cli
node_evaluate_cli -->|"calls evaluator"| node_evaluator
node_evaluator -->|"loads weights"| node_checkpoint
node_evaluator -->|"resolves dataset"| node_dataset_resolver
node_evaluator -->|"builds report"| node_metrics
node_engineer -->|"runs experiment"| node_speed_experiment
node_speed_experiment -->|"uses runner"| node_kaggle_runner
node_speed_experiment -->|"uses telemetry"| node_speed_telemetry

click node_prepare_cli "https://github.com/pranjal1-1/urbanpulse-ai/blob/main/scripts/prepare_rdd2022.py"
click node_rdd_converter "https://github.com/pranjal1-1/urbanpulse-ai/blob/main/ai/data/rdd2022.py"
click node_dataset_contract "https://github.com/pranjal1-1/urbanpulse-ai/blob/main/ai/contracts/dataset.py"
click node_taxonomy "https://github.com/pranjal1-1/urbanpulse-ai/blob/main/ai/contracts/taxonomy.py"
click node_event_contract "https://github.com/pranjal1-1/urbanpulse-ai/blob/main/ai/contracts/events.py"
click node_data_config "https://github.com/pranjal1-1/urbanpulse-ai/blob/main/configs/datasets/SIH26124_AI_Data_Config_v1.json"
click node_model_config "https://github.com/pranjal1-1/urbanpulse-ai/blob/main/ai/roadvision/config.py"
click node_dataset_resolver "https://github.com/pranjal1-1/urbanpulse-ai/blob/main/ai/roadvision/dataset.py"
click node_train_cli "https://github.com/pranjal1-1/urbanpulse-ai/blob/main/scripts/train_roadvision.py"
click node_trainer "https://github.com/pranjal1-1/urbanpulse-ai/blob/main/ai/roadvision/train.py"
click node_environment "https://github.com/pranjal1-1/urbanpulse-ai/blob/main/ai/roadvision/environment.py"
click node_run_manifest "https://github.com/pranjal1-1/urbanpulse-ai/blob/main/ai/roadvision/manifest.py"
click node_evaluate_cli "https://github.com/pranjal1-1/urbanpulse-ai/blob/main/scripts/evaluate_roadvision.py"
click node_evaluator "https://github.com/pranjal1-1/urbanpulse-ai/blob/main/ai/roadvision/evaluate.py"
click node_metrics "https://github.com/pranjal1-1/urbanpulse-ai/blob/main/ai/roadvision/metrics.py"
click node_kaggle_runner "https://github.com/pranjal1-1/urbanpulse-ai/blob/main/experiments/kaggle/kaggle_runner.py"
click node_speed_experiment "https://github.com/pranjal1-1/urbanpulse-ai/blob/main/experiments/kaggle/speed_experiment.py"
click node_speed_telemetry "https://github.com/pranjal1-1/urbanpulse-ai/blob/main/experiments/kaggle/speed_telemetry.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_prepare_cli,node_rdd_converter,node_prepared_data toneBlue
class node_dataset_contract,node_taxonomy,node_event_contract,node_data_config toneAmber
class node_model_config,node_dataset_resolver,node_train_cli,node_trainer,node_environment,node_run_manifest,node_checkpoint,node_evaluate_cli,node_evaluator,node_metrics toneMint
class node_kaggle_runner,node_speed_experiment,node_speed_telemetry toneRose
class node_engineer,node_source_data toneIndigo
```

## Components

### Data preparation

- [Preparation CLI](https://github.com/pranjal1-1/urbanpulse-ai/blob/main/scripts/prepare_rdd2022.py): `scripts/prepare_rdd2022.py`
- [RDD2022 converter](https://github.com/pranjal1-1/urbanpulse-ai/blob/main/ai/data/rdd2022.py): `ai/data/rdd2022.py`
- **Prepared dataset**

### AI contracts

- [Dataset contract](https://github.com/pranjal1-1/urbanpulse-ai/blob/main/ai/contracts/dataset.py): `ai/contracts/dataset.py`
- [Canonical taxonomy](https://github.com/pranjal1-1/urbanpulse-ai/blob/main/ai/contracts/taxonomy.py): `ai/contracts/taxonomy.py`
- [Event schema](https://github.com/pranjal1-1/urbanpulse-ai/blob/main/ai/contracts/events.py): `ai/contracts/events.py`
- [AI data config](https://github.com/pranjal1-1/urbanpulse-ai/blob/main/configs/datasets/SIH26124_AI_Data_Config_v1.json): `configs/datasets/SIH26124_AI_Data_Config_v1.json`

### RoadVision lifecycle

- [RoadVision config](https://github.com/pranjal1-1/urbanpulse-ai/blob/main/ai/roadvision/config.py): `ai/roadvision/config.py`
- [Dataset resolver](https://github.com/pranjal1-1/urbanpulse-ai/blob/main/ai/roadvision/dataset.py): `ai/roadvision/dataset.py`
- [Training CLI](https://github.com/pranjal1-1/urbanpulse-ai/blob/main/scripts/train_roadvision.py): `scripts/train_roadvision.py`
- [Training orchestration](https://github.com/pranjal1-1/urbanpulse-ai/blob/main/ai/roadvision/train.py): `ai/roadvision/train.py`
- [Runtime capture](https://github.com/pranjal1-1/urbanpulse-ai/blob/main/ai/roadvision/environment.py): `ai/roadvision/environment.py`
- [Run provenance](https://github.com/pranjal1-1/urbanpulse-ai/blob/main/ai/roadvision/manifest.py): `ai/roadvision/manifest.py`
- **Model checkpoint**
- [Evaluation CLI](https://github.com/pranjal1-1/urbanpulse-ai/blob/main/scripts/evaluate_roadvision.py): `scripts/evaluate_roadvision.py`
- [Checkpoint evaluator](https://github.com/pranjal1-1/urbanpulse-ai/blob/main/ai/roadvision/evaluate.py): `ai/roadvision/evaluate.py`
- [Metric reporting](https://github.com/pranjal1-1/urbanpulse-ai/blob/main/ai/roadvision/metrics.py): `ai/roadvision/metrics.py`

### Experiments

- [Kaggle runner](https://github.com/pranjal1-1/urbanpulse-ai/blob/main/experiments/kaggle/kaggle_runner.py): `experiments/kaggle/kaggle_runner.py`
- [Speed experiment](https://github.com/pranjal1-1/urbanpulse-ai/blob/main/experiments/kaggle/speed_experiment.py): `experiments/kaggle/speed_experiment.py`
- [Speed telemetry](https://github.com/pranjal1-1/urbanpulse-ai/blob/main/experiments/kaggle/speed_telemetry.py): `experiments/kaggle/speed_telemetry.py`

### Other components

- **Engineer**
- **RDD2022 source**

## Connections

- Engineer → Preparation CLI: runs preparation (evidence: `README.md`)
- Preparation CLI → RDD2022 converter: calls converter (evidence: `scripts/prepare_rdd2022.py`)
- RDD2022 source → RDD2022 converter: reads annotations (evidence: `ai/data/rdd2022.py`)
- RDD2022 converter → Prepared dataset: writes dataset (evidence: `ai/data/rdd2022.py`)
- Preparation CLI → Dataset contract: validates contract (evidence: `scripts/prepare_rdd2022.py`)
- RDD2022 converter → Canonical taxonomy: uses labels (evidence: `ai/data/rdd2022.py`)
- Canonical taxonomy → AI data config: loads taxonomy (evidence: `ai/contracts/taxonomy.py`)
- Event schema → Canonical taxonomy: validates classes (evidence: `ai/contracts/events.py`)
- Engineer → Training CLI: runs training (evidence: `README.md`)
- Training CLI → RoadVision config: loads settings (evidence: `scripts/train_roadvision.py`)
- Training CLI → Training orchestration: invokes training (evidence: `scripts/train_roadvision.py`)
- Training orchestration → Dataset resolver: resolves dataset (evidence: `ai/roadvision/train.py`)
- Dataset resolver → Prepared dataset: reads dataset (evidence: `ai/roadvision/dataset.py`)
- Training orchestration → Runtime capture: captures runtime (evidence: `ai/roadvision/train.py`)
- Training orchestration → Run provenance: records run (evidence: `ai/roadvision/train.py`)
- Training orchestration → Model checkpoint: writes weights (evidence: `ai/roadvision/train.py`)
- Engineer → Evaluation CLI: runs evaluation (evidence: `README.md`)
- Evaluation CLI → Checkpoint evaluator: calls evaluator (evidence: `scripts/evaluate_roadvision.py`)
- Checkpoint evaluator → Model checkpoint: loads weights (evidence: `ai/roadvision/evaluate.py`)
- Checkpoint evaluator → Dataset resolver: resolves dataset (evidence: `ai/roadvision/evaluate.py`)
- Checkpoint evaluator → Metric reporting: builds report (evidence: `ai/roadvision/evaluate.py`)
- Engineer → Speed experiment: runs experiment
- Speed experiment → Kaggle runner: uses runner (evidence: `experiments/kaggle/speed_experiment.py`)
- Speed experiment → Speed telemetry: uses telemetry (evidence: `experiments/kaggle/speed_experiment.py`)
