# provrb/obdium architecture

> Architecture diagram of the GitHub repository provrb/obdium, 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/provrb/obdium
- Repository: https://github.com/provrb/obdium

## Overview

OBDium is a desktop vehicle-diagnostics application. The user connects through the GUI to an ELM327 adapter, after which the backend requests and decodes live OBD-II data for dashboard metrics, graphs, trouble codes, and readiness tests; users can also decode a VIN offline. The graph includes documented capabilities whose detailed wiring was not sampled, such as custom PIDs, settings, and demo replay. Source excerpts are partial, so uncertain internal call paths are omitted.

Main entry points: [`frontend/scripts/main.js`](https://github.com/provrb/obdium/blob/main/frontend/scripts/main.js) (Dashboard UI), [`backend/src/bridge/events.rs`](https://github.com/provrb/obdium/blob/main/backend/src/bridge/events.rs) (Event handlers), [`backend/src/obd.rs`](https://github.com/provrb/obdium/blob/main/backend/src/obd.rs) (OBD connection), [`backend/src/stats.rs`](https://github.com/provrb/obdium/blob/main/backend/src/stats.rs) (Metric tracking)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Desktop interface"]
  node_gui["Dashboard UI<br/>[main.js]"]
  node_features["UI features<br/>[features.js]"]
  node_settings["Preferences<br/>[settings.js]"]
  node_vin_input["VIN entry<br/>[main.js]"]
end

subgraph group_bridge["Application bridge"]
  node_bridge_events["Event handlers<br/>[events.rs]"]
  node_bridge_state["Connection state<br/>[mod.rs]"]
  node_runtime["App runtime<br/>[main.rs]"]
  node_tracking["Metric tracking<br/>[stats.rs]"]
  node_vin_bridge["VIN request handler<br/>[events.rs]"]
end

subgraph group_obd["OBD diagnostics"]
  node_obd_core["OBD connection<br/>[obd.rs]"]
  node_pid_decode["Live PID decoding<br/>[engine.rs]"]
  node_response["Response decoding<br/>[response.rs]"]
  node_pid_catalog["PID catalog<br/>[dicts.rs]"]
  node_diagnostics["Codes and readiness<br/>[diagnostics.rs]"]
  node_custom_pid["Custom PIDs<br/>[events.rs]"]
  node_replay["Demo replay<br/>[replay.rs]"]
end

subgraph group_vin["VIN decoding"]
  node_vin_parser["VIN parser<br/>[parser.rs]"]
  node_vin_lookup["VPIC lookups<br/>[attributes.rs]"]
end

subgraph group_local["Offline data"]
  node_dtc_db[("Code descriptions")]
  node_vpic_db[("VPIC database<br/>[vpic.sqlite.xz]")]
  node_requests["Recorded requests<br/>[requests.json]"]
end

node_user(("Driver"))
node_adapter["ELM327 adapter"]

node_user -->|"uses"| node_gui
node_gui -->|"emits events"| node_bridge_events
node_bridge_events -->|"starts tracking"| node_runtime
node_bridge_events -->|"stores connection"| node_bridge_state
node_bridge_events -->|"connects and queries"| node_obd_core
node_obd_core -->|"sends commands"| node_adapter
node_obd_core -->|"queries PIDs"| node_pid_decode
node_pid_decode -->|"decodes responses"| node_response
node_runtime -->|"runs polling"| node_tracking
node_tracking -->|"requests metrics"| node_obd_core
node_tracking -->|"emits updates"| node_gui
node_gui -->|"requests codes and tests"| node_diagnostics
node_diagnostics -->|"reads descriptions"| node_dtc_db
node_gui -->|"displays PID list"| node_pid_catalog
node_gui -->|"submits custom PID"| node_custom_pid
node_gui -->|"saves preferences"| node_settings
node_vin_input -->|"requests decoding"| node_vin_bridge
node_vin_bridge -->|"parses VIN"| node_vin_parser
node_vin_parser -->|"looks up attributes"| node_vin_lookup
node_vin_lookup -->|"queries database"| node_vpic_db
node_gui -.->|"selects demo mode"| node_replay
node_replay -->|"reads recordings"| node_requests

click node_gui "https://github.com/provrb/obdium/blob/main/frontend/scripts/main.js"
click node_features "https://github.com/provrb/obdium/blob/main/frontend/scripts/features.js"
click node_settings "https://github.com/provrb/obdium/blob/main/frontend/scripts/settings.js"
click node_bridge_events "https://github.com/provrb/obdium/blob/main/backend/src/bridge/events.rs"
click node_bridge_state "https://github.com/provrb/obdium/blob/main/backend/src/bridge/mod.rs"
click node_runtime "https://github.com/provrb/obdium/blob/main/backend/src/main.rs"
click node_obd_core "https://github.com/provrb/obdium/blob/main/backend/src/obd.rs"
click node_pid_decode "https://github.com/provrb/obdium/blob/main/backend/src/pid/engine.rs"
click node_response "https://github.com/provrb/obdium/blob/main/backend/src/response.rs"
click node_tracking "https://github.com/provrb/obdium/blob/main/backend/src/stats.rs"
click node_pid_catalog "https://github.com/provrb/obdium/blob/main/backend/src/dicts.rs"
click node_diagnostics "https://github.com/provrb/obdium/blob/main/backend/src/pid/diagnostics.rs"
click node_dtc_db "https://github.com/provrb/obdium/blob/main/backend/data/code-descriptions.sqlite"
click node_custom_pid "https://github.com/provrb/obdium/blob/main/backend/src/bridge/events.rs"
click node_vin_input "https://github.com/provrb/obdium/blob/main/frontend/scripts/main.js"
click node_vin_bridge "https://github.com/provrb/obdium/blob/main/backend/src/bridge/events.rs"
click node_vin_parser "https://github.com/provrb/obdium/blob/main/backend/src/vin/parser.rs"
click node_vin_lookup "https://github.com/provrb/obdium/blob/main/backend/src/vin/attributes.rs"
click node_vpic_db "https://github.com/provrb/obdium/blob/main/backend/data/vpic.sqlite.xz"
click node_replay "https://github.com/provrb/obdium/blob/main/backend/src/replay.rs"
click node_requests "https://github.com/provrb/obdium/blob/main/backend/data/requests.json"

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_gui,node_features,node_settings,node_vin_input toneBlue
class node_bridge_events,node_bridge_state,node_runtime,node_tracking,node_vin_bridge toneAmber
class node_obd_core,node_pid_decode,node_response,node_pid_catalog,node_diagnostics,node_custom_pid,node_replay toneMint
class node_vin_parser,node_vin_lookup toneRose
class node_dtc_db,node_vpic_db,node_requests,node_user,node_adapter toneIndigo
```

## Components

### Desktop interface

- [Dashboard UI](https://github.com/provrb/obdium/blob/main/frontend/scripts/main.js): `frontend/scripts/main.js`
- [UI features](https://github.com/provrb/obdium/blob/main/frontend/scripts/features.js): `frontend/scripts/features.js`
- [Preferences](https://github.com/provrb/obdium/blob/main/frontend/scripts/settings.js): `frontend/scripts/settings.js`
- [VIN entry](https://github.com/provrb/obdium/blob/main/frontend/scripts/main.js): `frontend/scripts/main.js`

### Application bridge

- [Event handlers](https://github.com/provrb/obdium/blob/main/backend/src/bridge/events.rs): `backend/src/bridge/events.rs`
- [Connection state](https://github.com/provrb/obdium/blob/main/backend/src/bridge/mod.rs): `backend/src/bridge/mod.rs`
- [App runtime](https://github.com/provrb/obdium/blob/main/backend/src/main.rs): `backend/src/main.rs`
- [Metric tracking](https://github.com/provrb/obdium/blob/main/backend/src/stats.rs): `backend/src/stats.rs`
- [VIN request handler](https://github.com/provrb/obdium/blob/main/backend/src/bridge/events.rs): `backend/src/bridge/events.rs`

### OBD diagnostics

- [OBD connection](https://github.com/provrb/obdium/blob/main/backend/src/obd.rs): `backend/src/obd.rs`
- [Live PID decoding](https://github.com/provrb/obdium/blob/main/backend/src/pid/engine.rs): `backend/src/pid/engine.rs`
- [Response decoding](https://github.com/provrb/obdium/blob/main/backend/src/response.rs): `backend/src/response.rs`
- [PID catalog](https://github.com/provrb/obdium/blob/main/backend/src/dicts.rs): `backend/src/dicts.rs`
- [Codes and readiness](https://github.com/provrb/obdium/blob/main/backend/src/pid/diagnostics.rs): `backend/src/pid/diagnostics.rs`
- [Custom PIDs](https://github.com/provrb/obdium/blob/main/backend/src/bridge/events.rs): `backend/src/bridge/events.rs`
- [Demo replay](https://github.com/provrb/obdium/blob/main/backend/src/replay.rs): `backend/src/replay.rs`

### VIN decoding

- [VIN parser](https://github.com/provrb/obdium/blob/main/backend/src/vin/parser.rs): `backend/src/vin/parser.rs`
- [VPIC lookups](https://github.com/provrb/obdium/blob/main/backend/src/vin/attributes.rs): `backend/src/vin/attributes.rs`

### Offline data

- [Code descriptions](https://github.com/provrb/obdium/blob/main/backend/data/code-descriptions.sqlite): `backend/data/code-descriptions.sqlite`
- [VPIC database](https://github.com/provrb/obdium/blob/main/backend/data/vpic.sqlite.xz): `backend/data/vpic.sqlite.xz`
- [Recorded requests](https://github.com/provrb/obdium/blob/main/backend/data/requests.json): `backend/data/requests.json`

### Other components

- **Driver**
- **ELM327 adapter**

## Connections

- Driver → Dashboard UI: uses
- Dashboard UI → Event handlers: emits events
- Event handlers → App runtime: starts tracking
- Event handlers → Connection state: stores connection
- Event handlers → OBD connection: connects and queries
- OBD connection → ELM327 adapter: sends commands
- OBD connection → Live PID decoding: queries PIDs
- Live PID decoding → Response decoding: decodes responses
- App runtime → Metric tracking: runs polling
- Metric tracking → OBD connection: requests metrics
- Metric tracking → Dashboard UI: emits updates
- Dashboard UI → Codes and readiness: requests codes and tests
- Codes and readiness → Code descriptions: reads descriptions
- Dashboard UI → PID catalog: displays PID list
- Dashboard UI → Custom PIDs: submits custom PID
- Dashboard UI → Preferences: saves preferences
- VIN entry → VIN request handler: requests decoding
- VIN request handler → VIN parser: parses VIN
- VIN parser → VPIC lookups: looks up attributes
- VPIC lookups → VPIC database: queries database
- Dashboard UI → Demo replay: selects demo mode
- Demo replay → Recorded requests: reads recordings