# hoaihue04/review-insight architecture

> Architecture diagram of the GitHub repository hoaihue04/review-insight, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hoaihue04/review-insight
- Repository: https://github.com/hoaihue04/review-insight

## Overview

ReviewInsight is a Vietnamese e-commerce review analytics app for sellers. A seller submits a product link or ID; the app fetches product data and reviews, cleans and splits review text, predicts aspect-level sentiment with PhoBERT, then presents dashboard summaries, trends, and verbatim opinions. A separate review assistant answers product-specific questions using analytics and retrieved evidence. The graph covers the documented dashboard capabilities, background analysis, persistence, and assistant subsystems. Some internals are unsampled; edges are limited to relationships shown by excerpts, the source index, or README.

Main entry points: [`app/web/dashboard_service.py`](https://github.com/hoaihue04/review-insight/blob/main/app/web/dashboard_service.py) (Product analysis and analytics), [`app/assistant/assistant_service.py`](https://github.com/hoaihue04/review-insight/blob/main/app/assistant/assistant_service.py) (Question answering and advice), [`app/assistant/retrieval.py`](https://github.com/hoaihue04/review-insight/blob/main/app/assistant/retrieval.py) (Hybrid evidence retrieval), [`app/main.py`](https://github.com/hoaihue04/review-insight/blob/main/app/main.py) (FastAPI app and routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_intake["Product analysis"]
  node_api["FastAPI app and routes<br/>[main.py]"]
  node_job_manager["Analysis jobs and progress<br/>[analysis_jobs.py]"]
  node_dashboard_service["Product analysis and analytics"]
  node_tiki["Tiki product and review fetch<br/>[tiki_client.py]"]
  node_phobert["PhoBERT aspect sentiment"]
end

subgraph group_dashboard["Seller dashboard"]
  node_dashboard_ui["Seller dashboard interface"]
  node_dashboard_summary["Dashboard summaries and trends<br/>[seller_summary.py]"]
  node_csv["Filtered opinion CSV<br/>[csv_fallback.py]"]
end

subgraph group_assistant["Review assistant"]
  node_assistant_routes["Assistant endpoints<br/>[assistant.py]"]
  node_assistant_service["Question answering and advice"]
  node_query_analysis["Question intent and aspects<br/>[query_analyzer.py]"]
  node_retrieval["Hybrid evidence retrieval<br/>[retrieval.py]"]
  node_statistics["Question-focused statistics"]
  node_risk["Product risk assessment<br/>[risk.py]"]
  node_llm["Language model client<br/>[llm.py]"]
end

subgraph group_storage["Data and retrieval"]
  node_repository["Product and opinion repository<br/>[repository.py]"]
  node_database[("PostgreSQL and pgvector<br/>[db.py]")]
  node_vector_store["Semantic opinion store<br/>[vector_store.py]"]
end

node_seller(("Seller"))
node_tiki_service{{"Tiki marketplace API"}}
node_llm_service{{"Configured LLM provider"}}

node_seller -->|"submits product"| node_api
node_api -->|"starts analysis"| node_job_manager
node_api -->|"routes questions"| node_assistant_routes
node_job_manager -->|"runs analysis"| node_dashboard_service
node_dashboard_service -->|"fetches reviews"| node_tiki
node_tiki -->|"requests product data"| node_tiki_service
node_dashboard_service -->|"predicts opinions"| node_phobert
node_dashboard_service -->|"persists analysis"| node_repository
node_dashboard_service -->|"assesses risks"| node_risk
node_dashboard_service -->|"builds summaries"| node_dashboard_summary
node_seller -->|"views results"| node_dashboard_ui
node_dashboard_ui -->|"exports filtered opinions"| node_csv
node_assistant_routes -->|"analyzes product"| node_dashboard_service
node_assistant_routes -->|"requests answers"| node_assistant_service
node_assistant_service -->|"analyzes question"| node_query_analysis
node_assistant_service -->|"retrieves evidence"| node_retrieval
node_assistant_service -->|"plans statistics"| node_statistics
node_assistant_service -->|"uses risk context"| node_risk
node_assistant_service -->|"generates answer"| node_llm
node_llm -.->|"sends prompt"| node_llm_service
node_retrieval -->|"uses query aspects"| node_query_analysis
node_retrieval -->|"searches opinions"| node_vector_store
node_retrieval -.->|"loads structured evidence"| node_repository
node_repository -->|"reads and writes"| node_database
node_vector_store -->|"queries vectors"| node_database

click node_api "https://github.com/hoaihue04/review-insight/blob/main/app/main.py"
click node_job_manager "https://github.com/hoaihue04/review-insight/blob/main/app/core/analysis_jobs.py"
click node_dashboard_service "https://github.com/hoaihue04/review-insight/blob/main/app/web/dashboard_service.py"
click node_tiki "https://github.com/hoaihue04/review-insight/blob/main/app/web/tiki_client.py"
click node_phobert "https://github.com/hoaihue04/review-insight/blob/main/app/web/phobert_predictor.py"
click node_dashboard_ui "https://github.com/hoaihue04/review-insight/blob/main/app/static/seller_dashboard.js"
click node_dashboard_summary "https://github.com/hoaihue04/review-insight/blob/main/app/web/seller_summary.py"
click node_csv "https://github.com/hoaihue04/review-insight/blob/main/app/web/csv_fallback.py"
click node_assistant_routes "https://github.com/hoaihue04/review-insight/blob/main/app/api/routes/assistant.py"
click node_assistant_service "https://github.com/hoaihue04/review-insight/blob/main/app/assistant/assistant_service.py"
click node_query_analysis "https://github.com/hoaihue04/review-insight/blob/main/app/assistant/query_analyzer.py"
click node_retrieval "https://github.com/hoaihue04/review-insight/blob/main/app/assistant/retrieval.py"
click node_statistics "https://github.com/hoaihue04/review-insight/blob/main/app/assistant/statistics_planner.py"
click node_risk "https://github.com/hoaihue04/review-insight/blob/main/app/assistant/risk.py"
click node_llm "https://github.com/hoaihue04/review-insight/blob/main/app/assistant/llm.py"
click node_repository "https://github.com/hoaihue04/review-insight/blob/main/app/assistant/repository.py"
click node_database "https://github.com/hoaihue04/review-insight/blob/main/app/assistant/db.py"
click node_vector_store "https://github.com/hoaihue04/review-insight/blob/main/app/assistant/vector_store.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_api,node_job_manager,node_dashboard_service,node_tiki,node_phobert toneBlue
class node_dashboard_ui,node_dashboard_summary,node_csv toneAmber
class node_assistant_routes,node_assistant_service,node_query_analysis,node_retrieval,node_statistics,node_risk,node_llm,node_tiki_service toneMint
class node_repository,node_database,node_vector_store toneRose
class node_seller,node_llm_service toneIndigo
```

## Components

### Product analysis

- [FastAPI app and routes](https://github.com/hoaihue04/review-insight/blob/main/app/main.py): `app/main.py`
- [Analysis jobs and progress](https://github.com/hoaihue04/review-insight/blob/main/app/core/analysis_jobs.py): `app/core/analysis_jobs.py`
- [Product analysis and analytics](https://github.com/hoaihue04/review-insight/blob/main/app/web/dashboard_service.py): `app/web/dashboard_service.py`
- [Tiki product and review fetch](https://github.com/hoaihue04/review-insight/blob/main/app/web/tiki_client.py): `app/web/tiki_client.py`
- [PhoBERT aspect sentiment](https://github.com/hoaihue04/review-insight/blob/main/app/web/phobert_predictor.py): `app/web/phobert_predictor.py`

### Seller dashboard

- [Seller dashboard interface](https://github.com/hoaihue04/review-insight/blob/main/app/static/seller_dashboard.js): `app/static/seller_dashboard.js`
- [Dashboard summaries and trends](https://github.com/hoaihue04/review-insight/blob/main/app/web/seller_summary.py): `app/web/seller_summary.py`
- [Filtered opinion CSV](https://github.com/hoaihue04/review-insight/blob/main/app/web/csv_fallback.py): `app/web/csv_fallback.py`

### Review assistant

- [Assistant endpoints](https://github.com/hoaihue04/review-insight/blob/main/app/api/routes/assistant.py): `app/api/routes/assistant.py`
- [Question answering and advice](https://github.com/hoaihue04/review-insight/blob/main/app/assistant/assistant_service.py): `app/assistant/assistant_service.py`
- [Question intent and aspects](https://github.com/hoaihue04/review-insight/blob/main/app/assistant/query_analyzer.py): `app/assistant/query_analyzer.py`
- [Hybrid evidence retrieval](https://github.com/hoaihue04/review-insight/blob/main/app/assistant/retrieval.py): `app/assistant/retrieval.py`
- [Question-focused statistics](https://github.com/hoaihue04/review-insight/blob/main/app/assistant/statistics_planner.py): `app/assistant/statistics_planner.py`
- [Product risk assessment](https://github.com/hoaihue04/review-insight/blob/main/app/assistant/risk.py): `app/assistant/risk.py`
- [Language model client](https://github.com/hoaihue04/review-insight/blob/main/app/assistant/llm.py): `app/assistant/llm.py`

### Data and retrieval

- [Product and opinion repository](https://github.com/hoaihue04/review-insight/blob/main/app/assistant/repository.py): `app/assistant/repository.py`
- [PostgreSQL and pgvector](https://github.com/hoaihue04/review-insight/blob/main/app/assistant/db.py): `app/assistant/db.py`
- [Semantic opinion store](https://github.com/hoaihue04/review-insight/blob/main/app/assistant/vector_store.py): `app/assistant/vector_store.py`

### Other components

- **Seller**
- **Tiki marketplace API**
- **Configured LLM provider**

## Connections

- Seller → FastAPI app and routes: submits product (evidence: `README.md`)
- FastAPI app and routes → Analysis jobs and progress: starts analysis (evidence: `app/main.py`)
- FastAPI app and routes → Assistant endpoints: routes questions (evidence: `app/main.py`)
- Analysis jobs and progress → Product analysis and analytics: runs analysis (evidence: `app/core/analysis_jobs.py`)
- Product analysis and analytics → Tiki product and review fetch: fetches reviews (evidence: `app/web/dashboard_service.py`)
- Tiki product and review fetch → Tiki marketplace API: requests product data (evidence: `app/web/tiki_client.py`)
- Product analysis and analytics → PhoBERT aspect sentiment: predicts opinions (evidence: `app/web/dashboard_service.py`)
- Product analysis and analytics → Product and opinion repository: persists analysis (evidence: `app/web/dashboard_service.py`)
- Product analysis and analytics → Product risk assessment: assesses risks (evidence: `app/web/dashboard_service.py`)
- Product analysis and analytics → Dashboard summaries and trends: builds summaries (evidence: `app/web/dashboard_service.py`)
- Seller → Seller dashboard interface: views results (evidence: `README.md`)
- Seller dashboard interface → Filtered opinion CSV: exports filtered opinions (evidence: `README.md`)
- Assistant endpoints → Product analysis and analytics: analyzes product (evidence: `app/api/routes/assistant.py`)
- Assistant endpoints → Question answering and advice: requests answers (evidence: `app/api/routes/assistant.py`)
- Question answering and advice → Question intent and aspects: analyzes question (evidence: `app/assistant/assistant_service.py`)
- Question answering and advice → Hybrid evidence retrieval: retrieves evidence (evidence: `app/assistant/assistant_service.py`)
- Question answering and advice → Question-focused statistics: plans statistics (evidence: `app/assistant/assistant_service.py`)
- Question answering and advice → Product risk assessment: uses risk context (evidence: `app/assistant/assistant_service.py`)
- Question answering and advice → Language model client: generates answer (evidence: `app/assistant/assistant_service.py`)
- Language model client → Configured LLM provider: sends prompt
- Hybrid evidence retrieval → Question intent and aspects: uses query aspects (evidence: `app/assistant/retrieval.py`)
- Hybrid evidence retrieval → Semantic opinion store: searches opinions (evidence: `app/assistant/retrieval.py`)
- Hybrid evidence retrieval → Product and opinion repository: loads structured evidence
- Product and opinion repository → PostgreSQL and pgvector: reads and writes (evidence: `app/assistant/repository.py`)
- Semantic opinion store → PostgreSQL and pgvector: queries vectors (evidence: `app/assistant/vector_store.py`)
