# alveeerahman/opencarmind architecture

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

- Interactive diagram: https://gitdiagram.com/alveeerahman/opencarmind
- Repository: https://github.com/alveeerahman/opencarmind

## Overview

OpenCarMind is ESP32-based OBD-II logging and dashboard firmware, with an optional desktop companion for setup and session import. The main workflow is adapter connection, vehicle-data acquisition, on-device inference and drive logging, then local viewing or transfer to the desktop app. The graph preserves the documented R.E.V/E.V models, diagnostics, EdgeOS scheduling and safety, battery/radio services, and board UI. Firmware relationships beyond the excerpts are limited to README-documented flows; desktop USB authentication and network receiving are evidenced in source excerpts.

Main entry points: [`main/elm327.c`](https://github.com/alveeerahman/opencarmind/blob/main/main/elm327.c) (OBD polling), [`main/sdlog.c`](https://github.com/alveeerahman/opencarmind/blob/main/main/sdlog.c) (Drive sessions), [`desktop/app/src-tauri/src/board.rs`](https://github.com/alveeerahman/opencarmind/blob/main/desktop/app/src-tauri/src/board.rs) (USB board client), [`main/ml_infer.cpp`](https://github.com/alveeerahman/opencarmind/blob/main/main/ml_infer.cpp) (On-device inference)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_vehicle["Vehicle data"]
  node_ble["Adapter connection<br/>[obd_ble.c]"]
  node_obd["OBD polling<br/>[elm327.c]"]
  node_live["Live dashboard<br/>[econ.c]"]
  node_logger["Drive sessions<br/>[sdlog.c]"]
  node_nand[("NAND drive store<br/>[nand_store.c]")]
end

subgraph group_intelligence["Models and diagnostics"]
  node_inference["On-device inference<br/>[ml_infer.cpp]"]
  node_rev["R.E.V learning<br/>[rev_task.c]"]
  node_faults["Fault analysis<br/>[fault_engine.c]"]
  node_battery["Battery AI services<br/>[ai_svc.c]"]
end

subgraph group_platform["EdgeOS platform"]
  node_scheduler["Deadline scheduler<br/>[os.c]"]
  node_admission["Model admission<br/>[os_core.c]"]
  node_safety["Safety controls<br/>[stop_core.c]"]
  node_wifi["Wi-Fi sync<br/>[wifi_sync.c]"]
  node_usb["Authenticated USB door<br/>[usb_door.c]"]
end

subgraph group_experience["Board experience"]
  node_health["Health app<br/>[health_view.c]"]
  node_display["Board UI<br/>[mosaico_display.c]"]
  node_apps["Touch apps<br/>[mosaico_apps.c]"]
end

subgraph group_desktop["Desktop companion"]
  node_desktopui["Desktop interface<br/>[app.js]"]
  node_boardclient["USB board client<br/>[board.rs]"]
  node_receiver[("Session receiver<br/>[receiver.rs]")]
end

node_driver(("Driver"))
node_adapter{{"Bluetooth OBD adapter"}}
node_computer(("Owner computer"))

node_driver -->|"drives with"| node_adapter
node_adapter -->|"connects over Bluetooth"| node_ble
node_ble -->|"provides vehicle link"| node_obd
node_obd -->|"feeds dashboard"| node_live
node_obd -->|"records data"| node_logger
node_obd -->|"feeds model"| node_inference
node_inference -->|"logs model output"| node_logger
node_rev -->|"updates model"| node_inference
node_logger -->|"stores sessions"| node_nand
node_obd -->|"analyzes trouble codes"| node_faults
node_battery -->|"reports battery health"| node_health
node_scheduler -->|"admits model jobs"| node_admission
node_scheduler -->|"steps down workload"| node_safety
node_wifi -->|"syncs sessions"| node_computer
node_driver -->|"uses touch UI"| node_display
node_apps -->|"renders apps"| node_display
node_driver -->|"configures board"| node_desktopui
node_desktopui -.->|"invokes board actions"| node_boardclient
node_boardclient -->|"authenticates and transfers"| node_usb
node_usb -->|"exports session files"| node_logger
node_boardclient -->|"imports sessions"| node_computer
node_wifi -->|"uploads sessions"| node_receiver
node_receiver -->|"stores per-board files"| node_computer

click node_ble "https://github.com/alveeerahman/opencarmind/blob/main/main/obd_ble.c"
click node_obd "https://github.com/alveeerahman/opencarmind/blob/main/main/elm327.c"
click node_live "https://github.com/alveeerahman/opencarmind/blob/main/main/econ.c"
click node_logger "https://github.com/alveeerahman/opencarmind/blob/main/main/sdlog.c"
click node_nand "https://github.com/alveeerahman/opencarmind/blob/main/main/nand_store.c"
click node_inference "https://github.com/alveeerahman/opencarmind/blob/main/main/ml_infer.cpp"
click node_rev "https://github.com/alveeerahman/opencarmind/blob/main/main/rev_task.c"
click node_faults "https://github.com/alveeerahman/opencarmind/blob/main/main/fault_engine.c"
click node_battery "https://github.com/alveeerahman/opencarmind/blob/main/main/ai_svc.c"
click node_scheduler "https://github.com/alveeerahman/opencarmind/blob/main/main/os.c"
click node_admission "https://github.com/alveeerahman/opencarmind/blob/main/main/os_core.c"
click node_safety "https://github.com/alveeerahman/opencarmind/blob/main/main/stop_core.c"
click node_wifi "https://github.com/alveeerahman/opencarmind/blob/main/main/wifi_sync.c"
click node_health "https://github.com/alveeerahman/opencarmind/blob/main/main/health_view.c"
click node_display "https://github.com/alveeerahman/opencarmind/blob/main/main/mosaico_display.c"
click node_apps "https://github.com/alveeerahman/opencarmind/blob/main/main/mosaico_apps.c"
click node_usb "https://github.com/alveeerahman/opencarmind/blob/main/main/usb_door.c"
click node_desktopui "https://github.com/alveeerahman/opencarmind/blob/main/desktop/app/ui/app.js"
click node_boardclient "https://github.com/alveeerahman/opencarmind/blob/main/desktop/app/src-tauri/src/board.rs"
click node_receiver "https://github.com/alveeerahman/opencarmind/blob/main/desktop/app/src-tauri/src/receiver.rs"

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_ble,node_obd,node_live,node_logger,node_nand toneBlue
class node_inference,node_rev,node_faults,node_battery toneAmber
class node_scheduler,node_admission,node_safety,node_wifi,node_usb toneMint
class node_health,node_display,node_apps toneRose
class node_desktopui,node_boardclient,node_receiver,node_driver,node_adapter,node_computer toneIndigo
```

## Components

### Vehicle data

- [Adapter connection](https://github.com/alveeerahman/opencarmind/blob/main/main/obd_ble.c): `main/obd_ble.c`
- [OBD polling](https://github.com/alveeerahman/opencarmind/blob/main/main/elm327.c): `main/elm327.c`
- [Live dashboard](https://github.com/alveeerahman/opencarmind/blob/main/main/econ.c): `main/econ.c`
- [Drive sessions](https://github.com/alveeerahman/opencarmind/blob/main/main/sdlog.c): `main/sdlog.c`
- [NAND drive store](https://github.com/alveeerahman/opencarmind/blob/main/main/nand_store.c): `main/nand_store.c`

### Models and diagnostics

- [On-device inference](https://github.com/alveeerahman/opencarmind/blob/main/main/ml_infer.cpp): `main/ml_infer.cpp`
- [R.E.V learning](https://github.com/alveeerahman/opencarmind/blob/main/main/rev_task.c): `main/rev_task.c`
- [Fault analysis](https://github.com/alveeerahman/opencarmind/blob/main/main/fault_engine.c): `main/fault_engine.c`
- [Battery AI services](https://github.com/alveeerahman/opencarmind/blob/main/main/ai_svc.c): `main/ai_svc.c`

### EdgeOS platform

- [Deadline scheduler](https://github.com/alveeerahman/opencarmind/blob/main/main/os.c): `main/os.c`
- [Model admission](https://github.com/alveeerahman/opencarmind/blob/main/main/os_core.c): `main/os_core.c`
- [Safety controls](https://github.com/alveeerahman/opencarmind/blob/main/main/stop_core.c): `main/stop_core.c`
- [Wi-Fi sync](https://github.com/alveeerahman/opencarmind/blob/main/main/wifi_sync.c): `main/wifi_sync.c`
- [Authenticated USB door](https://github.com/alveeerahman/opencarmind/blob/main/main/usb_door.c): `main/usb_door.c`

### Board experience

- [Health app](https://github.com/alveeerahman/opencarmind/blob/main/main/health_view.c): `main/health_view.c`
- [Board UI](https://github.com/alveeerahman/opencarmind/blob/main/main/mosaico_display.c): `main/mosaico_display.c`
- [Touch apps](https://github.com/alveeerahman/opencarmind/blob/main/main/mosaico_apps.c): `main/mosaico_apps.c`

### Desktop companion

- [Desktop interface](https://github.com/alveeerahman/opencarmind/blob/main/desktop/app/ui/app.js): `desktop/app/ui/app.js`
- [USB board client](https://github.com/alveeerahman/opencarmind/blob/main/desktop/app/src-tauri/src/board.rs): `desktop/app/src-tauri/src/board.rs`
- [Session receiver](https://github.com/alveeerahman/opencarmind/blob/main/desktop/app/src-tauri/src/receiver.rs): `desktop/app/src-tauri/src/receiver.rs`

### Other components

- **Driver**
- **Bluetooth OBD adapter**
- **Owner computer**

## Connections

- Driver → Bluetooth OBD adapter: drives with (evidence: `README.md`)
- Bluetooth OBD adapter → Adapter connection: connects over Bluetooth (evidence: `README.md`)
- Adapter connection → OBD polling: provides vehicle link (evidence: `README.md`)
- OBD polling → Live dashboard: feeds dashboard (evidence: `README.md`)
- OBD polling → Drive sessions: records data (evidence: `README.md`)
- OBD polling → On-device inference: feeds model (evidence: `README.md`)
- On-device inference → Drive sessions: logs model output (evidence: `README.md`)
- R.E.V learning → On-device inference: updates model (evidence: `README.md`)
- Drive sessions → NAND drive store: stores sessions (evidence: `README.md`)
- OBD polling → Fault analysis: analyzes trouble codes (evidence: `README.md`)
- Battery AI services → Health app: reports battery health (evidence: `README.md`)
- Deadline scheduler → Model admission: admits model jobs (evidence: `README.md`)
- Deadline scheduler → Safety controls: steps down workload (evidence: `README.md`)
- Wi-Fi sync → Owner computer: syncs sessions (evidence: `README.md`)
- Driver → Board UI: uses touch UI (evidence: `README.md`)
- Touch apps → Board UI: renders apps (evidence: `main/mosaico_apps.c`)
- Driver → Desktop interface: configures board (evidence: `README.md`)
- Desktop interface → USB board client: invokes board actions
- USB board client → Authenticated USB door: authenticates and transfers (evidence: `desktop/app/src-tauri/src/board.rs`)
- Authenticated USB door → Drive sessions: exports session files (evidence: `README.md`)
- USB board client → Owner computer: imports sessions (evidence: `desktop/app/src-tauri/src/board.rs`)
- Wi-Fi sync → Session receiver: uploads sessions (evidence: `README.md`)
- Session receiver → Owner computer: stores per-board files (evidence: `desktop/app/src-tauri/src/receiver.rs`)
