# smuhammadtaha3/reputation-monitoring-agent architecture

> Architecture diagram of the GitHub repository smuhammadtaha3/reputation-monitoring-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/smuhammadtaha3/reputation-monitoring-agent
- Repository: https://github.com/smuhammadtaha3/reputation-monitoring-agent

## Overview

AI Reputation Monitoring Agent accepts reviews through a FastAPI API or periodically polls a simulated review source, analyzes sentiment and competitor mentions, drafts replies for reviews that warrant alerts, stores review records, and sends Telegram notifications. It also exposes review history and analytics, and serves a dashboard page. The API and scheduled worker have distinct processing paths. The README describes future platform integrations and UI plans; the sampled scraper currently rotates through a local Yelp review dataset. Edges reflect the shown routes, task, and service calls; unshown integration details are omitted.

Main entry points: [`app/api/routes.py`](https://github.com/smuhammadtaha3/reputation-monitoring-agent/blob/main/app/api/routes.py) (Review API), [`app/workers/tasks.py`](https://github.com/smuhammadtaha3/reputation-monitoring-agent/blob/main/app/workers/tasks.py) (Review Poll Task), [`app/core/database.py`](https://github.com/smuhammadtaha3/reputation-monitoring-agent/blob/main/app/core/database.py) (Supabase Client), [`app/services/draft.py`](https://github.com/smuhammadtaha3/reputation-monitoring-agent/blob/main/app/services/draft.py) (Reply Drafting)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["API and Dashboard"]
  node_api["Review API<br/>[routes.py]"]
  node_dashboard["Dashboard Page<br/>[index.html]"]
  node_app_server["FastAPI Server<br/>[main.py]"]
end

subgraph group_processing["Review Processing"]
  node_sentiment["Sentiment Analysis<br/>[sentiment.py]"]
  node_competitor["Competitor Detection<br/>[scraper.py]"]
  node_review_source["Review Dataset Pool"]
  node_drafts["Reply Drafting<br/>[draft.py]"]
  node_alerts["Telegram Alerts<br/>[alert.py]"]
end

subgraph group_operations["Scheduling and Workers"]
  node_poll_task["Review Poll Task<br/>[tasks.py]"]
  node_celery["Celery Scheduler<br/>[celery_app.py]"]
  node_config["Runtime Settings<br/>[config.py]"]
end

subgraph group_data["Data and Analytics"]
  node_db_client["Supabase Client<br/>[database.py]"]
  node_analytics["Review Analytics<br/>[analytics.py]"]
end

node_reviewer(("Review Submitter"))
node_groq{{"Groq LLaMA API"}}
node_telegram{{"Telegram Service"}}
node_supabase[("Supabase Database")]

node_reviewer -->|"submits review"| node_api
node_api -->|"analyzes text"| node_sentiment
node_api -->|"checks mentions"| node_competitor
node_api -->|"requests draft"| node_drafts
node_drafts -->|"generates reply"| node_groq
node_api -->|"sends alert"| node_alerts
node_alerts -->|"sends message"| node_telegram
node_api -->|"stores review"| node_db_client
node_db_client -->|"connects to"| node_supabase
node_api -->|"reads reviews"| node_db_client
node_api -->|"requests summaries"| node_analytics
node_analytics -->|"loads review data"| node_db_client
node_app_server -->|"mounts routes"| node_api
node_app_server -->|"serves page"| node_dashboard
node_app_server -->|"runs every 15 minutes"| node_poll_task
node_api -->|"triggers poll"| node_poll_task
node_poll_task -->|"fetches sample reviews"| node_review_source
node_poll_task -->|"analyzes reviews"| node_sentiment
node_poll_task -->|"checks mentions"| node_competitor
node_poll_task -->|"requests draft"| node_drafts
node_poll_task -->|"sends alert"| node_alerts
node_poll_task -->|"stores reviews"| node_db_client
node_celery -->|"registers task"| node_poll_task
node_db_client -->|"loads credentials"| node_config
node_drafts -->|"loads API key"| node_config
node_alerts -->|"loads bot settings"| node_config

click node_api "https://github.com/smuhammadtaha3/reputation-monitoring-agent/blob/main/app/api/routes.py"
click node_dashboard "https://github.com/smuhammadtaha3/reputation-monitoring-agent/blob/main/frontend/index.html"
click node_app_server "https://github.com/smuhammadtaha3/reputation-monitoring-agent/blob/main/app/main.py"
click node_sentiment "https://github.com/smuhammadtaha3/reputation-monitoring-agent/blob/main/app/services/sentiment.py"
click node_competitor "https://github.com/smuhammadtaha3/reputation-monitoring-agent/blob/main/app/services/scraper.py"
click node_review_source "https://github.com/smuhammadtaha3/reputation-monitoring-agent/blob/main/data/yelp_80000_fixed.json"
click node_drafts "https://github.com/smuhammadtaha3/reputation-monitoring-agent/blob/main/app/services/draft.py"
click node_alerts "https://github.com/smuhammadtaha3/reputation-monitoring-agent/blob/main/app/services/alert.py"
click node_poll_task "https://github.com/smuhammadtaha3/reputation-monitoring-agent/blob/main/app/workers/tasks.py"
click node_celery "https://github.com/smuhammadtaha3/reputation-monitoring-agent/blob/main/app/workers/celery_app.py"
click node_config "https://github.com/smuhammadtaha3/reputation-monitoring-agent/blob/main/app/core/config.py"
click node_db_client "https://github.com/smuhammadtaha3/reputation-monitoring-agent/blob/main/app/core/database.py"
click node_analytics "https://github.com/smuhammadtaha3/reputation-monitoring-agent/blob/main/app/services/analytics.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_dashboard,node_app_server,node_reviewer toneBlue
class node_sentiment,node_competitor,node_review_source,node_drafts,node_alerts,node_supabase toneAmber
class node_poll_task,node_celery,node_config,node_groq toneMint
class node_db_client,node_analytics toneRose
class node_telegram toneIndigo
```

## Components

### API and Dashboard

- [Review API](https://github.com/smuhammadtaha3/reputation-monitoring-agent/blob/main/app/api/routes.py): `app/api/routes.py`
- [Dashboard Page](https://github.com/smuhammadtaha3/reputation-monitoring-agent/blob/main/frontend/index.html): `frontend/index.html`
- [FastAPI Server](https://github.com/smuhammadtaha3/reputation-monitoring-agent/blob/main/app/main.py): `app/main.py`

### Review Processing

- [Sentiment Analysis](https://github.com/smuhammadtaha3/reputation-monitoring-agent/blob/main/app/services/sentiment.py): `app/services/sentiment.py`
- [Competitor Detection](https://github.com/smuhammadtaha3/reputation-monitoring-agent/blob/main/app/services/scraper.py): `app/services/scraper.py`
- [Review Dataset Pool](https://github.com/smuhammadtaha3/reputation-monitoring-agent/blob/main/data/yelp_80000_fixed.json): `data/yelp_80000_fixed.json`
- [Reply Drafting](https://github.com/smuhammadtaha3/reputation-monitoring-agent/blob/main/app/services/draft.py): `app/services/draft.py`
- [Telegram Alerts](https://github.com/smuhammadtaha3/reputation-monitoring-agent/blob/main/app/services/alert.py): `app/services/alert.py`

### Scheduling and Workers

- [Review Poll Task](https://github.com/smuhammadtaha3/reputation-monitoring-agent/blob/main/app/workers/tasks.py): `app/workers/tasks.py`
- [Celery Scheduler](https://github.com/smuhammadtaha3/reputation-monitoring-agent/blob/main/app/workers/celery_app.py): `app/workers/celery_app.py`
- [Runtime Settings](https://github.com/smuhammadtaha3/reputation-monitoring-agent/blob/main/app/core/config.py): `app/core/config.py`

### Data and Analytics

- [Supabase Client](https://github.com/smuhammadtaha3/reputation-monitoring-agent/blob/main/app/core/database.py): `app/core/database.py`
- [Review Analytics](https://github.com/smuhammadtaha3/reputation-monitoring-agent/blob/main/app/services/analytics.py): `app/services/analytics.py`

### Other components

- **Review Submitter**
- **Groq LLaMA API**
- **Telegram Service**
- **Supabase Database**

## Connections

- Review Submitter → Review API: submits review (evidence: `README.md`)
- Review API → Sentiment Analysis: analyzes text (evidence: `app/api/routes.py`)
- Review API → Competitor Detection: checks mentions (evidence: `app/api/routes.py`)
- Review API → Reply Drafting: requests draft (evidence: `app/api/routes.py`)
- Reply Drafting → Groq LLaMA API: generates reply (evidence: `README.md`)
- Review API → Telegram Alerts: sends alert (evidence: `app/api/routes.py`)
- Telegram Alerts → Telegram Service: sends message (evidence: `app/services/alert.py`)
- Review API → Supabase Client: stores review (evidence: `app/api/routes.py`)
- Supabase Client → Supabase Database: connects to (evidence: `app/core/database.py`)
- Review API → Supabase Client: reads reviews (evidence: `app/api/routes.py`)
- Review API → Review Analytics: requests summaries (evidence: `app/api/routes.py`)
- Review Analytics → Supabase Client: loads review data (evidence: `app/services/analytics.py`)
- FastAPI Server → Review API: mounts routes (evidence: `app/main.py`)
- FastAPI Server → Dashboard Page: serves page (evidence: `app/main.py`)
- FastAPI Server → Review Poll Task: runs every 15 minutes (evidence: `app/main.py`)
- Review API → Review Poll Task: triggers poll (evidence: `app/api/routes.py`)
- Review Poll Task → Review Dataset Pool: fetches sample reviews (evidence: `app/workers/tasks.py`)
- Review Poll Task → Sentiment Analysis: analyzes reviews (evidence: `app/workers/tasks.py`)
- Review Poll Task → Competitor Detection: checks mentions (evidence: `app/workers/tasks.py`)
- Review Poll Task → Reply Drafting: requests draft (evidence: `app/workers/tasks.py`)
- Review Poll Task → Telegram Alerts: sends alert (evidence: `app/workers/tasks.py`)
- Review Poll Task → Supabase Client: stores reviews (evidence: `app/workers/tasks.py`)
- Celery Scheduler → Review Poll Task: registers task (evidence: `app/workers/celery_app.py`)
- Supabase Client → Runtime Settings: loads credentials (evidence: `app/core/database.py`)
- Reply Drafting → Runtime Settings: loads API key (evidence: `app/services/draft.py`)
- Telegram Alerts → Runtime Settings: loads bot settings (evidence: `app/services/alert.py`)