# okapitales/automotive-sales-knowledge architecture

> Architecture diagram of the GitHub repository okapitales/automotive-sales-knowledge, 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/okapitales/automotive-sales-knowledge
- Repository: https://github.com/okapitales/automotive-sales-knowledge

## Overview

ASK is a FastAPI-based automotive knowledge assistant. Its demonstrated workflow is: an advisor submits a question, the API cleans and classifies it, then runs a retrieval-and-generation chain over Chroma and returns an answer. The repository also has a separate embedding/search service and vehicle reference documents. The README describes VIN-aware answers, clarification, and dealer handoffs, but the sampled implementation does not show those flows; ingestion and the processed-data producer are also not inspectable here.

Main entry points: [`api/assistant_service.py`](https://github.com/okapitales/automotive-sales-knowledge/blob/ASK/api/assistant_service.py) (Assistant API), [`ingestion/ingest`](https://github.com/okapitales/automotive-sales-knowledge/blob/ASK/ingestion/ingest) (Document ingestion), [`embeddings/embed_service.py`](https://github.com/okapitales/automotive-sales-knowledge/blob/ASK/embeddings/embed_service.py) (Embedding service), [`2024-volkswagen-id.4.pdf`](https://github.com/okapitales/automotive-sales-knowledge/blob/ASK/2024-volkswagen-id.4.pdf) (Vehicle references)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Question handling"]
  node_assistant_api["Assistant API"]
  node_query_gateway["Query gateway<br/>[slm_gateway.py]"]
  node_clarification["Clarification questions<br/>[README.md]"]
  node_dealer_handoff["Dealer handoff<br/>[README.md]"]
end

subgraph group_knowledge["Knowledge and retrieval"]
  node_embedding_service["Embedding service<br/>[embed_service.py]"]
  node_ingestion["Document ingestion"]
  node_vehicle_docs["Vehicle references"]
  node_chroma[("Chroma index")]
end

subgraph group_generation["Answer generation"]
  node_rag_chain["RAG chain"]
  node_llm["Language model"]
  node_vin_answers["VIN-aware answers<br/>[README.md]"]
end

node_advisor(("Advisor or customer"))

node_advisor -->|"submits question"| node_assistant_api
node_assistant_api -->|"cleans and classifies"| node_query_gateway
node_assistant_api -->|"runs query"| node_rag_chain
node_rag_chain -->|"retrieves context"| node_chroma
node_rag_chain -->|"generates answer"| node_llm
node_embedding_service -->|"creates or searches"| node_chroma
node_ingestion -.->|"prepares knowledge"| node_chroma
node_vehicle_docs -.->|"supplies references"| node_ingestion
node_advisor -.->|"may clarify"| node_clarification
node_advisor -.->|"may request"| node_vin_answers
node_assistant_api -.->|"can generate"| node_dealer_handoff

click node_assistant_api "https://github.com/okapitales/automotive-sales-knowledge/blob/ASK/api/assistant_service.py"
click node_query_gateway "https://github.com/okapitales/automotive-sales-knowledge/blob/ASK/api/slm_gateway.py"
click node_embedding_service "https://github.com/okapitales/automotive-sales-knowledge/blob/ASK/embeddings/embed_service.py"
click node_ingestion "https://github.com/okapitales/automotive-sales-knowledge/blob/ASK/ingestion/ingest"
click node_vehicle_docs "https://github.com/okapitales/automotive-sales-knowledge/blob/ASK/2024-volkswagen-id.4.pdf"
click node_rag_chain "https://github.com/okapitales/automotive-sales-knowledge/blob/ASK/api/assistant_service.py"
click node_vin_answers "https://github.com/okapitales/automotive-sales-knowledge/blob/ASK/README.md"
click node_clarification "https://github.com/okapitales/automotive-sales-knowledge/blob/ASK/README.md"
click node_dealer_handoff "https://github.com/okapitales/automotive-sales-knowledge/blob/ASK/README.md"

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_assistant_api,node_query_gateway,node_clarification,node_dealer_handoff toneBlue
class node_embedding_service,node_ingestion,node_vehicle_docs,node_chroma toneAmber
class node_rag_chain,node_llm,node_vin_answers toneMint
class node_advisor toneIndigo
```

## Components

### Question handling

- [Assistant API](https://github.com/okapitales/automotive-sales-knowledge/blob/ASK/api/assistant_service.py): `api/assistant_service.py`
- [Query gateway](https://github.com/okapitales/automotive-sales-knowledge/blob/ASK/api/slm_gateway.py): `api/slm_gateway.py`
- [Clarification questions](https://github.com/okapitales/automotive-sales-knowledge/blob/ASK/README.md): `README.md`
- [Dealer handoff](https://github.com/okapitales/automotive-sales-knowledge/blob/ASK/README.md): `README.md`

### Knowledge and retrieval

- [Embedding service](https://github.com/okapitales/automotive-sales-knowledge/blob/ASK/embeddings/embed_service.py): `embeddings/embed_service.py`
- [Document ingestion](https://github.com/okapitales/automotive-sales-knowledge/blob/ASK/ingestion/ingest): `ingestion/ingest`
- [Vehicle references](https://github.com/okapitales/automotive-sales-knowledge/blob/ASK/2024-volkswagen-id.4.pdf): `2024-volkswagen-id.4.pdf`
- **Chroma index**

### Answer generation

- [RAG chain](https://github.com/okapitales/automotive-sales-knowledge/blob/ASK/api/assistant_service.py): `api/assistant_service.py`
- **Language model**
- [VIN-aware answers](https://github.com/okapitales/automotive-sales-knowledge/blob/ASK/README.md): `README.md`

### Other components

- **Advisor or customer**

## Connections

- Advisor or customer → Assistant API: submits question (evidence: `README.md`)
- Assistant API → Query gateway: cleans and classifies (evidence: `api/assistant_service.py`)
- Assistant API → RAG chain: runs query (evidence: `api/assistant_service.py`)
- RAG chain → Chroma index: retrieves context (evidence: `api/assistant_service.py`)
- RAG chain → Language model: generates answer (evidence: `api/assistant_service.py`)
- Embedding service → Chroma index: creates or searches (evidence: `embeddings/embed_service.py`)
- Document ingestion → Chroma index: prepares knowledge
- Vehicle references → Document ingestion: supplies references
- Advisor or customer → Clarification questions: may clarify (evidence: `README.md`)
- Advisor or customer → VIN-aware answers: may request (evidence: `README.md`)
- Assistant API → Dealer handoff: can generate (evidence: `README.md`)