# difluoroethane/clew_idr architecture

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

- Interactive diagram: https://gitdiagram.com/difluoroethane/clew_idr
- Repository: https://github.com/difluoroethane/clew_idr

## Overview

CLEW-IDR is a phone/edge GNSS-denied vehicle-navigation engine. Its documented runtime flow calibrates and preprocesses sensor streams, estimates motion and adaptive constraints with a shared multi-task encoder, fuses measurements in a UKF, applies road/lane map matching and GNSS-state logic, then emits navigation state. The sampled pipeline confirms model-to-UKF and UKF-to-matcher calls; several calibration, state-machine, and deployment links are documented in the README but not shown in sampled implementation excerpts.

Main entry points: [`src/pipeline.py`](https://github.com/difluoroethane/clew_idr/blob/main/src/pipeline.py) (Pipeline step), [`src/models/shared_encoder.py`](https://github.com/difluoroethane/clew_idr/blob/main/src/models/shared_encoder.py) (Multi-task model), [`src/maps/hmm.py`](https://github.com/difluoroethane/clew_idr/blob/main/src/maps/hmm.py) (HMM matcher), [`src/filters/ukf.py`](https://github.com/difluoroethane/clew_idr/blob/main/src/filters/ukf.py) (15-state UKF)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sensing["Input and preprocessing"]
  node_calibration["Dynamic calibration"]
  node_preprocess["Window preparation<br/>[pipeline.py]"]
  node_schema["Stream schema<br/>[schema.py]"]
  node_csv_loader["Dataset loader<br/>[loader.py]"]
end

subgraph group_learning["Learned estimation"]
  node_shared_model["Multi-task model<br/>[shared_encoder.py]"]
  node_tcn["Causal TCN<br/>[tcn.py]"]
  node_speed["Speed estimate<br/>[heads.py]"]
  node_noise["Adaptive noise<br/>[adaptive_noise.py]"]
end

subgraph group_fusion["Navigation fusion"]
  node_ukf["15-state UKF<br/>[ukf.py]"]
  node_mechanization["Inertial mechanization<br/>[mechanization.py]"]
  node_physical_constraints["Motion constraints<br/>[constraints.py]"]
  node_barometer["Barometer updates<br/>[barometer.py]"]
end

subgraph group_maps["Road constraints"]
  node_road_data["OpenStreetMap roads<br/>[osm_loader.py]"]
  node_road_graph[("Road graph<br/>[road_graph.py]")]
  node_candidates["Road candidates<br/>[map_match.py]"]
  node_hmm["HMM matcher<br/>[hmm.py]"]
  node_hmm_match["Trajectory matcher<br/>[hmm_match.py]"]
  node_lateral["Lateral deviation"]
end

subgraph group_states["State and output"]
  node_gnss_state["GNSS state machine<br/>[gnss_deficit.py]"]
  node_lane_tracker["Lane-index tracker"]
  node_pipeline["Pipeline step<br/>[pipeline.py]"]
  node_navigation_result["Navigation state<br/>[pipeline.py]"]
end

node_phone(("Phone sensors"))
node_external_imu(("External IMU"))
node_mobile(("Mobile application"))
node_edge(("Edge engine"))

node_phone -.->|"supplies sensors"| node_calibration
node_external_imu -.->|"supplies IMU"| node_calibration
node_calibration -.->|"corrects samples"| node_preprocess
node_csv_loader -->|"maps columns"| node_schema
node_preprocess -.->|"forms windows"| node_shared_model
node_shared_model -->|"uses blocks"| node_tcn
node_shared_model -.->|"produces heads"| node_speed
node_pipeline -->|"infers outputs"| node_shared_model
node_pipeline -->|"predicts and updates"| node_ukf
node_pipeline -->|"applies multipliers"| node_noise
node_pipeline -->|"matches position"| node_hmm
node_ukf -.->|"integrates motion"| node_mechanization
node_ukf -.->|"applies constraints"| node_physical_constraints
node_phone -.->|"provides measurements"| node_ukf
node_phone -.->|"provides pressure"| node_barometer
node_barometer -->|"passes altitude"| node_pipeline
node_road_data -.->|"builds network"| node_road_graph
node_road_graph -->|"queries edges"| node_candidates
node_candidates -->|"supplies candidates"| node_hmm_match
node_hmm_match -->|"reads connectivity"| node_road_graph
node_hmm -->|"computes emissions"| node_lateral
node_hmm -->|"uses candidates"| node_candidates
node_hmm -.->|"provides match confidence"| node_gnss_state
node_shared_model -.->|"provides motion flags"| node_gnss_state
node_shared_model -.->|"provides lane events"| node_lane_tracker
node_gnss_state -.->|"selects navigation mode"| node_pipeline
node_pipeline -->|"returns state"| node_navigation_result
node_navigation_result -.->|"drives output"| node_mobile
node_navigation_result -.->|"drives output"| node_edge

click node_calibration "https://github.com/difluoroethane/clew_idr/tree/main/src"
click node_preprocess "https://github.com/difluoroethane/clew_idr/blob/main/src/preprocessing/pipeline.py"
click node_schema "https://github.com/difluoroethane/clew_idr/blob/main/src/preprocessing/schema.py"
click node_csv_loader "https://github.com/difluoroethane/clew_idr/blob/main/src/preprocessing/loader.py"
click node_shared_model "https://github.com/difluoroethane/clew_idr/blob/main/src/models/shared_encoder.py"
click node_tcn "https://github.com/difluoroethane/clew_idr/blob/main/src/models/tcn.py"
click node_speed "https://github.com/difluoroethane/clew_idr/blob/main/src/models/heads.py"
click node_noise "https://github.com/difluoroethane/clew_idr/blob/main/src/filters/adaptive_noise.py"
click node_ukf "https://github.com/difluoroethane/clew_idr/blob/main/src/filters/ukf.py"
click node_mechanization "https://github.com/difluoroethane/clew_idr/blob/main/src/filters/mechanization.py"
click node_physical_constraints "https://github.com/difluoroethane/clew_idr/blob/main/src/filters/constraints.py"
click node_barometer "https://github.com/difluoroethane/clew_idr/blob/main/src/barometer.py"
click node_road_data "https://github.com/difluoroethane/clew_idr/blob/main/src/maps/osm_loader.py"
click node_road_graph "https://github.com/difluoroethane/clew_idr/blob/main/src/maps/road_graph.py"
click node_candidates "https://github.com/difluoroethane/clew_idr/blob/main/src/maps/map_match.py"
click node_hmm "https://github.com/difluoroethane/clew_idr/blob/main/src/maps/hmm.py"
click node_hmm_match "https://github.com/difluoroethane/clew_idr/blob/main/src/maps/hmm_match.py"
click node_lateral "https://github.com/difluoroethane/clew_idr/blob/main/src/maps/lateral_deviation.py"
click node_gnss_state "https://github.com/difluoroethane/clew_idr/blob/main/src/statemachine/gnss_deficit.py"
click node_lane_tracker "https://github.com/difluoroethane/clew_idr/tree/main/src/maps"
click node_pipeline "https://github.com/difluoroethane/clew_idr/blob/main/src/pipeline.py"
click node_navigation_result "https://github.com/difluoroethane/clew_idr/blob/main/src/pipeline.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_calibration,node_preprocess,node_schema,node_csv_loader toneBlue
class node_shared_model,node_tcn,node_speed,node_noise toneAmber
class node_ukf,node_mechanization,node_physical_constraints,node_barometer toneMint
class node_road_data,node_road_graph,node_candidates,node_hmm,node_hmm_match,node_lateral toneRose
class node_gnss_state,node_lane_tracker,node_pipeline,node_navigation_result,node_phone,node_external_imu,node_mobile,node_edge toneIndigo
```

## Components

### Input and preprocessing

- [Dynamic calibration](https://github.com/difluoroethane/clew_idr/tree/main/src): `src`
- [Window preparation](https://github.com/difluoroethane/clew_idr/blob/main/src/preprocessing/pipeline.py): `src/preprocessing/pipeline.py`
- [Stream schema](https://github.com/difluoroethane/clew_idr/blob/main/src/preprocessing/schema.py): `src/preprocessing/schema.py`
- [Dataset loader](https://github.com/difluoroethane/clew_idr/blob/main/src/preprocessing/loader.py): `src/preprocessing/loader.py`

### Learned estimation

- [Multi-task model](https://github.com/difluoroethane/clew_idr/blob/main/src/models/shared_encoder.py): `src/models/shared_encoder.py`
- [Causal TCN](https://github.com/difluoroethane/clew_idr/blob/main/src/models/tcn.py): `src/models/tcn.py`
- [Speed estimate](https://github.com/difluoroethane/clew_idr/blob/main/src/models/heads.py): `src/models/heads.py`
- [Adaptive noise](https://github.com/difluoroethane/clew_idr/blob/main/src/filters/adaptive_noise.py): `src/filters/adaptive_noise.py`

### Navigation fusion

- [15-state UKF](https://github.com/difluoroethane/clew_idr/blob/main/src/filters/ukf.py): `src/filters/ukf.py`
- [Inertial mechanization](https://github.com/difluoroethane/clew_idr/blob/main/src/filters/mechanization.py): `src/filters/mechanization.py`
- [Motion constraints](https://github.com/difluoroethane/clew_idr/blob/main/src/filters/constraints.py): `src/filters/constraints.py`
- [Barometer updates](https://github.com/difluoroethane/clew_idr/blob/main/src/barometer.py): `src/barometer.py`

### Road constraints

- [OpenStreetMap roads](https://github.com/difluoroethane/clew_idr/blob/main/src/maps/osm_loader.py): `src/maps/osm_loader.py`
- [Road graph](https://github.com/difluoroethane/clew_idr/blob/main/src/maps/road_graph.py): `src/maps/road_graph.py`
- [Road candidates](https://github.com/difluoroethane/clew_idr/blob/main/src/maps/map_match.py): `src/maps/map_match.py`
- [HMM matcher](https://github.com/difluoroethane/clew_idr/blob/main/src/maps/hmm.py): `src/maps/hmm.py`
- [Trajectory matcher](https://github.com/difluoroethane/clew_idr/blob/main/src/maps/hmm_match.py): `src/maps/hmm_match.py`
- [Lateral deviation](https://github.com/difluoroethane/clew_idr/blob/main/src/maps/lateral_deviation.py): `src/maps/lateral_deviation.py`

### State and output

- [GNSS state machine](https://github.com/difluoroethane/clew_idr/blob/main/src/statemachine/gnss_deficit.py): `src/statemachine/gnss_deficit.py`
- [Lane-index tracker](https://github.com/difluoroethane/clew_idr/tree/main/src/maps): `src/maps`
- [Pipeline step](https://github.com/difluoroethane/clew_idr/blob/main/src/pipeline.py): `src/pipeline.py`
- [Navigation state](https://github.com/difluoroethane/clew_idr/blob/main/src/pipeline.py): `src/pipeline.py`

### Other components

- **Phone sensors**
- **External IMU**
- **Mobile application**
- **Edge engine**

## Connections

- Phone sensors → Dynamic calibration: supplies sensors (evidence: `README.md`)
- External IMU → Dynamic calibration: supplies IMU (evidence: `README.md`)
- Dynamic calibration → Window preparation: corrects samples (evidence: `README.md`)
- Dataset loader → Stream schema: maps columns (evidence: `src/preprocessing/loader.py`)
- Window preparation → Multi-task model: forms windows (evidence: `README.md`)
- Multi-task model → Causal TCN: uses blocks (evidence: `src/models/shared_encoder.py`)
- Multi-task model → Speed estimate: produces heads (evidence: `README.md`)
- Pipeline step → Multi-task model: infers outputs (evidence: `src/pipeline.py`)
- Pipeline step → 15-state UKF: predicts and updates (evidence: `src/pipeline.py`)
- Pipeline step → Adaptive noise: applies multipliers (evidence: `src/pipeline.py`)
- Pipeline step → HMM matcher: matches position (evidence: `src/pipeline.py`)
- 15-state UKF → Inertial mechanization: integrates motion
- 15-state UKF → Motion constraints: applies constraints
- Phone sensors → 15-state UKF: provides measurements (evidence: `README.md`)
- Phone sensors → Barometer updates: provides pressure (evidence: `README.md`)
- Barometer updates → Pipeline step: passes altitude (evidence: `src/pipeline.py`)
- OpenStreetMap roads → Road graph: builds network (evidence: `src/maps/road_graph.py`)
- Road graph → Road candidates: queries edges (evidence: `src/maps/map_match.py`)
- Road candidates → Trajectory matcher: supplies candidates (evidence: `src/maps/hmm_match.py`)
- Trajectory matcher → Road graph: reads connectivity (evidence: `src/maps/hmm_match.py`)
- HMM matcher → Lateral deviation: computes emissions (evidence: `src/maps/hmm.py`)
- HMM matcher → Road candidates: uses candidates (evidence: `src/maps/hmm.py`)
- HMM matcher → GNSS state machine: provides match confidence (evidence: `README.md`)
- Multi-task model → GNSS state machine: provides motion flags (evidence: `README.md`)
- Multi-task model → Lane-index tracker: provides lane events (evidence: `README.md`)
- GNSS state machine → Pipeline step: selects navigation mode (evidence: `README.md`)
- Pipeline step → Navigation state: returns state (evidence: `src/pipeline.py`)
- Navigation state → Mobile application: drives output (evidence: `README.md`)
- Navigation state → Edge engine: drives output (evidence: `README.md`)