# hegdepavant-spec/vehicle_maintenance_agentic_flow architecture

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

- Interactive diagram: https://gitdiagram.com/hegdepavant-spec/vehicle_maintenance_agentic_flow
- Repository: https://github.com/hegdepavant-spec/vehicle_maintenance_agentic_flow

## Overview

Vehicle Maintenance AI is a conversational vehicle-assessment product: a user chats through the React app, the backend coordinates feature collection, conditionally obtains an authoritative ML prediction, and returns an advisor response. Separate capabilities cover persisted conversations, OAuth-backed emergency contacts and Gmail alerts, and provider failover. The README documents the agent roles and broader capabilities; sampled excerpts do not expose every API-to-service call, so uncertain wiring is omitted.

Main entry points: [`backend/app/agent/adk_agents/controller_agent.py`](https://github.com/hegdepavant-spec/vehicle_maintenance_agentic_flow/blob/main/backend/app/agent/adk_agents/controller_agent.py) (Controller agent), [`frontend/src/App.tsx`](https://github.com/hegdepavant-spec/vehicle_maintenance_agentic_flow/blob/main/frontend/src/App.tsx) (Chat interface), [`backend/app/agent/adk_agents/runner.py`](https://github.com/hegdepavant-spec/vehicle_maintenance_agentic_flow/blob/main/backend/app/agent/adk_agents/runner.py) (ADK runner), [`backend/app/emergency/routes.py`](https://github.com/hegdepavant-spec/vehicle_maintenance_agentic_flow/blob/main/backend/app/emergency/routes.py) (Emergency routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_web["Chat interface<br/>[App.tsx]"]
  node_emergency_ui["Emergency controls"]
end

subgraph group_conversation["Assessment workflow"]
  node_api["Chat API<br/>[chat.py]"]
  node_runner["ADK runner<br/>[runner.py]"]
  node_controller["Controller agent"]
  node_information["Information agent"]
  node_state["Feature state<br/>[state.py]"]
  node_response["Response agent<br/>[response_agent.py]"]
  node_context["Context manager<br/>[manager.py]"]
end

subgraph group_intelligence["Prediction and language"]
  node_prediction_agent["Prediction agent"]
  node_ml["ML predictor<br/>[predict.py]"]
  node_preprocessing["Feature processing<br/>[preprocessing.py]"]
  node_judge["Turn judge<br/>[judge_agent.py]"]
  node_llm["LLM router<br/>[router.py]"]
end

subgraph group_operations["Persistence and emergency"]
  node_conversations["Conversation API<br/>[conversations.py]"]
  node_memory["Conversation memory<br/>[repository.py]"]
  node_database[("Application database<br/>[models.py]")]
  node_emergency_api["Emergency routes<br/>[routes.py]"]
  node_emergency_engine["Emergency evaluator"]
  node_auth["OAuth routes<br/>[routes.py]"]
  node_tokens["Token manager<br/>[token_manager.py]"]
  node_gmail["Gmail service<br/>[gmail_service.py]"]
end

node_user(("Driver"))
node_google(("Google services"))

node_user -->|"sends messages"| node_web
node_web -->|"posts chat"| node_api
node_api -->|"runs turn"| node_runner
node_runner -->|"dispatches"| node_controller
node_controller -->|"delegates extraction"| node_information
node_information -->|"updates features"| node_state
node_controller -->|"delegates prediction"| node_prediction_agent
node_prediction_agent -->|"invokes model"| node_ml
node_ml -->|"processes features"| node_preprocessing
node_controller -->|"delegates response"| node_response
node_runner -->|"compacts context"| node_context
node_controller -->|"requests generation"| node_llm
node_runner -.->|"evaluates turn"| node_judge
node_web -->|"loads conversations"| node_conversations
node_conversations -->|"reads and writes"| node_memory
node_api -->|"persists chat"| node_memory
node_memory -->|"stores records"| node_database
node_web -->|"manages alerts"| node_emergency_api
node_emergency_api -->|"evaluates conditions"| node_emergency_engine
node_emergency_api -->|"gets credentials"| node_tokens
node_auth -->|"OAuth exchange"| node_google
node_auth -->|"stores tokens"| node_tokens
node_tokens -->|"reads and writes"| node_database
node_emergency_api -->|"sends alert"| node_gmail
node_gmail -->|"sends email"| node_google

click node_web "https://github.com/hegdepavant-spec/vehicle_maintenance_agentic_flow/blob/main/frontend/src/App.tsx"
click node_api "https://github.com/hegdepavant-spec/vehicle_maintenance_agentic_flow/blob/main/backend/app/api/chat.py"
click node_runner "https://github.com/hegdepavant-spec/vehicle_maintenance_agentic_flow/blob/main/backend/app/agent/adk_agents/runner.py"
click node_controller "https://github.com/hegdepavant-spec/vehicle_maintenance_agentic_flow/blob/main/backend/app/agent/adk_agents/controller_agent.py"
click node_information "https://github.com/hegdepavant-spec/vehicle_maintenance_agentic_flow/blob/main/backend/app/agent/adk_agents/information_agent.py"
click node_state "https://github.com/hegdepavant-spec/vehicle_maintenance_agentic_flow/blob/main/backend/app/agent/state/state.py"
click node_response "https://github.com/hegdepavant-spec/vehicle_maintenance_agentic_flow/blob/main/backend/app/agent/adk_agents/response_agent.py"
click node_prediction_agent "https://github.com/hegdepavant-spec/vehicle_maintenance_agentic_flow/blob/main/backend/app/agent/adk_agents/prediction_agent.py"
click node_ml "https://github.com/hegdepavant-spec/vehicle_maintenance_agentic_flow/blob/main/backend/app/ml/predict.py"
click node_preprocessing "https://github.com/hegdepavant-spec/vehicle_maintenance_agentic_flow/blob/main/backend/app/ml/preprocessing.py"
click node_judge "https://github.com/hegdepavant-spec/vehicle_maintenance_agentic_flow/blob/main/backend/app/agent/adk_agents/judge_agent.py"
click node_context "https://github.com/hegdepavant-spec/vehicle_maintenance_agentic_flow/blob/main/backend/app/context/manager.py"
click node_llm "https://github.com/hegdepavant-spec/vehicle_maintenance_agentic_flow/blob/main/backend/app/llm/router.py"
click node_conversations "https://github.com/hegdepavant-spec/vehicle_maintenance_agentic_flow/blob/main/backend/app/api/conversations.py"
click node_memory "https://github.com/hegdepavant-spec/vehicle_maintenance_agentic_flow/blob/main/backend/app/memory/repository.py"
click node_database "https://github.com/hegdepavant-spec/vehicle_maintenance_agentic_flow/blob/main/backend/app/database/models.py"
click node_emergency_ui "https://github.com/hegdepavant-spec/vehicle_maintenance_agentic_flow/blob/main/frontend/src/components/AccountEmergencyModal.tsx"
click node_emergency_api "https://github.com/hegdepavant-spec/vehicle_maintenance_agentic_flow/blob/main/backend/app/emergency/routes.py"
click node_emergency_engine "https://github.com/hegdepavant-spec/vehicle_maintenance_agentic_flow/blob/main/backend/app/emergency/emergency_engine.py"
click node_auth "https://github.com/hegdepavant-spec/vehicle_maintenance_agentic_flow/blob/main/backend/app/auth/routes.py"
click node_tokens "https://github.com/hegdepavant-spec/vehicle_maintenance_agentic_flow/blob/main/backend/app/auth/token_manager.py"
click node_gmail "https://github.com/hegdepavant-spec/vehicle_maintenance_agentic_flow/blob/main/backend/app/services/gmail_service.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_web,node_emergency_ui toneBlue
class node_api,node_runner,node_controller,node_information,node_state,node_response,node_context toneAmber
class node_prediction_agent,node_ml,node_preprocessing,node_judge,node_llm toneMint
class node_conversations,node_memory,node_database,node_emergency_api,node_emergency_engine,node_auth,node_tokens,node_gmail toneRose
class node_user,node_google toneIndigo
```

## Components

### Web client

- [Chat interface](https://github.com/hegdepavant-spec/vehicle_maintenance_agentic_flow/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Emergency controls](https://github.com/hegdepavant-spec/vehicle_maintenance_agentic_flow/blob/main/frontend/src/components/AccountEmergencyModal.tsx): `frontend/src/components/AccountEmergencyModal.tsx`

### Assessment workflow

- [Chat API](https://github.com/hegdepavant-spec/vehicle_maintenance_agentic_flow/blob/main/backend/app/api/chat.py): `backend/app/api/chat.py`
- [ADK runner](https://github.com/hegdepavant-spec/vehicle_maintenance_agentic_flow/blob/main/backend/app/agent/adk_agents/runner.py): `backend/app/agent/adk_agents/runner.py`
- [Controller agent](https://github.com/hegdepavant-spec/vehicle_maintenance_agentic_flow/blob/main/backend/app/agent/adk_agents/controller_agent.py): `backend/app/agent/adk_agents/controller_agent.py`
- [Information agent](https://github.com/hegdepavant-spec/vehicle_maintenance_agentic_flow/blob/main/backend/app/agent/adk_agents/information_agent.py): `backend/app/agent/adk_agents/information_agent.py`
- [Feature state](https://github.com/hegdepavant-spec/vehicle_maintenance_agentic_flow/blob/main/backend/app/agent/state/state.py): `backend/app/agent/state/state.py`
- [Response agent](https://github.com/hegdepavant-spec/vehicle_maintenance_agentic_flow/blob/main/backend/app/agent/adk_agents/response_agent.py): `backend/app/agent/adk_agents/response_agent.py`
- [Context manager](https://github.com/hegdepavant-spec/vehicle_maintenance_agentic_flow/blob/main/backend/app/context/manager.py): `backend/app/context/manager.py`

### Prediction and language

- [Prediction agent](https://github.com/hegdepavant-spec/vehicle_maintenance_agentic_flow/blob/main/backend/app/agent/adk_agents/prediction_agent.py): `backend/app/agent/adk_agents/prediction_agent.py`
- [ML predictor](https://github.com/hegdepavant-spec/vehicle_maintenance_agentic_flow/blob/main/backend/app/ml/predict.py): `backend/app/ml/predict.py`
- [Feature processing](https://github.com/hegdepavant-spec/vehicle_maintenance_agentic_flow/blob/main/backend/app/ml/preprocessing.py): `backend/app/ml/preprocessing.py`
- [Turn judge](https://github.com/hegdepavant-spec/vehicle_maintenance_agentic_flow/blob/main/backend/app/agent/adk_agents/judge_agent.py): `backend/app/agent/adk_agents/judge_agent.py`
- [LLM router](https://github.com/hegdepavant-spec/vehicle_maintenance_agentic_flow/blob/main/backend/app/llm/router.py): `backend/app/llm/router.py`

### Persistence and emergency

- [Conversation API](https://github.com/hegdepavant-spec/vehicle_maintenance_agentic_flow/blob/main/backend/app/api/conversations.py): `backend/app/api/conversations.py`
- [Conversation memory](https://github.com/hegdepavant-spec/vehicle_maintenance_agentic_flow/blob/main/backend/app/memory/repository.py): `backend/app/memory/repository.py`
- [Application database](https://github.com/hegdepavant-spec/vehicle_maintenance_agentic_flow/blob/main/backend/app/database/models.py): `backend/app/database/models.py`
- [Emergency routes](https://github.com/hegdepavant-spec/vehicle_maintenance_agentic_flow/blob/main/backend/app/emergency/routes.py): `backend/app/emergency/routes.py`
- [Emergency evaluator](https://github.com/hegdepavant-spec/vehicle_maintenance_agentic_flow/blob/main/backend/app/emergency/emergency_engine.py): `backend/app/emergency/emergency_engine.py`
- [OAuth routes](https://github.com/hegdepavant-spec/vehicle_maintenance_agentic_flow/blob/main/backend/app/auth/routes.py): `backend/app/auth/routes.py`
- [Token manager](https://github.com/hegdepavant-spec/vehicle_maintenance_agentic_flow/blob/main/backend/app/auth/token_manager.py): `backend/app/auth/token_manager.py`
- [Gmail service](https://github.com/hegdepavant-spec/vehicle_maintenance_agentic_flow/blob/main/backend/app/services/gmail_service.py): `backend/app/services/gmail_service.py`

### Other components

- **Driver**
- **Google services**

## Connections

- Driver → Chat interface: sends messages
- Chat interface → Chat API: posts chat
- Chat API → ADK runner: runs turn
- ADK runner → Controller agent: dispatches
- Controller agent → Information agent: delegates extraction
- Information agent → Feature state: updates features
- Controller agent → Prediction agent: delegates prediction
- Prediction agent → ML predictor: invokes model
- ML predictor → Feature processing: processes features
- Controller agent → Response agent: delegates response
- ADK runner → Context manager: compacts context
- Controller agent → LLM router: requests generation
- ADK runner → Turn judge: evaluates turn
- Chat interface → Conversation API: loads conversations
- Conversation API → Conversation memory: reads and writes
- Chat API → Conversation memory: persists chat
- Conversation memory → Application database: stores records
- Chat interface → Emergency routes: manages alerts
- Emergency routes → Emergency evaluator: evaluates conditions
- Emergency routes → Token manager: gets credentials
- OAuth routes → Google services: OAuth exchange
- OAuth routes → Token manager: stores tokens
- Token manager → Application database: reads and writes
- Emergency routes → Gmail service: sends alert
- Gmail service → Google services: sends email