# dhruvagarwal4543/car-sage-ai architecture

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

## Overview

CarSage is an Indian new-car research marketplace: users browse and filter a historical-specification catalogue, inspect or compare cars, and can request explainable recommendations, grounded assistant replies, experimental price estimates, or live-price comparisons. The React site calls a FastAPI service backed by PostgreSQL; preprocessing and model training form a separate data/ML branch. The README also documents Firebase-authenticated saved cars. Some subsystem links rely on README descriptions or source-index references because their implementations were not excerpted; the Chrome extension and LLM are planned, not built.

Main entry points: [`carsage/app.py`](https://github.com/dhruvagarwal4543/car-sage-ai/blob/main/carsage/app.py) (FastAPI routes), [`frontend/src/api.ts`](https://github.com/dhruvagarwal4543/car-sage-ai/blob/main/frontend/src/api.ts) (API client), [`carsage/recommend.py`](https://github.com/dhruvagarwal4543/car-sage-ai/blob/main/carsage/recommend.py) (Recommendation ranking), [`carsage/catalogue.py`](https://github.com/dhruvagarwal4543/car-sage-ai/blob/main/carsage/catalogue.py) (Catalogue search and detail)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data and ML"]
  node_raw["Raw car data"]
  node_preprocess["Data cleaning<br/>[preprocess.py]"]
  node_processed["Processed catalogue data"]
  node_price_train["Price model training"]
  node_price_model["Price model"]
  node_catalogue_import["Catalogue import"]
end

subgraph group_backend["API and domain"]
  node_db[("PostgreSQL catalogue and saved cars<br/>[models.py]")]
  node_api["FastAPI routes<br/>[app.py]"]
  node_catalogue["Catalogue search and detail<br/>[catalogue.py]"]
  node_recommend["Recommendation ranking<br/>[recommend.py]"]
  node_constraints["Constraint search<br/>[search.py]"]
  node_rules["Suitability rules<br/>[rules.py]"]
  node_assistant["Grounded assistant<br/>[assistant.py]"]
  node_prediction["Experimental estimate<br/>[predict.py]"]
  node_live_prices["Live price comparison<br/>[prices.py]"]
  node_auth["Token verification<br/>[auth.py]"]
end

subgraph group_web["Website"]
  node_site["React website<br/>[App.tsx]"]
  node_explore["Explore catalogue<br/>[Explore.tsx]"]
  node_detail_compare["Details and comparison<br/>[CarDetail.tsx]"]
  node_advisor["Advisor experience<br/>[Advisor.tsx]"]
  node_web_api["API client<br/>[api.ts]"]
  node_web_auth["Website sign-in<br/>[auth.tsx]"]
end

subgraph group_integrations["Identity and providers"]
  node_providers["Price providers<br/>[providers.py]"]
  node_firebase["Firebase authentication"]
end

node_buyer(("Car buyer"))

node_raw -->|"cleans and audits"| node_preprocess
node_preprocess -->|"writes dataset"| node_processed
node_processed -->|"trains from"| node_price_train
node_price_train -->|"produces model"| node_price_model
node_price_model -->|"serves estimates"| node_api
node_processed -->|"loads from"| node_catalogue_import
node_catalogue_import -->|"upserts cars"| node_db
node_buyer -->|"browses"| node_site
node_site -->|"uses"| node_web_api
node_explore -->|"requests cars"| node_web_api
node_detail_compare -->|"requests details"| node_web_api
node_advisor -->|"requests advice"| node_web_api
node_web_api -->|"calls endpoints"| node_api
node_api -->|"routes catalogue queries"| node_catalogue
node_catalogue -->|"reads catalogue"| node_db
node_api -->|"routes recommendations"| node_recommend
node_recommend -->|"searches feasible cars"| node_constraints
node_recommend -->|"derives suitability"| node_rules
node_recommend -->|"uses catalogue data"| node_catalogue
node_api -->|"routes questions"| node_assistant
node_assistant -->|"gets recommendations"| node_recommend
node_api -->|"routes estimates"| node_prediction
node_api -->|"routes price comparison"| node_live_prices
node_live_prices -->|"fetches quotes"| node_providers
node_web_auth -->|"signs in with"| node_firebase
node_web_auth -->|"provides token"| node_web_api
node_api -->|"verifies protected requests"| node_auth
node_auth -->|"verifies ID tokens"| node_firebase
node_api -->|"reads and writes saved cars"| node_db

click node_preprocess "https://github.com/dhruvagarwal4543/car-sage-ai/blob/main/src/preprocess.py"
click node_price_train "https://github.com/dhruvagarwal4543/car-sage-ai/blob/main/src/train_price_model.py"
click node_catalogue_import "https://github.com/dhruvagarwal4543/car-sage-ai/blob/main/carsage/import_catalogue.py"
click node_db "https://github.com/dhruvagarwal4543/car-sage-ai/blob/main/carsage/models.py"
click node_api "https://github.com/dhruvagarwal4543/car-sage-ai/blob/main/carsage/app.py"
click node_catalogue "https://github.com/dhruvagarwal4543/car-sage-ai/blob/main/carsage/catalogue.py"
click node_recommend "https://github.com/dhruvagarwal4543/car-sage-ai/blob/main/carsage/recommend.py"
click node_constraints "https://github.com/dhruvagarwal4543/car-sage-ai/blob/main/carsage/search.py"
click node_rules "https://github.com/dhruvagarwal4543/car-sage-ai/blob/main/carsage/rules.py"
click node_assistant "https://github.com/dhruvagarwal4543/car-sage-ai/blob/main/carsage/assistant.py"
click node_prediction "https://github.com/dhruvagarwal4543/car-sage-ai/blob/main/carsage/predict.py"
click node_live_prices "https://github.com/dhruvagarwal4543/car-sage-ai/blob/main/carsage/prices.py"
click node_providers "https://github.com/dhruvagarwal4543/car-sage-ai/blob/main/carsage/providers.py"
click node_auth "https://github.com/dhruvagarwal4543/car-sage-ai/blob/main/carsage/auth.py"
click node_site "https://github.com/dhruvagarwal4543/car-sage-ai/blob/main/frontend/src/App.tsx"
click node_explore "https://github.com/dhruvagarwal4543/car-sage-ai/blob/main/frontend/src/pages/Explore.tsx"
click node_detail_compare "https://github.com/dhruvagarwal4543/car-sage-ai/blob/main/frontend/src/pages/CarDetail.tsx"
click node_advisor "https://github.com/dhruvagarwal4543/car-sage-ai/blob/main/frontend/src/pages/Advisor.tsx"
click node_web_api "https://github.com/dhruvagarwal4543/car-sage-ai/blob/main/frontend/src/api.ts"
click node_web_auth "https://github.com/dhruvagarwal4543/car-sage-ai/blob/main/frontend/src/auth.tsx"

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_raw,node_preprocess,node_processed,node_price_train,node_price_model,node_catalogue_import toneBlue
class node_db,node_api,node_catalogue,node_recommend,node_constraints,node_rules,node_assistant,node_prediction,node_live_prices,node_auth toneAmber
class node_site,node_explore,node_detail_compare,node_advisor,node_web_api,node_web_auth toneMint
class node_providers,node_firebase toneRose
class node_buyer toneIndigo
```

## Components

### Data and ML

- **Raw car data**
- [Data cleaning](https://github.com/dhruvagarwal4543/car-sage-ai/blob/main/src/preprocess.py): `src/preprocess.py`
- **Processed catalogue data**
- [Price model training](https://github.com/dhruvagarwal4543/car-sage-ai/blob/main/src/train_price_model.py): `src/train_price_model.py`
- **Price model**
- [Catalogue import](https://github.com/dhruvagarwal4543/car-sage-ai/blob/main/carsage/import_catalogue.py): `carsage/import_catalogue.py`

### API and domain

- [PostgreSQL catalogue and saved cars](https://github.com/dhruvagarwal4543/car-sage-ai/blob/main/carsage/models.py): `carsage/models.py`
- [FastAPI routes](https://github.com/dhruvagarwal4543/car-sage-ai/blob/main/carsage/app.py): `carsage/app.py`
- [Catalogue search and detail](https://github.com/dhruvagarwal4543/car-sage-ai/blob/main/carsage/catalogue.py): `carsage/catalogue.py`
- [Recommendation ranking](https://github.com/dhruvagarwal4543/car-sage-ai/blob/main/carsage/recommend.py): `carsage/recommend.py`
- [Constraint search](https://github.com/dhruvagarwal4543/car-sage-ai/blob/main/carsage/search.py): `carsage/search.py`
- [Suitability rules](https://github.com/dhruvagarwal4543/car-sage-ai/blob/main/carsage/rules.py): `carsage/rules.py`
- [Grounded assistant](https://github.com/dhruvagarwal4543/car-sage-ai/blob/main/carsage/assistant.py): `carsage/assistant.py`
- [Experimental estimate](https://github.com/dhruvagarwal4543/car-sage-ai/blob/main/carsage/predict.py): `carsage/predict.py`
- [Live price comparison](https://github.com/dhruvagarwal4543/car-sage-ai/blob/main/carsage/prices.py): `carsage/prices.py`
- [Token verification](https://github.com/dhruvagarwal4543/car-sage-ai/blob/main/carsage/auth.py): `carsage/auth.py`

### Website

- [React website](https://github.com/dhruvagarwal4543/car-sage-ai/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Explore catalogue](https://github.com/dhruvagarwal4543/car-sage-ai/blob/main/frontend/src/pages/Explore.tsx): `frontend/src/pages/Explore.tsx`
- [Details and comparison](https://github.com/dhruvagarwal4543/car-sage-ai/blob/main/frontend/src/pages/CarDetail.tsx): `frontend/src/pages/CarDetail.tsx`
- [Advisor experience](https://github.com/dhruvagarwal4543/car-sage-ai/blob/main/frontend/src/pages/Advisor.tsx): `frontend/src/pages/Advisor.tsx`
- [API client](https://github.com/dhruvagarwal4543/car-sage-ai/blob/main/frontend/src/api.ts): `frontend/src/api.ts`
- [Website sign-in](https://github.com/dhruvagarwal4543/car-sage-ai/blob/main/frontend/src/auth.tsx): `frontend/src/auth.tsx`

### Identity and providers

- [Price providers](https://github.com/dhruvagarwal4543/car-sage-ai/blob/main/carsage/providers.py): `carsage/providers.py`
- **Firebase authentication**

### Other components

- **Car buyer**

## Connections

- Raw car data → Data cleaning: cleans and audits
- Data cleaning → Processed catalogue data: writes dataset
- Processed catalogue data → Price model training: trains from
- Price model training → Price model: produces model
- Price model → FastAPI routes: serves estimates
- Processed catalogue data → Catalogue import: loads from
- Catalogue import → PostgreSQL catalogue and saved cars: upserts cars
- Car buyer → React website: browses
- React website → API client: uses (evidence: `frontend/src/App.tsx`)
- Explore catalogue → API client: requests cars (evidence: `frontend/src/pages/Explore.tsx`)
- Details and comparison → API client: requests details (evidence: `frontend/src/pages/CarDetail.tsx`)
- Advisor experience → API client: requests advice
- API client → FastAPI routes: calls endpoints
- FastAPI routes → Catalogue search and detail: routes catalogue queries (evidence: `carsage/app.py`)
- Catalogue search and detail → PostgreSQL catalogue and saved cars: reads catalogue (evidence: `carsage/app.py`)
- FastAPI routes → Recommendation ranking: routes recommendations (evidence: `carsage/app.py`)
- Recommendation ranking → Constraint search: searches feasible cars (evidence: `carsage/recommend.py`)
- Recommendation ranking → Suitability rules: derives suitability (evidence: `carsage/recommend.py`)
- Recommendation ranking → Catalogue search and detail: uses catalogue data (evidence: `carsage/recommend.py`)
- FastAPI routes → Grounded assistant: routes questions (evidence: `carsage/app.py`)
- Grounded assistant → Recommendation ranking: gets recommendations (evidence: `carsage/assistant.py`)
- FastAPI routes → Experimental estimate: routes estimates (evidence: `carsage/app.py`)
- FastAPI routes → Live price comparison: routes price comparison (evidence: `carsage/app.py`)
- Live price comparison → Price providers: fetches quotes (evidence: `carsage/prices.py`)
- Website sign-in → Firebase authentication: signs in with
- Website sign-in → API client: provides token (evidence: `frontend/src/auth.tsx`)
- FastAPI routes → Token verification: verifies protected requests (evidence: `carsage/app.py`)
- Token verification → Firebase authentication: verifies ID tokens
- FastAPI routes → PostgreSQL catalogue and saved cars: reads and writes saved cars (evidence: `carsage/app.py`)
