# mohdtalal3/google-review-automation architecture

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

- Interactive diagram: https://gitdiagram.com/mohdtalal3/google-review-automation
- Repository: https://github.com/mohdtalal3/google-review-automation

## Overview

Google Review Automation combines a password-protected Flask dashboard with a separate polling worker. Users configure businesses and account pools, then queue review jobs with ratings, formats, and languages. The worker loads each business’s pending jobs and configuration, and the bot generates review text with Gemini before automating the Maps posting flow; results and failures are tracked in SQLite. The repository also documents a Donut Browser/Playwright bot variant, but the sampled worker uses the SeleniumBase bot. Relationships involving unsampled route and bot code are limited to documented or indexed evidence.

Main entry points: [`app.py`](https://github.com/mohdtalal3/google-review-automation/blob/main/app.py) (Web dashboard), [`bot.py`](https://github.com/mohdtalal3/google-review-automation/blob/main/bot.py) (SeleniumBase bot), [`bot_donut.py`](https://github.com/mohdtalal3/google-review-automation/blob/main/bot_donut.py) (Donut bot variant), [`db.py`](https://github.com/mohdtalal3/google-review-automation/blob/main/db.py) (SQLite state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Dashboard"]
  node_dashboard["Web dashboard<br/>[app.py]"]
  node_login_template["Login view<br/>[login.html]"]
  node_dashboard_template["Dashboard view<br/>[dashboard.html]"]
  node_business_template["Business view<br/>[business.html]"]
end

subgraph group_jobs["Job Processing"]
  node_worker["Job worker<br/>[worker.py]"]
  node_queue_jobs["Review job queue<br/>[db.py]"]
end

subgraph group_automation["Review Automation"]
  node_selenium_bot["SeleniumBase bot<br/>[bot.py]"]
  node_review_generation["Review generation<br/>[bot.py]"]
  node_donut_variant["Donut bot variant<br/>[bot_donut.py]"]
end

subgraph group_state["Persistent State"]
  node_review_store[("SQLite state<br/>[db.py]")]
end

node_operator(("Dashboard user"))
node_gemini{{"Gemini API"}}
node_browser["Chrome browser"]
node_maps["Google Maps"]
node_donut_service["Donut Browser API"]
node_playwright["Playwright CDP"]

node_operator -->|"manages"| node_dashboard
node_dashboard -->|"renders"| node_login_template
node_dashboard -->|"renders"| node_dashboard_template
node_dashboard -->|"renders"| node_business_template
node_dashboard -->|"reads and writes"| node_review_store
node_dashboard -->|"queues"| node_queue_jobs
node_queue_jobs -->|"persists jobs"| node_review_store
node_worker -->|"polls and updates"| node_review_store
node_worker -->|"dispatches jobs"| node_selenium_bot
node_selenium_bot -->|"reads jobs; records results"| node_review_store
node_selenium_bot -->|"generates text"| node_review_generation
node_review_generation -->|"requests text"| node_gemini
node_selenium_bot -->|"automates"| node_browser
node_browser -->|"posts review"| node_maps
node_donut_variant -->|"manages profiles"| node_donut_service
node_donut_variant -->|"connects via CDP"| node_playwright
node_donut_variant -->|"automates posting"| node_maps
node_worker -.->|"alternative implementation"| node_donut_variant

click node_dashboard "https://github.com/mohdtalal3/google-review-automation/blob/main/app.py"
click node_login_template "https://github.com/mohdtalal3/google-review-automation/blob/main/templates/login.html"
click node_dashboard_template "https://github.com/mohdtalal3/google-review-automation/blob/main/templates/dashboard.html"
click node_business_template "https://github.com/mohdtalal3/google-review-automation/blob/main/templates/business.html"
click node_worker "https://github.com/mohdtalal3/google-review-automation/blob/main/worker.py"
click node_queue_jobs "https://github.com/mohdtalal3/google-review-automation/blob/main/db.py"
click node_review_store "https://github.com/mohdtalal3/google-review-automation/blob/main/db.py"
click node_selenium_bot "https://github.com/mohdtalal3/google-review-automation/blob/main/bot.py"
click node_review_generation "https://github.com/mohdtalal3/google-review-automation/blob/main/bot.py"
click node_donut_variant "https://github.com/mohdtalal3/google-review-automation/blob/main/bot_donut.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_dashboard,node_login_template,node_dashboard_template,node_business_template,node_operator,node_browser,node_donut_service toneBlue
class node_worker,node_queue_jobs toneAmber
class node_selenium_bot,node_review_generation,node_donut_variant,node_gemini toneMint
class node_review_store toneRose
class node_maps,node_playwright toneIndigo
```

## Components

### Dashboard

- [Web dashboard](https://github.com/mohdtalal3/google-review-automation/blob/main/app.py): `app.py`
- [Login view](https://github.com/mohdtalal3/google-review-automation/blob/main/templates/login.html): `templates/login.html`
- [Dashboard view](https://github.com/mohdtalal3/google-review-automation/blob/main/templates/dashboard.html): `templates/dashboard.html`
- [Business view](https://github.com/mohdtalal3/google-review-automation/blob/main/templates/business.html): `templates/business.html`

### Job Processing

- [Job worker](https://github.com/mohdtalal3/google-review-automation/blob/main/worker.py): `worker.py`
- [Review job queue](https://github.com/mohdtalal3/google-review-automation/blob/main/db.py): `db.py`

### Review Automation

- [SeleniumBase bot](https://github.com/mohdtalal3/google-review-automation/blob/main/bot.py): `bot.py`
- [Review generation](https://github.com/mohdtalal3/google-review-automation/blob/main/bot.py): `bot.py`
- [Donut bot variant](https://github.com/mohdtalal3/google-review-automation/blob/main/bot_donut.py): `bot_donut.py`

### Persistent State

- [SQLite state](https://github.com/mohdtalal3/google-review-automation/blob/main/db.py): `db.py`

### Other components

- **Dashboard user**
- **Gemini API**
- **Chrome browser**
- **Google Maps**
- **Donut Browser API**
- **Playwright CDP**

## Connections

- Dashboard user → Web dashboard: manages (evidence: `README.md`)
- Web dashboard → Login view: renders (evidence: `app.py`)
- Web dashboard → Dashboard view: renders (evidence: `app.py`)
- Web dashboard → Business view: renders (evidence: `app.py`)
- Web dashboard → SQLite state: reads and writes (evidence: `app.py`)
- Web dashboard → Review job queue: queues (evidence: `app.py`)
- Review job queue → SQLite state: persists jobs (evidence: `db.py`)
- Job worker → SQLite state: polls and updates (evidence: `worker.py`)
- Job worker → SeleniumBase bot: dispatches jobs (evidence: `worker.py`)
- SeleniumBase bot → SQLite state: reads jobs; records results (evidence: `bot.py`)
- SeleniumBase bot → Review generation: generates text (evidence: `bot.py`)
- Review generation → Gemini API: requests text (evidence: `bot.py`)
- SeleniumBase bot → Chrome browser: automates (evidence: `bot.py`)
- Chrome browser → Google Maps: posts review
- Donut bot variant → Donut Browser API: manages profiles (evidence: `bot_donut.py`)
- Donut bot variant → Playwright CDP: connects via CDP (evidence: `bot_donut.py`)
- Donut bot variant → Google Maps: automates posting (evidence: `bot_donut.py`)
- Job worker → Donut bot variant: alternative implementation (evidence: `bot_donut.py`)
