# rsiniavski/obd-app architecture

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

- Interactive diagram: https://gitdiagram.com/rsiniavski/obd-app
- Repository: https://github.com/rsiniavski/obd-app

## Overview

OBD App is a BMW E90/E91 diagnostic dashboard with Kivy and terminal interfaces. Its main workflow selects an emulator or vehicle connection, reads telemetry and diagnostic trouble codes, then presents live values and supports refreshing or clearing DTCs. The README also documents configurable metric widgets, desktop serial and Android Bluetooth connections, and both internal and TCP emulation. The GUI excerpt is partial, so links from its screens to connection and reader services rely on indexed imports and documented behavior; unsampled internals are not inferred.

Main entry points: [`gui/main_app.py`](https://github.com/rsiniavski/obd-app/blob/main/gui/main_app.py) (Kivy dashboard), [`app/connection.py`](https://github.com/rsiniavski/obd-app/blob/main/app/connection.py) (Connection manager), [`app/reader.py`](https://github.com/rsiniavski/obd-app/blob/main/app/reader.py) (Telemetry and DTC reader), [`main.py`](https://github.com/rsiniavski/obd-app/blob/main/main.py) (Terminal dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_gui["Kivy dashboard<br/>[main_app.py]"]
  node_metric_cards["Metric cards<br/>[main_app.py]"]
  node_gui_screens["Dashboard, DTC, settings<br/>[ui_layout.kv]"]
  node_tui["Terminal dashboard<br/>[main.py]"]
  node_settings["UI and connection settings<br/>[settings.json]"]
end

subgraph group_diagnostics["Diagnostic services"]
  node_metric_catalog["Metric catalog and limits<br/>[config.py]"]
  node_reader["Telemetry and DTC reader<br/>[reader.py]"]
end

subgraph group_connectivity["Connections"]
  node_connection_manager["Connection manager<br/>[connection.py]"]
  node_desktop_obd["Desktop OBD adapter<br/>[connection.py]"]
  node_android_bt["Android Bluetooth adapter<br/>[android_bt.py]"]
  node_tcp_client["TCP OBD client<br/>[connection.py]"]
end

subgraph group_emulation["Emulation"]
  node_mock_reader["Internal telemetry mock<br/>[reader.py]"]
  node_tcp_emulator["TCP ELM327 server<br/>[server.py]"]
  node_mock_engine["OBD mock engine<br/>[mock_data.py]"]
end

node_driver(("Driver"))
node_vehicle(("ELM327 / vehicle"))

node_driver -->|"uses"| node_gui
node_driver -->|"uses"| node_tui
node_gui -->|"presents"| node_gui_screens
node_gui -.->|"reads diagnostics"| node_reader
node_gui -.->|"opens connection"| node_connection_manager
node_gui -->|"renders"| node_metric_cards
node_metric_cards -->|"uses limits"| node_metric_catalog
node_gui -->|"loads and saves"| node_settings
node_gui_screens -->|"defines screens"| node_gui
node_tui -->|"opens connection"| node_connection_manager
node_tui -->|"reads and controls"| node_reader
node_reader -->|"uses metrics"| node_metric_catalog
node_reader -->|"generates telemetry"| node_mock_reader
node_connection_manager -->|"creates adapter"| node_android_bt
node_android_bt -->|"sends OBD commands"| node_vehicle
node_connection_manager -->|"connects via serial"| node_desktop_obd
node_desktop_obd -->|"communicates"| node_vehicle
node_connection_manager -->|"configures socket"| node_tcp_client
node_tcp_client -->|"sends OBD requests"| node_tcp_emulator
node_tcp_emulator -->|"processes commands"| node_mock_engine
node_driver -->|"starts emulator"| node_tcp_emulator

click node_gui "https://github.com/rsiniavski/obd-app/blob/main/gui/main_app.py"
click node_metric_cards "https://github.com/rsiniavski/obd-app/blob/main/gui/main_app.py"
click node_gui_screens "https://github.com/rsiniavski/obd-app/blob/main/gui/ui_layout.kv"
click node_tui "https://github.com/rsiniavski/obd-app/blob/main/main.py"
click node_settings "https://github.com/rsiniavski/obd-app/blob/main/settings.json"
click node_metric_catalog "https://github.com/rsiniavski/obd-app/blob/main/config.py"
click node_reader "https://github.com/rsiniavski/obd-app/blob/main/app/reader.py"
click node_connection_manager "https://github.com/rsiniavski/obd-app/blob/main/app/connection.py"
click node_desktop_obd "https://github.com/rsiniavski/obd-app/blob/main/app/connection.py"
click node_android_bt "https://github.com/rsiniavski/obd-app/blob/main/app/android_bt.py"
click node_mock_reader "https://github.com/rsiniavski/obd-app/blob/main/app/reader.py"
click node_tcp_emulator "https://github.com/rsiniavski/obd-app/blob/main/emulator/server.py"
click node_mock_engine "https://github.com/rsiniavski/obd-app/blob/main/emulator/mock_data.py"
click node_tcp_client "https://github.com/rsiniavski/obd-app/blob/main/app/connection.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_gui,node_metric_cards,node_gui_screens,node_tui,node_settings toneBlue
class node_metric_catalog,node_reader toneAmber
class node_connection_manager,node_desktop_obd,node_android_bt,node_tcp_client toneMint
class node_mock_reader,node_tcp_emulator,node_mock_engine toneRose
class node_driver,node_vehicle toneIndigo
```

## Components

### User interfaces

- [Kivy dashboard](https://github.com/rsiniavski/obd-app/blob/main/gui/main_app.py): `gui/main_app.py`
- [Metric cards](https://github.com/rsiniavski/obd-app/blob/main/gui/main_app.py): `gui/main_app.py`
- [Dashboard, DTC, settings](https://github.com/rsiniavski/obd-app/blob/main/gui/ui_layout.kv): `gui/ui_layout.kv`
- [Terminal dashboard](https://github.com/rsiniavski/obd-app/blob/main/main.py): `main.py`
- [UI and connection settings](https://github.com/rsiniavski/obd-app/blob/main/settings.json): `settings.json`

### Diagnostic services

- [Metric catalog and limits](https://github.com/rsiniavski/obd-app/blob/main/config.py): `config.py`
- [Telemetry and DTC reader](https://github.com/rsiniavski/obd-app/blob/main/app/reader.py): `app/reader.py`

### Connections

- [Connection manager](https://github.com/rsiniavski/obd-app/blob/main/app/connection.py): `app/connection.py`
- [Desktop OBD adapter](https://github.com/rsiniavski/obd-app/blob/main/app/connection.py): `app/connection.py`
- [Android Bluetooth adapter](https://github.com/rsiniavski/obd-app/blob/main/app/android_bt.py): `app/android_bt.py`
- [TCP OBD client](https://github.com/rsiniavski/obd-app/blob/main/app/connection.py): `app/connection.py`

### Emulation

- [Internal telemetry mock](https://github.com/rsiniavski/obd-app/blob/main/app/reader.py): `app/reader.py`
- [TCP ELM327 server](https://github.com/rsiniavski/obd-app/blob/main/emulator/server.py): `emulator/server.py`
- [OBD mock engine](https://github.com/rsiniavski/obd-app/blob/main/emulator/mock_data.py): `emulator/mock_data.py`

### Other components

- **Driver**
- **ELM327 / vehicle**

## Connections

- Driver → Kivy dashboard: uses (evidence: `README.md`)
- Driver → Terminal dashboard: uses (evidence: `README.md`)
- Kivy dashboard → Dashboard, DTC, settings: presents (evidence: `README.md`)
- Kivy dashboard → Telemetry and DTC reader: reads diagnostics (evidence: `gui/main_app.py`)
- Kivy dashboard → Connection manager: opens connection (evidence: `gui/main_app.py`)
- Kivy dashboard → Metric cards: renders (evidence: `gui/main_app.py`)
- Metric cards → Metric catalog and limits: uses limits (evidence: `gui/main_app.py`)
- Kivy dashboard → UI and connection settings: loads and saves (evidence: `README.md`)
- Dashboard, DTC, settings → Kivy dashboard: defines screens (evidence: `README.md`)
- Terminal dashboard → Connection manager: opens connection (evidence: `main.py`)
- Terminal dashboard → Telemetry and DTC reader: reads and controls (evidence: `main.py`)
- Telemetry and DTC reader → Metric catalog and limits: uses metrics (evidence: `app/reader.py`)
- Telemetry and DTC reader → Internal telemetry mock: generates telemetry (evidence: `app/reader.py`)
- Connection manager → Android Bluetooth adapter: creates adapter (evidence: `app/connection.py`)
- Android Bluetooth adapter → ELM327 / vehicle: sends OBD commands (evidence: `app/android_bt.py`)
- Connection manager → Desktop OBD adapter: connects via serial (evidence: `README.md`)
- Desktop OBD adapter → ELM327 / vehicle: communicates (evidence: `README.md`)
- Connection manager → TCP OBD client: configures socket (evidence: `app/connection.py`)
- TCP OBD client → TCP ELM327 server: sends OBD requests (evidence: `README.md`)
- TCP ELM327 server → OBD mock engine: processes commands (evidence: `emulator/server.py`)
- Driver → TCP ELM327 server: starts emulator (evidence: `README.md`)
