# santhoshsivang/second-hand-car-shop-customer-review-analysis architecture

> Architecture diagram of the GitHub repository santhoshsivang/second-hand-car-shop-customer-review-analysis, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/santhoshsivang/second-hand-car-shop-customer-review-analysis
- Repository: https://github.com/santhoshsivang/second-hand-car-shop-customer-review-analysis

## Overview

Customer Review AI turns raw review CSVs into satisfaction and journey labels, optionally discovers named topics, and presents the resulting insights in an interactive dashboard with AI-generated keep/improve ideas and editable policy. The dashboard reads processed artifacts, aggregates filters, heatmap cells, and topic bubbles, and uses PostgreSQL and Gemini for idea generation. The README also documents optional AWS deployment. Preprocessing internals and frontend interactions are supported by excerpts; some backend route details and deployment wiring are represented only where the README documents them.

Main entry points: [`data_preprocessing/pipeline.py`](https://github.com/santhoshsivang/second-hand-car-shop-customer-review-analysis/blob/main/data_preprocessing/pipeline.py) (Pipeline orchestration), [`app/frontend/src/App.tsx`](https://github.com/santhoshsivang/second-hand-car-shop-customer-review-analysis/blob/main/app/frontend/src/App.tsx) (Dashboard shell), [`app/frontend/src/api.ts`](https://github.com/santhoshsivang/second-hand-car-shop-customer-review-analysis/blob/main/app/frontend/src/api.ts) (API client), [`app/backend/main.py`](https://github.com/santhoshsivang/second-hand-car-shop-customer-review-analysis/blob/main/app/backend/main.py) (FastAPI routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_prep["Offline preprocessing"]
  node_raw_reviews["Raw reviews"]
  node_pipeline["Pipeline orchestration<br/>[pipeline.py]"]
  node_cleaning["Review cleaning<br/>[clean_reviews.py]"]
  node_satisfaction["Satisfaction labels<br/>[satisfaction.py]"]
  node_journey["Journey classification<br/>[classify.py]"]
  node_validation["Output validation<br/>[validate.py]"]
  node_processed["Processed reviews"]
  node_topics_model["Topic modeling<br/>[bertopic_topics.py]"]
  node_topic_catalog["Topic catalog"]
end

subgraph group_dashboard["Interactive dashboard"]
  node_dashboard_ui["Dashboard shell<br/>[App.tsx]"]
  node_filter_ui["Filter controls<br/>[FilterSidebar.tsx]"]
  node_heatmap_ui["Heatmap<br/>[Heatmap.tsx]"]
  node_topics_ui["Topic bubbles<br/>[TopicBubbles.tsx]"]
  node_idea_ui["Idea modal<br/>[IdeaModal.tsx]"]
  node_policy_ui["Policy editor<br/>[PolicyEditor.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_services["Backend services"]
  node_backend["FastAPI routes<br/>[main.py]"]
  node_app_data["Artifact loader<br/>[data.py]"]
  node_aggregation["Insight aggregation<br/>[services.py]"]
  node_idea_service["Idea generation<br/>[ideas.py]"]
  node_policy_store[("PostgreSQL<br/>[db.py]")]
end

subgraph group_deploy["Optional deployment"]
  node_deployment["AWS deployment<br/>[main.tf]"]
end

node_operator(("Analyst"))
node_gemini{{"Gemini"}}
node_browser(("Browser user"))

node_operator -.->|"provides CSV"| node_raw_reviews
node_pipeline -->|"loads"| node_raw_reviews
node_pipeline -->|"cleans"| node_cleaning
node_pipeline -->|"labels satisfaction"| node_satisfaction
node_pipeline -->|"classifies stages"| node_journey
node_pipeline -->|"validates"| node_validation
node_pipeline -->|"writes"| node_processed
node_pipeline -->|"optionally runs"| node_topics_model
node_topics_model -->|"names topics"| node_gemini
node_topics_model -.->|"writes catalog"| node_topic_catalog
node_browser -.->|"uses"| node_dashboard_ui
node_dashboard_ui -->|"renders"| node_filter_ui
node_dashboard_ui -->|"renders"| node_heatmap_ui
node_dashboard_ui -->|"renders"| node_topics_ui
node_dashboard_ui -.->|"opens"| node_idea_ui
node_dashboard_ui -->|"renders"| node_policy_ui
node_filter_ui -->|"requests filters"| node_api_client
node_heatmap_ui -->|"requests heatmap"| node_api_client
node_topics_ui -->|"requests topics"| node_api_client
node_policy_ui -->|"loads and updates"| node_api_client
node_api_client -->|"calls API"| node_backend
node_backend -.->|"loads artifacts"| node_app_data
node_backend -.->|"serves insights"| node_aggregation
node_backend -.->|"generates ideas"| node_idea_service
node_app_data -.->|"reads reviews"| node_processed
node_app_data -.->|"reads topics"| node_topic_catalog
node_idea_service -.->|"loads policy"| node_policy_store
node_idea_service -.->|"requests ideas"| node_gemini
node_idea_service -.->|"saves ideas"| node_policy_store
node_operator -.->|"deploys optionally"| node_deployment

click node_raw_reviews "https://github.com/santhoshsivang/second-hand-car-shop-customer-review-analysis/tree/main/data_preprocessing/raw_data"
click node_pipeline "https://github.com/santhoshsivang/second-hand-car-shop-customer-review-analysis/blob/main/data_preprocessing/pipeline.py"
click node_cleaning "https://github.com/santhoshsivang/second-hand-car-shop-customer-review-analysis/blob/main/data_preprocessing/cleaning/clean_reviews.py"
click node_satisfaction "https://github.com/santhoshsivang/second-hand-car-shop-customer-review-analysis/blob/main/data_preprocessing/labeling/satisfaction.py"
click node_journey "https://github.com/santhoshsivang/second-hand-car-shop-customer-review-analysis/blob/main/data_preprocessing/journey_classification/classify.py"
click node_validation "https://github.com/santhoshsivang/second-hand-car-shop-customer-review-analysis/blob/main/data_preprocessing/validation/validate.py"
click node_processed "https://github.com/santhoshsivang/second-hand-car-shop-customer-review-analysis/tree/main/data_preprocessing/processed_data"
click node_topics_model "https://github.com/santhoshsivang/second-hand-car-shop-customer-review-analysis/blob/main/data_preprocessing/topic_modeling/bertopic_topics.py"
click node_topic_catalog "https://github.com/santhoshsivang/second-hand-car-shop-customer-review-analysis/tree/main/data_preprocessing/topic_modeling/output"
click node_dashboard_ui "https://github.com/santhoshsivang/second-hand-car-shop-customer-review-analysis/blob/main/app/frontend/src/App.tsx"
click node_filter_ui "https://github.com/santhoshsivang/second-hand-car-shop-customer-review-analysis/blob/main/app/frontend/src/components/FilterSidebar.tsx"
click node_heatmap_ui "https://github.com/santhoshsivang/second-hand-car-shop-customer-review-analysis/blob/main/app/frontend/src/components/Heatmap.tsx"
click node_topics_ui "https://github.com/santhoshsivang/second-hand-car-shop-customer-review-analysis/blob/main/app/frontend/src/components/TopicBubbles.tsx"
click node_idea_ui "https://github.com/santhoshsivang/second-hand-car-shop-customer-review-analysis/blob/main/app/frontend/src/components/IdeaModal.tsx"
click node_policy_ui "https://github.com/santhoshsivang/second-hand-car-shop-customer-review-analysis/blob/main/app/frontend/src/components/PolicyEditor.tsx"
click node_api_client "https://github.com/santhoshsivang/second-hand-car-shop-customer-review-analysis/blob/main/app/frontend/src/api.ts"
click node_backend "https://github.com/santhoshsivang/second-hand-car-shop-customer-review-analysis/blob/main/app/backend/main.py"
click node_app_data "https://github.com/santhoshsivang/second-hand-car-shop-customer-review-analysis/blob/main/app/backend/data.py"
click node_aggregation "https://github.com/santhoshsivang/second-hand-car-shop-customer-review-analysis/blob/main/app/backend/services.py"
click node_idea_service "https://github.com/santhoshsivang/second-hand-car-shop-customer-review-analysis/blob/main/app/backend/ideas.py"
click node_policy_store "https://github.com/santhoshsivang/second-hand-car-shop-customer-review-analysis/blob/main/app/backend/db.py"
click node_deployment "https://github.com/santhoshsivang/second-hand-car-shop-customer-review-analysis/blob/main/infra/main.tf"

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_reviews,node_pipeline,node_cleaning,node_satisfaction,node_journey,node_validation,node_processed,node_topics_model,node_topic_catalog,node_browser toneBlue
class node_dashboard_ui,node_filter_ui,node_heatmap_ui,node_topics_ui,node_idea_ui,node_policy_ui,node_api_client toneAmber
class node_backend,node_app_data,node_aggregation,node_idea_service,node_policy_store toneMint
class node_deployment toneRose
class node_operator,node_gemini toneIndigo
```

## Components

### Offline preprocessing

- [Raw reviews](https://github.com/santhoshsivang/second-hand-car-shop-customer-review-analysis/tree/main/data_preprocessing/raw_data): `data_preprocessing/raw_data`
- [Pipeline orchestration](https://github.com/santhoshsivang/second-hand-car-shop-customer-review-analysis/blob/main/data_preprocessing/pipeline.py): `data_preprocessing/pipeline.py`
- [Review cleaning](https://github.com/santhoshsivang/second-hand-car-shop-customer-review-analysis/blob/main/data_preprocessing/cleaning/clean_reviews.py): `data_preprocessing/cleaning/clean_reviews.py`
- [Satisfaction labels](https://github.com/santhoshsivang/second-hand-car-shop-customer-review-analysis/blob/main/data_preprocessing/labeling/satisfaction.py): `data_preprocessing/labeling/satisfaction.py`
- [Journey classification](https://github.com/santhoshsivang/second-hand-car-shop-customer-review-analysis/blob/main/data_preprocessing/journey_classification/classify.py): `data_preprocessing/journey_classification/classify.py`
- [Output validation](https://github.com/santhoshsivang/second-hand-car-shop-customer-review-analysis/blob/main/data_preprocessing/validation/validate.py): `data_preprocessing/validation/validate.py`
- [Processed reviews](https://github.com/santhoshsivang/second-hand-car-shop-customer-review-analysis/tree/main/data_preprocessing/processed_data): `data_preprocessing/processed_data`
- [Topic modeling](https://github.com/santhoshsivang/second-hand-car-shop-customer-review-analysis/blob/main/data_preprocessing/topic_modeling/bertopic_topics.py): `data_preprocessing/topic_modeling/bertopic_topics.py`
- [Topic catalog](https://github.com/santhoshsivang/second-hand-car-shop-customer-review-analysis/tree/main/data_preprocessing/topic_modeling/output): `data_preprocessing/topic_modeling/output`

### Interactive dashboard

- [Dashboard shell](https://github.com/santhoshsivang/second-hand-car-shop-customer-review-analysis/blob/main/app/frontend/src/App.tsx): `app/frontend/src/App.tsx`
- [Filter controls](https://github.com/santhoshsivang/second-hand-car-shop-customer-review-analysis/blob/main/app/frontend/src/components/FilterSidebar.tsx): `app/frontend/src/components/FilterSidebar.tsx`
- [Heatmap](https://github.com/santhoshsivang/second-hand-car-shop-customer-review-analysis/blob/main/app/frontend/src/components/Heatmap.tsx): `app/frontend/src/components/Heatmap.tsx`
- [Topic bubbles](https://github.com/santhoshsivang/second-hand-car-shop-customer-review-analysis/blob/main/app/frontend/src/components/TopicBubbles.tsx): `app/frontend/src/components/TopicBubbles.tsx`
- [Idea modal](https://github.com/santhoshsivang/second-hand-car-shop-customer-review-analysis/blob/main/app/frontend/src/components/IdeaModal.tsx): `app/frontend/src/components/IdeaModal.tsx`
- [Policy editor](https://github.com/santhoshsivang/second-hand-car-shop-customer-review-analysis/blob/main/app/frontend/src/components/PolicyEditor.tsx): `app/frontend/src/components/PolicyEditor.tsx`
- [API client](https://github.com/santhoshsivang/second-hand-car-shop-customer-review-analysis/blob/main/app/frontend/src/api.ts): `app/frontend/src/api.ts`

### Backend services

- [FastAPI routes](https://github.com/santhoshsivang/second-hand-car-shop-customer-review-analysis/blob/main/app/backend/main.py): `app/backend/main.py`
- [Artifact loader](https://github.com/santhoshsivang/second-hand-car-shop-customer-review-analysis/blob/main/app/backend/data.py): `app/backend/data.py`
- [Insight aggregation](https://github.com/santhoshsivang/second-hand-car-shop-customer-review-analysis/blob/main/app/backend/services.py): `app/backend/services.py`
- [Idea generation](https://github.com/santhoshsivang/second-hand-car-shop-customer-review-analysis/blob/main/app/backend/ideas.py): `app/backend/ideas.py`
- [PostgreSQL](https://github.com/santhoshsivang/second-hand-car-shop-customer-review-analysis/blob/main/app/backend/db.py): `app/backend/db.py`

### Optional deployment

- [AWS deployment](https://github.com/santhoshsivang/second-hand-car-shop-customer-review-analysis/blob/main/infra/main.tf): `infra/main.tf`

### Other components

- **Analyst**
- **Gemini**
- **Browser user**

## Connections

- Analyst → Raw reviews: provides CSV (evidence: `README.md`)
- Pipeline orchestration → Raw reviews: loads (evidence: `data_preprocessing/pipeline.py`)
- Pipeline orchestration → Review cleaning: cleans (evidence: `data_preprocessing/pipeline.py`)
- Pipeline orchestration → Satisfaction labels: labels satisfaction (evidence: `data_preprocessing/pipeline.py`)
- Pipeline orchestration → Journey classification: classifies stages (evidence: `data_preprocessing/pipeline.py`)
- Pipeline orchestration → Output validation: validates (evidence: `data_preprocessing/pipeline.py`)
- Pipeline orchestration → Processed reviews: writes (evidence: `data_preprocessing/pipeline.py`)
- Pipeline orchestration → Topic modeling: optionally runs (evidence: `data_preprocessing/pipeline.py`)
- Topic modeling → Gemini: names topics (evidence: `data_preprocessing/topic_modeling/bertopic_topics.py`)
- Topic modeling → Topic catalog: writes catalog
- Browser user → Dashboard shell: uses (evidence: `README.md`)
- Dashboard shell → Filter controls: renders (evidence: `app/frontend/src/App.tsx`)
- Dashboard shell → Heatmap: renders (evidence: `app/frontend/src/App.tsx`)
- Dashboard shell → Topic bubbles: renders (evidence: `app/frontend/src/App.tsx`)
- Dashboard shell → Idea modal: opens (evidence: `README.md`)
- Dashboard shell → Policy editor: renders (evidence: `app/frontend/src/App.tsx`)
- Filter controls → API client: requests filters (evidence: `app/frontend/src/components/FilterSidebar.tsx`)
- Heatmap → API client: requests heatmap (evidence: `app/frontend/src/components/Heatmap.tsx`)
- Topic bubbles → API client: requests topics (evidence: `app/frontend/src/components/TopicBubbles.tsx`)
- Policy editor → API client: loads and updates (evidence: `app/frontend/src/components/PolicyEditor.tsx`)
- API client → FastAPI routes: calls API (evidence: `README.md`)
- FastAPI routes → Artifact loader: loads artifacts (evidence: `README.md`)
- FastAPI routes → Insight aggregation: serves insights (evidence: `README.md`)
- FastAPI routes → Idea generation: generates ideas (evidence: `README.md`)
- Artifact loader → Processed reviews: reads reviews (evidence: `README.md`)
- Artifact loader → Topic catalog: reads topics (evidence: `README.md`)
- Idea generation → PostgreSQL: loads policy (evidence: `README.md`)
- Idea generation → Gemini: requests ideas (evidence: `README.md`)
- Idea generation → PostgreSQL: saves ideas (evidence: `README.md`)
- Analyst → AWS deployment: deploys optionally (evidence: `README.md`)
