# dsgaming98/sih26168-idr architecture

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

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

## Overview

NavGhost is an Android, phone-only navigation app that uses inertial dead reckoning when GNSS is unavailable, then cautiously verifies GNSS recovery. Its runtime workflow is sensor/GNSS input → on-device navigation engine → live navigation and trip/map experience. The repository also contains a Python research stack for preparing Android sessions, running blackout and estimator experiments, map matching, and evaluation, plus an optional local telemetry observer. Android engine internals are excerpted; several product integrations and research modules are represented by their exact tree paths, with uncertain connections omitted.

Main entry points: [`technical-evidence/android/android/app/src/main/java/org/sih26168/idrlogger/engine/IdrEngine.kt`](https://github.com/dsgaming98/sih26168-idr/blob/main/technical-evidence/android/android/app/src/main/java/org/sih26168/idrlogger/engine/IdrEngine.kt) (IDR engine), [`research/src/idr/phase8/pipeline.py`](https://github.com/dsgaming98/sih26168-idr/blob/main/research/src/idr/phase8/pipeline.py) (Frozen runtime experiments), [`research/src/idr/phase5_pipeline.py`](https://github.com/dsgaming98/sih26168-idr/blob/main/research/src/idr/phase5_pipeline.py) (Estimator comparisons), [`technical-evidence/android/android/app/src/main/java/org/sih26168/idrlogger/ui/MainActivity.kt`](https://github.com/dsgaming98/sih26168-idr/blob/main/technical-evidence/android/android/app/src/main/java/org/sih26168/idrlogger/ui/MainActivity.kt) (Live navigation UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["On-device Navigation"]
  node_sensor_repo["Sensor capture"]
  node_gnss_repo["GNSS freshness"]
  node_sensor_conditioner["Conditioning"]
  node_idr_engine["IDR engine<br/>[IdrEngine.kt]"]
  node_ekf["Classical EKF<br/>[ClassicalEkf.kt]"]
  node_stop_gate["Stationary gate"]
  node_velocity_model["Gated velocity model"]
end

subgraph group_experience["App Experience"]
  node_live_ui["Live navigation UI<br/>[MainActivity.kt]"]
  node_map_renderers["Map renderers"]
  node_trip_recorder["Trip recording<br/>[TripRecorder.kt]"]
  node_trip_store[("Trip storage<br/>[TripDao.java]")]
  node_geomesh["GeoMesh zones"]
  node_geomesh_store[("GeoMesh storage")]
end

subgraph group_research["Research and Evaluation"]
  node_session_reader["Android session reader<br/>[android_session.py]"]
  node_canonical["Canonical adaptation<br/>[canonical.py]"]
  node_phase8["Frozen runtime experiments<br/>[pipeline.py]"]
  node_phase7["GNSS recovery experiments<br/>[pipeline.py]"]
  node_phase7_engine["Recovery state machine<br/>[engine.py]"]
  node_phase5["Estimator comparisons<br/>[phase5_pipeline.py]"]
  node_blackout["Blackout scenarios<br/>[blackout.py]"]
  node_estimators["Dead-reckoning estimators<br/>[dead_reckoning.py]"]
  node_hybrid["Hybrid estimator<br/>[hybrid_idr.py]"]
  node_ml_model["Velocity model<br/>[velocity_model.py]"]
  node_map_matching["Map matching<br/>[matcher.py]"]
  node_evaluation["Evaluation<br/>[evaluation.py]"]
end

subgraph group_observer["Local Observer"]
  node_server["Telemetry observer<br/>[app.py]"]
  node_hub["Ephemeral telemetry hub<br/>[state.py]"]
  node_dashboard["Observer dashboard<br/>[dashboard.js]"]
end

node_driver(("Phone user"))
node_sensors(("Phone sensors"))
node_gnss(("GNSS fixes"))
node_geomesh_api["GeoMesh service"]
node_telemetry_phone(("Phone telemetry"))

node_driver -.->|"uses"| node_live_ui
node_sensors -.->|"provides samples"| node_sensor_repo
node_gnss -.->|"provides fixes"| node_gnss_repo
node_sensor_repo -.->|"feeds runtime"| node_idr_engine
node_gnss_repo -.->|"supplies fixes"| node_idr_engine
node_gnss_repo -->|"checks freshness"| node_gnss_repo
node_idr_engine -->|"conditions samples"| node_sensor_conditioner
node_idr_engine -->|"updates state"| node_ekf
node_idr_engine -->|"gates motion"| node_stop_gate
node_idr_engine -->|"requests inference"| node_velocity_model
node_idr_engine -.->|"provides navigation"| node_live_ui
node_live_ui -.->|"presents maps"| node_map_renderers
node_live_ui -.->|"records trips"| node_trip_recorder
node_trip_recorder -.->|"persists trips"| node_trip_store
node_live_ui -.->|"uses zones"| node_geomesh
node_geomesh -->|"reads and writes"| node_geomesh_store
node_geomesh -.->|"syncs zones"| node_geomesh_api
node_session_reader -->|"adapts session"| node_canonical
node_phase8 -->|"uses adaptation"| node_canonical
node_phase8 -->|"runs estimators"| node_estimators
node_phase8 -->|"runs hybrid"| node_hybrid
node_phase8 -->|"uses velocity model"| node_ml_model
node_phase7 -->|"steps recovery engine"| node_phase7_engine
node_phase7_engine -.->|"consumes outage inputs"| node_blackout
node_phase5 -->|"creates scenarios"| node_blackout
node_phase5 -->|"runs dead reckoning"| node_estimators
node_phase5 -->|"runs hybrid"| node_hybrid
node_phase5 -.->|"uses model bundle"| node_ml_model
node_phase7 -->|"evaluates map matching"| node_map_matching
node_phase7 -->|"uses metrics"| node_evaluation
node_phase8 -->|"uses metrics"| node_evaluation
node_phase5 -->|"evaluates predictions"| node_evaluation
node_telemetry_phone -.->|"streams telemetry"| node_server
node_server -->|"accepts and fans out"| node_hub
node_server -.->|"serves observer"| node_dashboard

click node_sensor_repo "https://github.com/dsgaming98/sih26168-idr/blob/main/technical-evidence/android/android/app/src/main/java/org/sih26168/idrlogger/core/SensorRepository.kt"
click node_gnss_repo "https://github.com/dsgaming98/sih26168-idr/blob/main/technical-evidence/android/android/app/src/main/java/org/sih26168/idrlogger/core/GnssLocationRepository.kt"
click node_sensor_conditioner "https://github.com/dsgaming98/sih26168-idr/blob/main/technical-evidence/android/android/app/src/main/java/org/sih26168/idrlogger/engine/SensorConditioner.kt"
click node_idr_engine "https://github.com/dsgaming98/sih26168-idr/blob/main/technical-evidence/android/android/app/src/main/java/org/sih26168/idrlogger/engine/IdrEngine.kt"
click node_ekf "https://github.com/dsgaming98/sih26168-idr/blob/main/technical-evidence/android/android/app/src/main/java/org/sih26168/idrlogger/engine/ClassicalEkf.kt"
click node_stop_gate "https://github.com/dsgaming98/sih26168-idr/blob/main/technical-evidence/android/android/app/src/main/java/org/sih26168/idrlogger/engine/InertialStopGate.kt"
click node_velocity_model "https://github.com/dsgaming98/sih26168-idr/blob/main/technical-evidence/android/android/app/src/main/java/org/sih26168/idrlogger/engine/FrozenVelocityModelData.kt"
click node_live_ui "https://github.com/dsgaming98/sih26168-idr/blob/main/technical-evidence/android/android/app/src/main/java/org/sih26168/idrlogger/ui/MainActivity.kt"
click node_map_renderers "https://github.com/dsgaming98/sih26168-idr/blob/main/technical-evidence/android/android/app/src/main/java/org/sih26168/idrlogger/ui/Google3dMapSurface.kt"
click node_trip_recorder "https://github.com/dsgaming98/sih26168-idr/blob/main/technical-evidence/android/android/app/src/main/java/org/sih26168/idrlogger/product/TripRecorder.kt"
click node_trip_store "https://github.com/dsgaming98/sih26168-idr/blob/main/technical-evidence/android/android/app/src/main/java/org/sih26168/idrlogger/product/TripDao.java"
click node_geomesh "https://github.com/dsgaming98/sih26168-idr/blob/main/technical-evidence/android/android/app/src/main/java/org/sih26168/idrlogger/product/GeoMeshRepository.kt"
click node_geomesh_store "https://github.com/dsgaming98/sih26168-idr/blob/main/technical-evidence/android/android/app/src/main/java/org/sih26168/idrlogger/product/NavGhostDatabase.java"
click node_session_reader "https://github.com/dsgaming98/sih26168-idr/blob/main/research/src/idr/phase9/android_session.py"
click node_canonical "https://github.com/dsgaming98/sih26168-idr/blob/main/research/src/idr/phase8/canonical.py"
click node_phase8 "https://github.com/dsgaming98/sih26168-idr/blob/main/research/src/idr/phase8/pipeline.py"
click node_phase7 "https://github.com/dsgaming98/sih26168-idr/blob/main/research/src/idr/phase7/pipeline.py"
click node_phase7_engine "https://github.com/dsgaming98/sih26168-idr/blob/main/research/src/idr/phase7/engine.py"
click node_phase5 "https://github.com/dsgaming98/sih26168-idr/blob/main/research/src/idr/phase5_pipeline.py"
click node_blackout "https://github.com/dsgaming98/sih26168-idr/blob/main/research/src/idr/blackout.py"
click node_estimators "https://github.com/dsgaming98/sih26168-idr/blob/main/research/src/idr/dead_reckoning.py"
click node_hybrid "https://github.com/dsgaming98/sih26168-idr/blob/main/research/src/idr/hybrid/hybrid_idr.py"
click node_ml_model "https://github.com/dsgaming98/sih26168-idr/blob/main/research/src/idr/ml/velocity_model.py"
click node_map_matching "https://github.com/dsgaming98/sih26168-idr/blob/main/research/src/idr/map_matching/matcher.py"
click node_evaluation "https://github.com/dsgaming98/sih26168-idr/blob/main/research/src/idr/evaluation.py"
click node_server "https://github.com/dsgaming98/sih26168-idr/blob/main/research/server/app.py"
click node_hub "https://github.com/dsgaming98/sih26168-idr/blob/main/research/server/state.py"
click node_dashboard "https://github.com/dsgaming98/sih26168-idr/blob/main/research/server/static/dashboard.js"

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_sensor_repo,node_gnss_repo,node_sensor_conditioner,node_idr_engine,node_ekf,node_stop_gate,node_velocity_model,node_driver toneBlue
class node_live_ui,node_map_renderers,node_trip_recorder,node_trip_store,node_geomesh,node_geomesh_store toneAmber
class node_session_reader,node_canonical,node_phase8,node_phase7,node_phase7_engine,node_phase5,node_blackout,node_estimators,node_hybrid,node_ml_model,node_map_matching,node_evaluation toneMint
class node_server,node_hub,node_dashboard toneRose
class node_sensors,node_gnss,node_geomesh_api,node_telemetry_phone toneIndigo
```

## Components

### On-device Navigation

- [Sensor capture](https://github.com/dsgaming98/sih26168-idr/blob/main/technical-evidence/android/android/app/src/main/java/org/sih26168/idrlogger/core/SensorRepository.kt): `technical-evidence/android/android/app/src/main/java/org/sih26168/idrlogger/core/SensorRepository.kt`
- [GNSS freshness](https://github.com/dsgaming98/sih26168-idr/blob/main/technical-evidence/android/android/app/src/main/java/org/sih26168/idrlogger/core/GnssLocationRepository.kt): `technical-evidence/android/android/app/src/main/java/org/sih26168/idrlogger/core/GnssLocationRepository.kt`
- [Conditioning](https://github.com/dsgaming98/sih26168-idr/blob/main/technical-evidence/android/android/app/src/main/java/org/sih26168/idrlogger/engine/SensorConditioner.kt): `technical-evidence/android/android/app/src/main/java/org/sih26168/idrlogger/engine/SensorConditioner.kt`
- [IDR engine](https://github.com/dsgaming98/sih26168-idr/blob/main/technical-evidence/android/android/app/src/main/java/org/sih26168/idrlogger/engine/IdrEngine.kt): `technical-evidence/android/android/app/src/main/java/org/sih26168/idrlogger/engine/IdrEngine.kt`
- [Classical EKF](https://github.com/dsgaming98/sih26168-idr/blob/main/technical-evidence/android/android/app/src/main/java/org/sih26168/idrlogger/engine/ClassicalEkf.kt): `technical-evidence/android/android/app/src/main/java/org/sih26168/idrlogger/engine/ClassicalEkf.kt`
- [Stationary gate](https://github.com/dsgaming98/sih26168-idr/blob/main/technical-evidence/android/android/app/src/main/java/org/sih26168/idrlogger/engine/InertialStopGate.kt): `technical-evidence/android/android/app/src/main/java/org/sih26168/idrlogger/engine/InertialStopGate.kt`
- [Gated velocity model](https://github.com/dsgaming98/sih26168-idr/blob/main/technical-evidence/android/android/app/src/main/java/org/sih26168/idrlogger/engine/FrozenVelocityModelData.kt): `technical-evidence/android/android/app/src/main/java/org/sih26168/idrlogger/engine/FrozenVelocityModelData.kt`

### App Experience

- [Live navigation UI](https://github.com/dsgaming98/sih26168-idr/blob/main/technical-evidence/android/android/app/src/main/java/org/sih26168/idrlogger/ui/MainActivity.kt): `technical-evidence/android/android/app/src/main/java/org/sih26168/idrlogger/ui/MainActivity.kt`
- [Map renderers](https://github.com/dsgaming98/sih26168-idr/blob/main/technical-evidence/android/android/app/src/main/java/org/sih26168/idrlogger/ui/Google3dMapSurface.kt): `technical-evidence/android/android/app/src/main/java/org/sih26168/idrlogger/ui/Google3dMapSurface.kt`
- [Trip recording](https://github.com/dsgaming98/sih26168-idr/blob/main/technical-evidence/android/android/app/src/main/java/org/sih26168/idrlogger/product/TripRecorder.kt): `technical-evidence/android/android/app/src/main/java/org/sih26168/idrlogger/product/TripRecorder.kt`
- [Trip storage](https://github.com/dsgaming98/sih26168-idr/blob/main/technical-evidence/android/android/app/src/main/java/org/sih26168/idrlogger/product/TripDao.java): `technical-evidence/android/android/app/src/main/java/org/sih26168/idrlogger/product/TripDao.java`
- [GeoMesh zones](https://github.com/dsgaming98/sih26168-idr/blob/main/technical-evidence/android/android/app/src/main/java/org/sih26168/idrlogger/product/GeoMeshRepository.kt): `technical-evidence/android/android/app/src/main/java/org/sih26168/idrlogger/product/GeoMeshRepository.kt`
- [GeoMesh storage](https://github.com/dsgaming98/sih26168-idr/blob/main/technical-evidence/android/android/app/src/main/java/org/sih26168/idrlogger/product/NavGhostDatabase.java): `technical-evidence/android/android/app/src/main/java/org/sih26168/idrlogger/product/NavGhostDatabase.java`

### Research and Evaluation

- [Android session reader](https://github.com/dsgaming98/sih26168-idr/blob/main/research/src/idr/phase9/android_session.py): `research/src/idr/phase9/android_session.py`
- [Canonical adaptation](https://github.com/dsgaming98/sih26168-idr/blob/main/research/src/idr/phase8/canonical.py): `research/src/idr/phase8/canonical.py`
- [Frozen runtime experiments](https://github.com/dsgaming98/sih26168-idr/blob/main/research/src/idr/phase8/pipeline.py): `research/src/idr/phase8/pipeline.py`
- [GNSS recovery experiments](https://github.com/dsgaming98/sih26168-idr/blob/main/research/src/idr/phase7/pipeline.py): `research/src/idr/phase7/pipeline.py`
- [Recovery state machine](https://github.com/dsgaming98/sih26168-idr/blob/main/research/src/idr/phase7/engine.py): `research/src/idr/phase7/engine.py`
- [Estimator comparisons](https://github.com/dsgaming98/sih26168-idr/blob/main/research/src/idr/phase5_pipeline.py): `research/src/idr/phase5_pipeline.py`
- [Blackout scenarios](https://github.com/dsgaming98/sih26168-idr/blob/main/research/src/idr/blackout.py): `research/src/idr/blackout.py`
- [Dead-reckoning estimators](https://github.com/dsgaming98/sih26168-idr/blob/main/research/src/idr/dead_reckoning.py): `research/src/idr/dead_reckoning.py`
- [Hybrid estimator](https://github.com/dsgaming98/sih26168-idr/blob/main/research/src/idr/hybrid/hybrid_idr.py): `research/src/idr/hybrid/hybrid_idr.py`
- [Velocity model](https://github.com/dsgaming98/sih26168-idr/blob/main/research/src/idr/ml/velocity_model.py): `research/src/idr/ml/velocity_model.py`
- [Map matching](https://github.com/dsgaming98/sih26168-idr/blob/main/research/src/idr/map_matching/matcher.py): `research/src/idr/map_matching/matcher.py`
- [Evaluation](https://github.com/dsgaming98/sih26168-idr/blob/main/research/src/idr/evaluation.py): `research/src/idr/evaluation.py`

### Local Observer

- [Telemetry observer](https://github.com/dsgaming98/sih26168-idr/blob/main/research/server/app.py): `research/server/app.py`
- [Ephemeral telemetry hub](https://github.com/dsgaming98/sih26168-idr/blob/main/research/server/state.py): `research/server/state.py`
- [Observer dashboard](https://github.com/dsgaming98/sih26168-idr/blob/main/research/server/static/dashboard.js): `research/server/static/dashboard.js`

### Other components

- **Phone user**
- **Phone sensors**
- **GNSS fixes**
- **GeoMesh service**
- **Phone telemetry**

## Connections

- Phone user → Live navigation UI: uses (evidence: `README.md`)
- Phone sensors → Sensor capture: provides samples (evidence: `README.md`)
- GNSS fixes → GNSS freshness: provides fixes (evidence: `README.md`)
- Sensor capture → IDR engine: feeds runtime
- GNSS freshness → IDR engine: supplies fixes
- GNSS freshness → GNSS freshness: checks freshness (evidence: `technical-evidence/android/android/app/src/main/java/org/sih26168/idrlogger/core/GnssLocationRepository.kt`)
- IDR engine → Conditioning: conditions samples (evidence: `technical-evidence/android/android/app/src/main/java/org/sih26168/idrlogger/engine/IdrEngine.kt`)
- IDR engine → Classical EKF: updates state (evidence: `technical-evidence/android/android/app/src/main/java/org/sih26168/idrlogger/engine/IdrEngine.kt`)
- IDR engine → Stationary gate: gates motion (evidence: `technical-evidence/android/android/app/src/main/java/org/sih26168/idrlogger/engine/IdrEngine.kt`)
- IDR engine → Gated velocity model: requests inference (evidence: `technical-evidence/android/android/app/src/main/java/org/sih26168/idrlogger/engine/IdrEngine.kt`)
- IDR engine → Live navigation UI: provides navigation
- Live navigation UI → Map renderers: presents maps
- Live navigation UI → Trip recording: records trips
- Trip recording → Trip storage: persists trips
- Live navigation UI → GeoMesh zones: uses zones
- GeoMesh zones → GeoMesh storage: reads and writes (evidence: `technical-evidence/android/android/app/src/main/java/org/sih26168/idrlogger/product/GeoMeshRepository.kt`)
- GeoMesh zones → GeoMesh service: syncs zones
- Android session reader → Canonical adaptation: adapts session (evidence: `research/src/idr/phase9/android_session.py`)
- Frozen runtime experiments → Canonical adaptation: uses adaptation (evidence: `research/src/idr/phase8/pipeline.py`)
- Frozen runtime experiments → Dead-reckoning estimators: runs estimators (evidence: `research/src/idr/phase8/pipeline.py`)
- Frozen runtime experiments → Hybrid estimator: runs hybrid (evidence: `research/src/idr/phase8/pipeline.py`)
- Frozen runtime experiments → Velocity model: uses velocity model (evidence: `research/src/idr/phase8/pipeline.py`)
- GNSS recovery experiments → Recovery state machine: steps recovery engine (evidence: `research/src/idr/phase7/pipeline.py`)
- Recovery state machine → Blackout scenarios: consumes outage inputs
- Estimator comparisons → Blackout scenarios: creates scenarios (evidence: `research/src/idr/phase5_pipeline.py`)
- Estimator comparisons → Dead-reckoning estimators: runs dead reckoning (evidence: `research/src/idr/phase5_pipeline.py`)
- Estimator comparisons → Hybrid estimator: runs hybrid (evidence: `research/src/idr/phase5_pipeline.py`)
- Estimator comparisons → Velocity model: uses model bundle (evidence: `research/src/idr/phase5_pipeline.py`)
- GNSS recovery experiments → Map matching: evaluates map matching (evidence: `research/src/idr/phase7/pipeline.py`)
- GNSS recovery experiments → Evaluation: uses metrics (evidence: `research/src/idr/phase7/pipeline.py`)
- Frozen runtime experiments → Evaluation: uses metrics (evidence: `research/src/idr/phase8/pipeline.py`)
- Estimator comparisons → Evaluation: evaluates predictions (evidence: `research/src/idr/phase5_pipeline.py`)
- Phone telemetry → Telemetry observer: streams telemetry
- Telemetry observer → Ephemeral telemetry hub: accepts and fans out (evidence: `research/server/app.py`)
- Telemetry observer → Observer dashboard: serves observer