# castlebbs/vehicle-diagnostic-assistant architecture

> Architecture diagram of the GitHub repository castlebbs/vehicle-diagnostic-assistant, 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/castlebbs/vehicle-diagnostic-assistant
- Repository: https://github.com/castlebbs/vehicle-diagnostic-assistant

## Overview

This repository is a Gradio vehicle-diagnostics assistant: a user chats with a LangGraph agent, which can query an MCP-connected OBD-II device or simulator, interpret raw PID data, and present diagnostic results. The README also documents VIN decoding, DTC handling, telemetry/history, and repair-video search. The sampled excerpts establish agent tool setup and result handling, but not every UI callback or MCP transport detail; the separately listed embedded-server repository is not present here.

Main entry points: [`app.py`](https://github.com/castlebbs/vehicle-diagnostic-assistant/blob/main/app.py) (Diagnostic agent), [`MCP_servers/gradio-OBD2-simulator/app.py`](https://github.com/castlebbs/vehicle-diagnostic-assistant/blob/main/MCP_servers/gradio-OBD2-simulator/app.py) (Simulator interfaces), [`tools.py`](https://github.com/castlebbs/vehicle-diagnostic-assistant/blob/main/tools.py) (VIN decoder), [`dtc_display.py`](https://github.com/castlebbs/vehicle-diagnostic-assistant/blob/main/dtc_display.py) (DTC display)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_gradio["Chat and dashboard<br/>[app.py]"]
  node_dtcview["DTC display<br/>[dtc_display.py]"]
  node_telemetry["Telemetry and history<br/>[app.py]"]
end

subgraph group_agent["Agent orchestration"]
  node_prompt["Mechanic prompt<br/>[prompts.py]"]
  node_agentflow["Diagnostic agent<br/>[app.py]"]
end

subgraph group_diagnostics["Diagnostic tools"]
  node_obdcalc["OBD value tools<br/>[tools.py]"]
  node_vindecode["VIN decoder<br/>[tools.py]"]
  node_youtube["Repair video search<br/>[tools.py]"]
end

subgraph group_mcp["MCP device access"]
  node_mcpclient["MCP client<br/>[app.py]"]
  node_elmtools["Vehicle MCP tools"]
end

subgraph group_simulator["OBD-II simulator"]
  node_simui["Simulator interfaces<br/>[app.py]"]
  node_simstate["Simulated vehicle state<br/>[app.py]"]
end

node_driver(("Vehicle owner"))
node_vehicle["Vehicle ECU"]
node_nhtsa["NHTSA vPIC"]
node_ytservice["YouTube search"]

node_driver -->|"asks diagnostics"| node_gradio
node_gradio -->|"submits chat"| node_agentflow
node_agentflow -->|"uses instructions"| node_prompt
node_agentflow -->|"loads MCP tools"| node_mcpclient
node_agentflow -->|"invokes calculations"| node_obdcalc
node_agentflow -->|"decodes VIN"| node_vindecode
node_agentflow -->|"searches repairs"| node_youtube
node_mcpclient -->|"obtains tools"| node_elmtools
node_elmtools -.->|"queries OBD-II"| node_vehicle
node_vindecode -->|"requests VIN data"| node_nhtsa
node_youtube -->|"searches videos"| node_ytservice
node_agentflow -->|"streams replies"| node_gradio
node_gradio -->|"updates DTCs"| node_dtcview
node_gradio -->|"captures history"| node_telemetry
node_simui -->|"reads vehicle state"| node_simstate
node_simui -.->|"serves MCP tools"| node_mcpclient

click node_gradio "https://github.com/castlebbs/vehicle-diagnostic-assistant/blob/main/app.py"
click node_dtcview "https://github.com/castlebbs/vehicle-diagnostic-assistant/blob/main/dtc_display.py"
click node_prompt "https://github.com/castlebbs/vehicle-diagnostic-assistant/blob/main/prompts.py"
click node_agentflow "https://github.com/castlebbs/vehicle-diagnostic-assistant/blob/main/app.py"
click node_mcpclient "https://github.com/castlebbs/vehicle-diagnostic-assistant/blob/main/app.py"
click node_obdcalc "https://github.com/castlebbs/vehicle-diagnostic-assistant/blob/main/tools.py"
click node_vindecode "https://github.com/castlebbs/vehicle-diagnostic-assistant/blob/main/tools.py"
click node_youtube "https://github.com/castlebbs/vehicle-diagnostic-assistant/blob/main/tools.py"
click node_telemetry "https://github.com/castlebbs/vehicle-diagnostic-assistant/blob/main/app.py"
click node_simui "https://github.com/castlebbs/vehicle-diagnostic-assistant/blob/main/MCP_servers/gradio-OBD2-simulator/app.py"
click node_simstate "https://github.com/castlebbs/vehicle-diagnostic-assistant/blob/main/MCP_servers/gradio-OBD2-simulator/app.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_gradio,node_dtcview,node_telemetry toneBlue
class node_prompt,node_agentflow toneAmber
class node_obdcalc,node_vindecode,node_youtube toneMint
class node_mcpclient,node_elmtools toneRose
class node_simui,node_simstate,node_driver,node_vehicle,node_nhtsa,node_ytservice toneIndigo
```

## Components

### User interface

- [Chat and dashboard](https://github.com/castlebbs/vehicle-diagnostic-assistant/blob/main/app.py): `app.py`
- [DTC display](https://github.com/castlebbs/vehicle-diagnostic-assistant/blob/main/dtc_display.py): `dtc_display.py`
- [Telemetry and history](https://github.com/castlebbs/vehicle-diagnostic-assistant/blob/main/app.py): `app.py`

### Agent orchestration

- [Mechanic prompt](https://github.com/castlebbs/vehicle-diagnostic-assistant/blob/main/prompts.py): `prompts.py`
- [Diagnostic agent](https://github.com/castlebbs/vehicle-diagnostic-assistant/blob/main/app.py): `app.py`

### Diagnostic tools

- [OBD value tools](https://github.com/castlebbs/vehicle-diagnostic-assistant/blob/main/tools.py): `tools.py`
- [VIN decoder](https://github.com/castlebbs/vehicle-diagnostic-assistant/blob/main/tools.py): `tools.py`
- [Repair video search](https://github.com/castlebbs/vehicle-diagnostic-assistant/blob/main/tools.py): `tools.py`

### MCP device access

- [MCP client](https://github.com/castlebbs/vehicle-diagnostic-assistant/blob/main/app.py): `app.py`
- **Vehicle MCP tools**

### OBD-II simulator

- [Simulator interfaces](https://github.com/castlebbs/vehicle-diagnostic-assistant/blob/main/MCP_servers/gradio-OBD2-simulator/app.py): `MCP_servers/gradio-OBD2-simulator/app.py`
- [Simulated vehicle state](https://github.com/castlebbs/vehicle-diagnostic-assistant/blob/main/MCP_servers/gradio-OBD2-simulator/app.py): `MCP_servers/gradio-OBD2-simulator/app.py`

### Other components

- **Vehicle owner**
- **Vehicle ECU**
- **NHTSA vPIC**
- **YouTube search**

## Connections

- Vehicle owner → Chat and dashboard: asks diagnostics
- Chat and dashboard → Diagnostic agent: submits chat
- Diagnostic agent → Mechanic prompt: uses instructions
- Diagnostic agent → MCP client: loads MCP tools
- Diagnostic agent → OBD value tools: invokes calculations
- Diagnostic agent → VIN decoder: decodes VIN
- Diagnostic agent → Repair video search: searches repairs
- MCP client → Vehicle MCP tools: obtains tools
- Vehicle MCP tools → Vehicle ECU: queries OBD-II
- VIN decoder → NHTSA vPIC: requests VIN data
- Repair video search → YouTube search: searches videos
- Diagnostic agent → Chat and dashboard: streams replies
- Chat and dashboard → DTC display: updates DTCs
- Chat and dashboard → Telemetry and history: captures history
- Simulator interfaces → Simulated vehicle state: reads vehicle state
- Simulator interfaces → MCP client: serves MCP tools