# satyak99108/idr architecture

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

- Interactive diagram: https://gitdiagram.com/satyak99108/idr
- Repository: https://github.com/satyak99108/idr

## Overview

IDR combines offline Python navigation pipelines, a sensor-agnostic edge engine, and a native Android navigation app. The principal workflow takes IMU and optional GNSS readings through preprocessing, velocity/motion estimation, inertial navigation and GNSS fusion, then optional road-map matching to produce a vehicle position and navigation state. README architecture supports the edge adapter-to-engine-to-client flow; sampled excerpts confirm the Python pipeline’s fusion orchestration and the map matcher’s fusion-output input. Other subsystem links are omitted where source wiring was not sampled.

Main entry points: [`src/pipeline/engine.py`](https://github.com/satyak99108/idr/blob/main/src/pipeline/engine.py) (Python Pipeline), [`android/app/src/main/java/com/idr/navigation/ui/MainActivity.kt`](https://github.com/satyak99108/idr/blob/main/android/app/src/main/java/com/idr/navigation/ui/MainActivity.kt) (Navigation UI), [`src/fusion/fusion_engine.py`](https://github.com/satyak99108/idr/blob/main/src/fusion/fusion_engine.py) (GNSS-INS Fusion), [`android/app/src/main/java/com/idr/navigation/core/DeadReckoningEngine.kt`](https://github.com/satyak99108/idr/blob/main/android/app/src/main/java/com/idr/navigation/core/DeadReckoningEngine.kt) (Android DR Engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Sensors and Data"]
  node_preprocessing["Data Preparation"]
end

subgraph group_estimate["Navigation Estimation"]
  node_pipeline["Python Pipeline<br/>[engine.py]"]
  node_motion["Motion Classification<br/>[classifier.py]"]
  node_velocity_model["Velocity Model<br/>[model.py]"]
  node_ai_training["AI Training and Quantization"]
  node_ins["Inertial Navigation"]
  node_fusion["GNSS-INS Fusion<br/>[fusion_engine.py]"]
  node_ekf["Navigation EKF<br/>[ekf.py]"]
  node_mode_manager["GNSS Mode Management<br/>[mode_manager.py]"]
  node_map_matcher["HMM Map Matching<br/>[matcher_engine.py]"]
  node_road_graph[("Road Network<br/>[road_graph.py]")]
end

subgraph group_edge["Edge Streaming"]
  node_sensor_contracts["Sensor Contracts<br/>[contracts.py]"]
  node_smartphone_adapter["Phone Adapter"]
  node_imu_adapter["External IMU Adapter"]
  node_edge_engine["Edge Engine<br/>[core.py]"]
end

subgraph group_android["Android App"]
  node_android_activity["Navigation UI<br/>[MainActivity.kt]"]
  node_android_sensor["Android Sensor Providers"]
  node_android_engine["Android DR Engine"]
  node_android_mode["Android Mode Manager"]
  node_android_ai["On-device Velocity Inference"]
end

subgraph group_support["Calibration and Evaluation"]
  node_calibration["Sensor Calibration"]
  node_outage_sim["Outage Simulation"]
  node_evaluation["Performance Evaluation"]
end

node_vehicle(("Vehicle / Sensors"))
node_dataset["Recorded Dataset"]
node_edge_client(("Navigation Client"))

node_vehicle -->|"supplies phone data"| node_smartphone_adapter
node_vehicle -->|"supplies IMU data"| node_imu_adapter
node_smartphone_adapter -->|"creates packet"| node_sensor_contracts
node_imu_adapter -->|"creates packet"| node_sensor_contracts
node_sensor_contracts -->|"provides input"| node_edge_engine
node_edge_engine -->|"emits navigation output"| node_edge_client
node_dataset -->|"loads data"| node_preprocessing
node_preprocessing -->|"provides prepared data"| node_pipeline
node_pipeline -->|"runs fusion"| node_fusion
node_fusion -->|"updates state"| node_ekf
node_fusion -->|"manages modes"| node_mode_manager
node_pipeline -.->|"supplies fusion results"| node_map_matcher
node_map_matcher -->|"uses road network"| node_road_graph
node_pipeline -->|"classifies motion"| node_motion
node_pipeline -->|"estimates velocity"| node_velocity_model
node_ai_training -.->|"trains or quantizes"| node_velocity_model
node_dataset -.->|"supports calibration"| node_calibration
node_dataset -.->|"provides trajectory"| node_outage_sim
node_outage_sim -->|"generates test outages"| node_evaluation
node_pipeline -.->|"provides navigation results"| node_evaluation
node_vehicle -->|"provides live readings"| node_android_sensor
node_android_sensor -->|"provides sensor frames"| node_android_activity
node_android_activity -->|"updates navigation"| node_android_engine
node_android_engine -->|"updates mode"| node_android_mode
node_android_activity -.->|"uses inference"| node_android_ai
node_android_engine -->|"provides position"| node_android_activity

click node_preprocessing "https://github.com/satyak99108/idr/tree/main/src/preprocessing"
click node_sensor_contracts "https://github.com/satyak99108/idr/blob/main/edge/contracts.py"
click node_smartphone_adapter "https://github.com/satyak99108/idr/blob/main/edge/adapters/smartphone_adapter.py"
click node_imu_adapter "https://github.com/satyak99108/idr/blob/main/edge/adapters/external_imu_adapter.py"
click node_edge_engine "https://github.com/satyak99108/idr/blob/main/edge/core.py"
click node_pipeline "https://github.com/satyak99108/idr/blob/main/src/pipeline/engine.py"
click node_motion "https://github.com/satyak99108/idr/blob/main/src/motion/classifier.py"
click node_velocity_model "https://github.com/satyak99108/idr/blob/main/src/ai/model.py"
click node_ai_training "https://github.com/satyak99108/idr/tree/main/src/ai"
click node_ins "https://github.com/satyak99108/idr/tree/main/src/ins"
click node_fusion "https://github.com/satyak99108/idr/blob/main/src/fusion/fusion_engine.py"
click node_ekf "https://github.com/satyak99108/idr/blob/main/src/fusion/ekf.py"
click node_mode_manager "https://github.com/satyak99108/idr/blob/main/src/fusion/mode_manager.py"
click node_map_matcher "https://github.com/satyak99108/idr/blob/main/src/map_matching/matcher_engine.py"
click node_road_graph "https://github.com/satyak99108/idr/blob/main/src/map_matching/road_graph.py"
click node_calibration "https://github.com/satyak99108/idr/tree/main/src/calibration"
click node_outage_sim "https://github.com/satyak99108/idr/blob/main/src/simulation/outage_simulator.py"
click node_evaluation "https://github.com/satyak99108/idr/tree/main/src/evaluation"
click node_android_activity "https://github.com/satyak99108/idr/blob/main/android/app/src/main/java/com/idr/navigation/ui/MainActivity.kt"
click node_android_sensor "https://github.com/satyak99108/idr/tree/main/android/app/src/main/java/com/idr/navigation/sensor"
click node_android_engine "https://github.com/satyak99108/idr/blob/main/android/app/src/main/java/com/idr/navigation/core/DeadReckoningEngine.kt"
click node_android_mode "https://github.com/satyak99108/idr/blob/main/android/app/src/main/java/com/idr/navigation/core/NavigationModeManager.kt"
click node_android_ai "https://github.com/satyak99108/idr/blob/main/android/app/src/main/java/com/idr/navigation/ai/TFLiteVelocityEstimator.kt"

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_preprocessing,node_edge_client toneBlue
class node_pipeline,node_motion,node_velocity_model,node_ai_training,node_ins,node_fusion,node_ekf,node_mode_manager,node_map_matcher,node_road_graph toneAmber
class node_sensor_contracts,node_smartphone_adapter,node_imu_adapter,node_edge_engine toneMint
class node_android_activity,node_android_sensor,node_android_engine,node_android_mode,node_android_ai toneRose
class node_calibration,node_outage_sim,node_evaluation,node_vehicle,node_dataset toneIndigo
```

## Components

### Sensors and Data

- [Data Preparation](https://github.com/satyak99108/idr/tree/main/src/preprocessing): `src/preprocessing`

### Navigation Estimation

- [Python Pipeline](https://github.com/satyak99108/idr/blob/main/src/pipeline/engine.py): `src/pipeline/engine.py`
- [Motion Classification](https://github.com/satyak99108/idr/blob/main/src/motion/classifier.py): `src/motion/classifier.py`
- [Velocity Model](https://github.com/satyak99108/idr/blob/main/src/ai/model.py): `src/ai/model.py`
- [AI Training and Quantization](https://github.com/satyak99108/idr/tree/main/src/ai): `src/ai`
- [Inertial Navigation](https://github.com/satyak99108/idr/tree/main/src/ins): `src/ins`
- [GNSS-INS Fusion](https://github.com/satyak99108/idr/blob/main/src/fusion/fusion_engine.py): `src/fusion/fusion_engine.py`
- [Navigation EKF](https://github.com/satyak99108/idr/blob/main/src/fusion/ekf.py): `src/fusion/ekf.py`
- [GNSS Mode Management](https://github.com/satyak99108/idr/blob/main/src/fusion/mode_manager.py): `src/fusion/mode_manager.py`
- [HMM Map Matching](https://github.com/satyak99108/idr/blob/main/src/map_matching/matcher_engine.py): `src/map_matching/matcher_engine.py`
- [Road Network](https://github.com/satyak99108/idr/blob/main/src/map_matching/road_graph.py): `src/map_matching/road_graph.py`

### Edge Streaming

- [Sensor Contracts](https://github.com/satyak99108/idr/blob/main/edge/contracts.py): `edge/contracts.py`
- [Phone Adapter](https://github.com/satyak99108/idr/blob/main/edge/adapters/smartphone_adapter.py): `edge/adapters/smartphone_adapter.py`
- [External IMU Adapter](https://github.com/satyak99108/idr/blob/main/edge/adapters/external_imu_adapter.py): `edge/adapters/external_imu_adapter.py`
- [Edge Engine](https://github.com/satyak99108/idr/blob/main/edge/core.py): `edge/core.py`

### Android App

- [Navigation UI](https://github.com/satyak99108/idr/blob/main/android/app/src/main/java/com/idr/navigation/ui/MainActivity.kt): `android/app/src/main/java/com/idr/navigation/ui/MainActivity.kt`
- [Android Sensor Providers](https://github.com/satyak99108/idr/tree/main/android/app/src/main/java/com/idr/navigation/sensor): `android/app/src/main/java/com/idr/navigation/sensor`
- [Android DR Engine](https://github.com/satyak99108/idr/blob/main/android/app/src/main/java/com/idr/navigation/core/DeadReckoningEngine.kt): `android/app/src/main/java/com/idr/navigation/core/DeadReckoningEngine.kt`
- [Android Mode Manager](https://github.com/satyak99108/idr/blob/main/android/app/src/main/java/com/idr/navigation/core/NavigationModeManager.kt): `android/app/src/main/java/com/idr/navigation/core/NavigationModeManager.kt`
- [On-device Velocity Inference](https://github.com/satyak99108/idr/blob/main/android/app/src/main/java/com/idr/navigation/ai/TFLiteVelocityEstimator.kt): `android/app/src/main/java/com/idr/navigation/ai/TFLiteVelocityEstimator.kt`

### Calibration and Evaluation

- [Sensor Calibration](https://github.com/satyak99108/idr/tree/main/src/calibration): `src/calibration`
- [Outage Simulation](https://github.com/satyak99108/idr/blob/main/src/simulation/outage_simulator.py): `src/simulation/outage_simulator.py`
- [Performance Evaluation](https://github.com/satyak99108/idr/tree/main/src/evaluation): `src/evaluation`

### Other components

- **Vehicle / Sensors**
- **Recorded Dataset**
- **Navigation Client**

## Connections

- Vehicle / Sensors → Phone Adapter: supplies phone data
- Vehicle / Sensors → External IMU Adapter: supplies IMU data
- Phone Adapter → Sensor Contracts: creates packet
- External IMU Adapter → Sensor Contracts: creates packet
- Sensor Contracts → Edge Engine: provides input
- Edge Engine → Navigation Client: emits navigation output
- Recorded Dataset → Data Preparation: loads data
- Data Preparation → Python Pipeline: provides prepared data
- Python Pipeline → GNSS-INS Fusion: runs fusion
- GNSS-INS Fusion → Navigation EKF: updates state
- GNSS-INS Fusion → GNSS Mode Management: manages modes
- Python Pipeline → HMM Map Matching: supplies fusion results
- HMM Map Matching → Road Network: uses road network
- Python Pipeline → Motion Classification: classifies motion
- Python Pipeline → Velocity Model: estimates velocity
- AI Training and Quantization → Velocity Model: trains or quantizes
- Recorded Dataset → Sensor Calibration: supports calibration
- Recorded Dataset → Outage Simulation: provides trajectory
- Outage Simulation → Performance Evaluation: generates test outages
- Python Pipeline → Performance Evaluation: provides navigation results
- Vehicle / Sensors → Android Sensor Providers: provides live readings
- Android Sensor Providers → Navigation UI: provides sensor frames
- Navigation UI → Android DR Engine: updates navigation
- Android DR Engine → Android Mode Manager: updates mode
- Navigation UI → On-device Velocity Inference: uses inference
- Android DR Engine → Navigation UI: provides position