# imaad00/whatsapp-product-review-collector architecture

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

- Interactive diagram: https://gitdiagram.com/imaad00/whatsapp-product-review-collector
- Repository: https://github.com/imaad00/whatsapp-product-review-collector

## Overview

The product collects reviews through a per-phone WhatsApp conversation, persists completed reviews, and exposes them in a periodically refreshed React table. The webhook owns the conversation transitions and database operations; the REST handler owns review listing. The README documents Twilio and local curl entry points, but the excerpts do not show Docker wiring or a direct Twilio client, so those links are not inferred.

Main entry points: [`backend/main.py`](https://github.com/imaad00/whatsapp-product-review-collector/blob/main/backend/main.py) (Conversation webhook), [`backend/db.py`](https://github.com/imaad00/whatsapp-product-review-collector/blob/main/backend/db.py) (PostgreSQL database), [`backend/models.py`](https://github.com/imaad00/whatsapp-product-review-collector/blob/main/backend/models.py) (Review records), [`frontend/src/App.js`](https://github.com/imaad00/whatsapp-product-review-collector/blob/main/frontend/src/App.js) (Reviews dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_conversation["Conversation intake"]
  node_webhook["Conversation webhook<br/>[main.py]"]
end

subgraph group_backend["Review backend"]
  node_sessionstate[("Conversation state<br/>[models.py]")]
  node_reviewrecords[("Review records<br/>[models.py]")]
  node_database[("PostgreSQL database<br/>[db.py]")]
  node_reviewapi["Reviews API<br/>[main.py]"]
end

subgraph group_frontend["Review dashboard"]
  node_dashboard["Reviews dashboard<br/>[App.js]"]
  node_frontendentry["React entry point<br/>[index.js]"]
end

node_reviewer(("WhatsApp reviewer"))
node_twilio{{"Twilio WhatsApp"}}

node_reviewer -->|"sends messages"| node_twilio
node_twilio -->|"posts messages"| node_webhook
node_reviewer -->|"simulates messages"| node_webhook
node_webhook -->|"reads and updates"| node_sessionstate
node_webhook -->|"creates review"| node_reviewrecords
node_webhook -->|"uses sessions"| node_database
node_reviewapi -->|"queries reviews"| node_reviewrecords
node_reviewapi -->|"uses database session"| node_database
node_dashboard -->|"fetches reviews"| node_reviewapi
node_frontendentry -->|"renders"| node_dashboard
node_database -->|"stores"| node_sessionstate
node_database -->|"stores"| node_reviewrecords

click node_webhook "https://github.com/imaad00/whatsapp-product-review-collector/blob/main/backend/main.py"
click node_sessionstate "https://github.com/imaad00/whatsapp-product-review-collector/blob/main/backend/models.py"
click node_reviewrecords "https://github.com/imaad00/whatsapp-product-review-collector/blob/main/backend/models.py"
click node_database "https://github.com/imaad00/whatsapp-product-review-collector/blob/main/backend/db.py"
click node_reviewapi "https://github.com/imaad00/whatsapp-product-review-collector/blob/main/backend/main.py"
click node_dashboard "https://github.com/imaad00/whatsapp-product-review-collector/blob/main/frontend/src/App.js"
click node_frontendentry "https://github.com/imaad00/whatsapp-product-review-collector/blob/main/frontend/src/index.js"

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_webhook,node_reviewer toneBlue
class node_sessionstate,node_reviewrecords,node_database,node_reviewapi toneAmber
class node_dashboard,node_frontendentry toneMint
class node_twilio toneIndigo
```

## Components

### Conversation intake

- [Conversation webhook](https://github.com/imaad00/whatsapp-product-review-collector/blob/main/backend/main.py): `backend/main.py`

### Review backend

- [Conversation state](https://github.com/imaad00/whatsapp-product-review-collector/blob/main/backend/models.py): `backend/models.py`
- [Review records](https://github.com/imaad00/whatsapp-product-review-collector/blob/main/backend/models.py): `backend/models.py`
- [PostgreSQL database](https://github.com/imaad00/whatsapp-product-review-collector/blob/main/backend/db.py): `backend/db.py`
- [Reviews API](https://github.com/imaad00/whatsapp-product-review-collector/blob/main/backend/main.py): `backend/main.py`

### Review dashboard

- [Reviews dashboard](https://github.com/imaad00/whatsapp-product-review-collector/blob/main/frontend/src/App.js): `frontend/src/App.js`
- [React entry point](https://github.com/imaad00/whatsapp-product-review-collector/blob/main/frontend/src/index.js): `frontend/src/index.js`

### Other components

- **WhatsApp reviewer**
- **Twilio WhatsApp**

## Connections

- WhatsApp reviewer → Twilio WhatsApp: sends messages (evidence: `README.md`)
- Twilio WhatsApp → Conversation webhook: posts messages (evidence: `README.md`)
- WhatsApp reviewer → Conversation webhook: simulates messages (evidence: `README.md`)
- Conversation webhook → Conversation state: reads and updates (evidence: `backend/main.py`)
- Conversation webhook → Review records: creates review (evidence: `backend/main.py`)
- Conversation webhook → PostgreSQL database: uses sessions (evidence: `backend/main.py`)
- Reviews API → Review records: queries reviews (evidence: `backend/main.py`)
- Reviews API → PostgreSQL database: uses database session (evidence: `backend/main.py`)
- Reviews dashboard → Reviews API: fetches reviews (evidence: `frontend/src/App.js`)
- React entry point → Reviews dashboard: renders (evidence: `frontend/src/index.js`)
- PostgreSQL database → Conversation state: stores (evidence: `backend/models.py`)
- PostgreSQL database → Review records: stores (evidence: `backend/models.py`)