# ahireavadhut/majdhaar architecture

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

- Interactive diagram: https://gitdiagram.com/ahireavadhut/majdhaar
- Repository: https://github.com/ahireavadhut/majdhaar

## Overview

Aero Piston Engine Digital Twin ingests live or replayed CAN telemetry, turns frames into synchronized engine state, then combines an independent physics twin with analytical virtual sensors and a PINN observer to diagnose faults and estimate remaining useful life. The GCS presents the resulting health data; MAVLink provides an avionics downlink. Calibration, raw-data lineage, and PINN model training are supporting product capabilities. Several subsystem links are documented in the README or SOURCE INDEX rather than shown in excerpts, so uncertain runtime connections are omitted.

Main entry points: [`core/pipeline.py`](https://github.com/ahireavadhut/majdhaar/blob/main/core/pipeline.py) (Digital twin pipeline), [`core/telemetry_schema/schemas.py`](https://github.com/ahireavadhut/majdhaar/blob/main/core/telemetry_schema/schemas.py) (Telemetry schemas), [`core/telemetry/decoder.py`](https://github.com/ahireavadhut/majdhaar/blob/main/core/telemetry/decoder.py) (CAN decoder), [`core/telemetry/normalizer.py`](https://github.com/ahireavadhut/majdhaar/blob/main/core/telemetry/normalizer.py) (Telemetry normalizer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Telemetry and lineage"]
  node_decoder["CAN decoder<br/>[decoder.py]"]
  node_normalizer["Telemetry normalizer<br/>[normalizer.py]"]
  node_schema["Telemetry schemas<br/>[schemas.py]"]
  node_recorder["Raw data recorder<br/>[recorder.py]"]
  node_archive[("Run data archive")]
end

subgraph group_analysis["Twin and inference"]
  node_pipeline["Digital twin pipeline<br/>[pipeline.py]"]
  node_injector["Fault injector<br/>[fault_injector.py]"]
  node_twin["Physics twin<br/>[physics_model.py]"]
  node_virtual["Virtual sensors<br/>[estimators.py]"]
  node_observer["PINN observer<br/>[observer_engine.py]"]
end

subgraph group_health["Health and prognostics"]
  node_diagnostics["Fault diagnostics"]
  node_rul["Wiener RUL<br/>[wiener_rul.py]"]
end

subgraph group_interfaces["Operator and avionics"]
  node_gcsapi["GCS API<br/>[server.py]"]
  node_frontend["GCS console<br/>[app.js]"]
  node_mavlink["MAVLink EFI bridge<br/>[efi_status.py]"]
end

subgraph group_models["Calibration and PINN"]
  node_calibrator["Baseline calibrator<br/>[calibrator.py]"]
  node_dataset["PINN dataset<br/>[dataset.py]"]
  node_pinnmodel["PINN model<br/>[model.py]"]
end

node_engine(("Engine / CAN bus"))
node_operator(("Operator"))
node_avionics(("Avionics consumer"))

node_engine -->|"sends frames"| node_decoder
node_decoder -->|"decoded signals"| node_normalizer
node_normalizer -->|"normalized state"| node_pipeline
node_pipeline -->|"injects faults"| node_injector
node_pipeline -->|"advances model"| node_twin
node_pipeline -->|"estimates sensors"| node_virtual
node_pipeline -->|"evaluates residuals"| node_observer
node_pipeline -->|"classifies faults"| node_diagnostics
node_pipeline -->|"predicts RUL"| node_rul
node_pipeline -->|"encodes downlink"| node_mavlink
node_pipeline -->|"packages results"| node_schema
node_decoder -->|"produces frame data"| node_schema
node_normalizer -->|"builds state"| node_schema
node_recorder -->|"reads and writes"| node_archive
node_gcsapi -->|"uses pipeline"| node_pipeline
node_gcsapi -->|"uses recorder"| node_recorder
node_operator -->|"views dashboard"| node_frontend
node_frontend -->|"gets telemetry"| node_gcsapi
node_calibrator -->|"calibrates parameters"| node_twin
node_dataset -->|"loads telemetry"| node_schema
node_observer -.->|"loads trained artifact"| node_pinnmodel
node_mavlink -->|"downlinks EFI status"| node_avionics

click node_decoder "https://github.com/ahireavadhut/majdhaar/blob/main/core/telemetry/decoder.py"
click node_normalizer "https://github.com/ahireavadhut/majdhaar/blob/main/core/telemetry/normalizer.py"
click node_schema "https://github.com/ahireavadhut/majdhaar/blob/main/core/telemetry_schema/schemas.py"
click node_recorder "https://github.com/ahireavadhut/majdhaar/blob/main/core/telemetry/recorder.py"
click node_archive "https://github.com/ahireavadhut/majdhaar/tree/main/data/raw"
click node_pipeline "https://github.com/ahireavadhut/majdhaar/blob/main/core/pipeline.py"
click node_injector "https://github.com/ahireavadhut/majdhaar/blob/main/core/telemetry/fault_injector.py"
click node_twin "https://github.com/ahireavadhut/majdhaar/blob/main/core/twin_core/physics_model.py"
click node_virtual "https://github.com/ahireavadhut/majdhaar/blob/main/core/virtual_sensors/estimators.py"
click node_observer "https://github.com/ahireavadhut/majdhaar/blob/main/core/observer/observer_engine.py"
click node_diagnostics "https://github.com/ahireavadhut/majdhaar/blob/main/core/diagnostics/fault_classifier.py"
click node_rul "https://github.com/ahireavadhut/majdhaar/blob/main/core/prognostics/wiener_rul.py"
click node_calibrator "https://github.com/ahireavadhut/majdhaar/blob/main/core/twin_core/calibrator.py"
click node_dataset "https://github.com/ahireavadhut/majdhaar/blob/main/pinn/dataset.py"
click node_pinnmodel "https://github.com/ahireavadhut/majdhaar/blob/main/pinn/model.py"
click node_gcsapi "https://github.com/ahireavadhut/majdhaar/blob/main/gcs_api/server.py"
click node_frontend "https://github.com/ahireavadhut/majdhaar/blob/main/gcs_frontend/app.js"
click node_mavlink "https://github.com/ahireavadhut/majdhaar/blob/main/core/mavlink_bridge/efi_status.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_decoder,node_normalizer,node_schema,node_recorder,node_archive toneBlue
class node_pipeline,node_injector,node_twin,node_virtual,node_observer toneAmber
class node_diagnostics,node_rul toneMint
class node_gcsapi,node_frontend,node_mavlink toneRose
class node_calibrator,node_dataset,node_pinnmodel,node_engine,node_operator,node_avionics toneIndigo
```

## Components

### Telemetry and lineage

- [CAN decoder](https://github.com/ahireavadhut/majdhaar/blob/main/core/telemetry/decoder.py): `core/telemetry/decoder.py`
- [Telemetry normalizer](https://github.com/ahireavadhut/majdhaar/blob/main/core/telemetry/normalizer.py): `core/telemetry/normalizer.py`
- [Telemetry schemas](https://github.com/ahireavadhut/majdhaar/blob/main/core/telemetry_schema/schemas.py): `core/telemetry_schema/schemas.py`
- [Raw data recorder](https://github.com/ahireavadhut/majdhaar/blob/main/core/telemetry/recorder.py): `core/telemetry/recorder.py`
- [Run data archive](https://github.com/ahireavadhut/majdhaar/tree/main/data/raw): `data/raw`

### Twin and inference

- [Digital twin pipeline](https://github.com/ahireavadhut/majdhaar/blob/main/core/pipeline.py): `core/pipeline.py`
- [Fault injector](https://github.com/ahireavadhut/majdhaar/blob/main/core/telemetry/fault_injector.py): `core/telemetry/fault_injector.py`
- [Physics twin](https://github.com/ahireavadhut/majdhaar/blob/main/core/twin_core/physics_model.py): `core/twin_core/physics_model.py`
- [Virtual sensors](https://github.com/ahireavadhut/majdhaar/blob/main/core/virtual_sensors/estimators.py): `core/virtual_sensors/estimators.py`
- [PINN observer](https://github.com/ahireavadhut/majdhaar/blob/main/core/observer/observer_engine.py): `core/observer/observer_engine.py`

### Health and prognostics

- [Fault diagnostics](https://github.com/ahireavadhut/majdhaar/blob/main/core/diagnostics/fault_classifier.py): `core/diagnostics/fault_classifier.py`
- [Wiener RUL](https://github.com/ahireavadhut/majdhaar/blob/main/core/prognostics/wiener_rul.py): `core/prognostics/wiener_rul.py`

### Operator and avionics

- [GCS API](https://github.com/ahireavadhut/majdhaar/blob/main/gcs_api/server.py): `gcs_api/server.py`
- [GCS console](https://github.com/ahireavadhut/majdhaar/blob/main/gcs_frontend/app.js): `gcs_frontend/app.js`
- [MAVLink EFI bridge](https://github.com/ahireavadhut/majdhaar/blob/main/core/mavlink_bridge/efi_status.py): `core/mavlink_bridge/efi_status.py`

### Calibration and PINN

- [Baseline calibrator](https://github.com/ahireavadhut/majdhaar/blob/main/core/twin_core/calibrator.py): `core/twin_core/calibrator.py`
- [PINN dataset](https://github.com/ahireavadhut/majdhaar/blob/main/pinn/dataset.py): `pinn/dataset.py`
- [PINN model](https://github.com/ahireavadhut/majdhaar/blob/main/pinn/model.py): `pinn/model.py`

### Other components

- **Engine / CAN bus**
- **Operator**
- **Avionics consumer**

## Connections

- Engine / CAN bus → CAN decoder: sends frames (evidence: `README.md`)
- CAN decoder → Telemetry normalizer: decoded signals (evidence: `core/pipeline.py`)
- Telemetry normalizer → Digital twin pipeline: normalized state (evidence: `core/pipeline.py`)
- Digital twin pipeline → Fault injector: injects faults (evidence: `core/pipeline.py`)
- Digital twin pipeline → Physics twin: advances model (evidence: `core/pipeline.py`)
- Digital twin pipeline → Virtual sensors: estimates sensors (evidence: `core/pipeline.py`)
- Digital twin pipeline → PINN observer: evaluates residuals (evidence: `core/pipeline.py`)
- Digital twin pipeline → Fault diagnostics: classifies faults (evidence: `core/pipeline.py`)
- Digital twin pipeline → Wiener RUL: predicts RUL (evidence: `core/pipeline.py`)
- Digital twin pipeline → MAVLink EFI bridge: encodes downlink (evidence: `core/pipeline.py`)
- Digital twin pipeline → Telemetry schemas: packages results (evidence: `core/pipeline.py`)
- CAN decoder → Telemetry schemas: produces frame data (evidence: `core/telemetry/decoder.py`)
- Telemetry normalizer → Telemetry schemas: builds state (evidence: `core/telemetry/normalizer.py`)
- Raw data recorder → Run data archive: reads and writes (evidence: `core/telemetry/recorder.py`)
- GCS API → Digital twin pipeline: uses pipeline (evidence: `gcs_api/server.py`)
- GCS API → Raw data recorder: uses recorder (evidence: `gcs_api/server.py`)
- Operator → GCS console: views dashboard (evidence: `README.md`)
- GCS console → GCS API: gets telemetry (evidence: `README.md`)
- Baseline calibrator → Physics twin: calibrates parameters (evidence: `core/twin_core/calibrator.py`)
- PINN dataset → Telemetry schemas: loads telemetry (evidence: `pinn/dataset.py`)
- PINN observer → PINN model: loads trained artifact
- MAVLink EFI bridge → Avionics consumer: downlinks EFI status (evidence: `README.md`)
