# sufiankanaan/ai-car-assistant architecture

> Architecture diagram of the GitHub repository sufiankanaan/ai-car-assistant, 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/sufiankanaan/ai-car-assistant
- Repository: https://github.com/sufiankanaan/ai-car-assistant

## Overview

AI Car Assistant combines document-backed retrieval and calculator tools behind a model-routed chat agent. Users enter through Gradio or Streamlit; the agent calls Gemini, which may use knowledge search or calculators, then returns an answer subject to a numeric-input guard. The knowledge base is built from bundled text and documents, embedded, and stored in ChromaDB. README documents Langfuse tracing and these capabilities; unsampled internals are represented only where that documentation supports them.

Main entry points: [`agent.py`](https://github.com/sufiankanaan/ai-car-assistant/blob/main/agent.py) (Agent orchestration), [`rag.py`](https://github.com/sufiankanaan/ai-car-assistant/blob/main/rag.py) (ChromaDB collection), [`app.py`](https://github.com/sufiankanaan/ai-car-assistant/blob/main/app.py) (Streamlit chat), [`gradio_app.py`](https://github.com/sufiankanaan/ai-car-assistant/blob/main/gradio_app.py) (Gradio chat)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Chat interfaces"]
  node_streamlit["Streamlit chat<br/>[app.py]"]
  node_gradio["Gradio chat<br/>[gradio_app.py]"]
end

subgraph group_agent["Agent and safeguards"]
  node_orchestrator["Agent orchestration<br/>[agent.py]"]
  node_number_guard["Number guard<br/>[guard.py]"]
end

subgraph group_knowledge["Knowledge retrieval"]
  node_knowledge_search["Knowledge search<br/>[agent.py]"]
  node_document_loader["Document ingestion<br/>[doc_loader.py]"]
  node_knowledge_sources["Car knowledge sources<br/>[cars_knowledge.txt]"]
  node_documents["PDF and Word documents"]
  node_vector_store[("ChromaDB collection<br/>[rag.py]")]
end

subgraph group_calculations["Cost calculators"]
  node_calculators["Cost calculators<br/>[tools.py]"]
end

subgraph group_integrations["External services"]
  node_gemini{{"Gemini API"}}
  node_langfuse{{"Langfuse tracing"}}
end

node_user(("Car assistant user"))

node_user -->|"asks via"| node_streamlit
node_user -->|"asks via"| node_gradio
node_streamlit -->|"calls"| node_orchestrator
node_gradio -->|"calls"| node_orchestrator
node_orchestrator -->|"requests response"| node_gemini
node_orchestrator -->|"registers tool"| node_knowledge_search
node_orchestrator -->|"registers tools"| node_calculators
node_orchestrator -->|"checks numbers"| node_number_guard
node_orchestrator -->|"records traces"| node_langfuse
node_knowledge_search -->|"queries"| node_vector_store
node_knowledge_search -->|"embeds query"| node_gemini
node_knowledge_sources -->|"indexed at startup"| node_vector_store
node_documents -->|"converted and chunked"| node_document_loader
node_document_loader -->|"supplies chunks"| node_vector_store
node_calculators -->|"returns results"| node_orchestrator

click node_streamlit "https://github.com/sufiankanaan/ai-car-assistant/blob/main/app.py"
click node_gradio "https://github.com/sufiankanaan/ai-car-assistant/blob/main/gradio_app.py"
click node_orchestrator "https://github.com/sufiankanaan/ai-car-assistant/blob/main/agent.py"
click node_number_guard "https://github.com/sufiankanaan/ai-car-assistant/blob/main/guard.py"
click node_knowledge_search "https://github.com/sufiankanaan/ai-car-assistant/blob/main/agent.py"
click node_document_loader "https://github.com/sufiankanaan/ai-car-assistant/blob/main/doc_loader.py"
click node_knowledge_sources "https://github.com/sufiankanaan/ai-car-assistant/blob/main/cars_knowledge.txt"
click node_documents "https://github.com/sufiankanaan/ai-car-assistant/tree/main/docs"
click node_vector_store "https://github.com/sufiankanaan/ai-car-assistant/blob/main/rag.py"
click node_calculators "https://github.com/sufiankanaan/ai-car-assistant/blob/main/tools.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_streamlit,node_gradio,node_user toneBlue
class node_orchestrator,node_number_guard toneAmber
class node_knowledge_search,node_document_loader,node_knowledge_sources,node_documents,node_vector_store toneMint
class node_calculators toneRose
class node_gemini,node_langfuse toneIndigo
```

## Components

### Chat interfaces

- [Streamlit chat](https://github.com/sufiankanaan/ai-car-assistant/blob/main/app.py): `app.py`
- [Gradio chat](https://github.com/sufiankanaan/ai-car-assistant/blob/main/gradio_app.py): `gradio_app.py`

### Agent and safeguards

- [Agent orchestration](https://github.com/sufiankanaan/ai-car-assistant/blob/main/agent.py): `agent.py`
- [Number guard](https://github.com/sufiankanaan/ai-car-assistant/blob/main/guard.py): `guard.py`

### Knowledge retrieval

- [Knowledge search](https://github.com/sufiankanaan/ai-car-assistant/blob/main/agent.py): `agent.py`
- [Document ingestion](https://github.com/sufiankanaan/ai-car-assistant/blob/main/doc_loader.py): `doc_loader.py`
- [Car knowledge sources](https://github.com/sufiankanaan/ai-car-assistant/blob/main/cars_knowledge.txt): `cars_knowledge.txt`
- [PDF and Word documents](https://github.com/sufiankanaan/ai-car-assistant/tree/main/docs): `docs`
- [ChromaDB collection](https://github.com/sufiankanaan/ai-car-assistant/blob/main/rag.py): `rag.py`

### Cost calculators

- [Cost calculators](https://github.com/sufiankanaan/ai-car-assistant/blob/main/tools.py): `tools.py`

### External services

- **Gemini API**
- **Langfuse tracing**

### Other components

- **Car assistant user**

## Connections

- Car assistant user → Streamlit chat: asks via (evidence: `app.py`)
- Car assistant user → Gradio chat: asks via (evidence: `README.md`)
- Streamlit chat → Agent orchestration: calls (evidence: `app.py`)
- Gradio chat → Agent orchestration: calls (evidence: `gradio_app.py`)
- Agent orchestration → Gemini API: requests response (evidence: `agent.py`)
- Agent orchestration → Knowledge search: registers tool (evidence: `agent.py`)
- Agent orchestration → Cost calculators: registers tools (evidence: `agent.py`)
- Agent orchestration → Number guard: checks numbers (evidence: `agent.py`)
- Agent orchestration → Langfuse tracing: records traces (evidence: `README.md`)
- Knowledge search → ChromaDB collection: queries (evidence: `agent.py`)
- Knowledge search → Gemini API: embeds query (evidence: `agent.py`)
- Car knowledge sources → ChromaDB collection: indexed at startup (evidence: `rag.py`)
- PDF and Word documents → Document ingestion: converted and chunked (evidence: `README.md`)
- Document ingestion → ChromaDB collection: supplies chunks (evidence: `rag.py`)
- Cost calculators → Agent orchestration: returns results (evidence: `agent.py`)
