# jacobbhatt12/ops-dashboard architecture

> Architecture diagram of the GitHub repository jacobbhatt12/ops-dashboard, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jacobbhatt12/ops-dashboard
- Repository: https://github.com/jacobbhatt12/ops-dashboard

## Overview

This repository is an unattended agency back office with two principal workflows: monthly client site-health reports and lead discovery followed by scheduled outreach. Lead Finder imports and crawls businesses, queues them for review, then the outreach bot applies contact and bounce safeguards before sending. The dashboard exposes operational pages for these workflows and other agency records. Relationships are limited to calls visible in excerpts or the source index and workflows explicitly described in the README; unsampled integrations are not inferred.

Main entry points: [`bot/run_daily.py`](https://github.com/jacobbhatt12/ops-dashboard/blob/main/bot/run_daily.py) (Daily send orchestrator), [`monthly_agent.py`](https://github.com/jacobbhatt12/ops-dashboard/blob/main/monthly_agent.py) (Monthly report agent), [`leadfinder/run.py`](https://github.com/jacobbhatt12/ops-dashboard/blob/main/leadfinder/run.py) (Finder job runner), [`leadfinder/api.py`](https://github.com/jacobbhatt12/ops-dashboard/blob/main/leadfinder/api.py) (Lead Finder API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_reports["Client reporting"]
  node_monthly["Monthly report agent<br/>[monthly_agent.py]"]
  node_report_log[("Report send log<br/>[send_log.py]")]
  node_github["GitHub deploy status"]
  node_hosting["Hostinger site status"]
  node_analytics["GA4 traffic"]
  node_pagespeed["PageSpeed scores"]
  node_contacts_list["Client contacts"]
end

subgraph group_finder["Lead discovery"]
  node_overture["Overture import<br/>[overture.py]"]
  node_crawler["Website crawler<br/>[crawler.py]"]
  node_finder_settings[("Finder settings<br/>[settings.py]")]
  node_finder_runner["Finder job runner<br/>[run.py]"]
  node_finder_api["Lead Finder API<br/>[api.py]"]
end

subgraph group_outreach["Outreach sending"]
  node_gmail["Gmail service"]
  node_lead_template["Lead email template<br/>[template.py]"]
  node_daily_runner["Daily send orchestrator<br/>[run_daily.py]"]
  node_contact_rules["Contact eligibility<br/>[contacts.py]"]
  node_selector["Batch selection<br/>[selector.py]"]
  node_scanner["Opt-out and bounce scan<br/>[scanner.py]"]
  node_message["Outreach message<br/>[message.py]"]
end

subgraph group_dashboard["Operations dashboard"]
  node_dashboard_server["Dashboard server<br/>[ops_dashboard.py]"]
  node_dashboard_ui["Dashboard pages"]
  node_other_pages["Agency records pages"]
end

subgraph group_state["Persistent state"]
  node_lead_db[("Lead lifecycle store<br/>[store.py]")]
  node_bot_store[("Send and block store<br/>[store.py]")]
end

node_operator(("Agency operator"))

node_operator -->|"operates"| node_dashboard_ui
node_dashboard_ui -->|"uses"| node_dashboard_server
node_dashboard_server -->|"serves"| node_finder_api
node_dashboard_server -->|"exposes"| node_monthly
node_dashboard_server -->|"serves"| node_other_pages
node_operator -->|"reviews leads"| node_finder_api
node_finder_api -->|"reads and updates"| node_lead_db
node_finder_api -->|"renders preview"| node_lead_template
node_finder_api -->|"starts jobs"| node_finder_runner
node_finder_runner -->|"loads settings"| node_finder_settings
node_finder_runner -->|"imports places"| node_overture
node_finder_runner -->|"crawls sites"| node_crawler
node_finder_runner -->|"stores leads"| node_lead_db
node_finder_runner -->|"uses template"| node_lead_template
node_overture -->|"supplies businesses"| node_lead_db
node_crawler -->|"updates checks"| node_lead_db
node_finder_settings -->|"configures jobs"| node_finder_runner
node_daily_runner -->|"loads send state"| node_bot_store
node_daily_runner -->|"loads contacts"| node_contact_rules
node_daily_runner -->|"scans replies"| node_scanner
node_daily_runner -->|"selects batch"| node_selector
node_daily_runner -->|"sends messages"| node_gmail
node_daily_runner -->|"renders outreach"| node_message
node_daily_runner -->|"uses approved leads"| node_lead_db
node_scanner -->|"reads replies"| node_gmail
node_scanner -->|"blocks addresses"| node_bot_store
node_selector -->|"checks history"| node_bot_store
node_daily_runner -->|"renders lead emails"| node_lead_template
node_monthly -->|"checks deployments"| node_github
node_monthly -->|"collects site status"| node_hosting
node_monthly -->|"collects scores"| node_pagespeed
node_monthly -->|"gets traffic"| node_analytics
node_monthly -->|"reports to clients"| node_contacts_list
node_monthly -->|"sends reports"| node_gmail
node_monthly -->|"records sends"| node_report_log

click node_monthly "https://github.com/jacobbhatt12/ops-dashboard/blob/main/monthly_agent.py"
click node_report_log "https://github.com/jacobbhatt12/ops-dashboard/blob/main/send_log.py"
click node_overture "https://github.com/jacobbhatt12/ops-dashboard/blob/main/leadfinder/overture.py"
click node_crawler "https://github.com/jacobbhatt12/ops-dashboard/blob/main/leadfinder/crawler.py"
click node_lead_db "https://github.com/jacobbhatt12/ops-dashboard/blob/main/leadfinder/store.py"
click node_finder_settings "https://github.com/jacobbhatt12/ops-dashboard/blob/main/leadfinder/settings.py"
click node_finder_runner "https://github.com/jacobbhatt12/ops-dashboard/blob/main/leadfinder/run.py"
click node_finder_api "https://github.com/jacobbhatt12/ops-dashboard/blob/main/leadfinder/api.py"
click node_lead_template "https://github.com/jacobbhatt12/ops-dashboard/blob/main/leadfinder/template.py"
click node_daily_runner "https://github.com/jacobbhatt12/ops-dashboard/blob/main/bot/run_daily.py"
click node_contact_rules "https://github.com/jacobbhatt12/ops-dashboard/blob/main/bot/contacts.py"
click node_selector "https://github.com/jacobbhatt12/ops-dashboard/blob/main/bot/selector.py"
click node_scanner "https://github.com/jacobbhatt12/ops-dashboard/blob/main/bot/scanner.py"
click node_message "https://github.com/jacobbhatt12/ops-dashboard/blob/main/bot/message.py"
click node_bot_store "https://github.com/jacobbhatt12/ops-dashboard/blob/main/bot/store.py"
click node_dashboard_server "https://github.com/jacobbhatt12/ops-dashboard/blob/main/ops_dashboard.py"
click node_dashboard_ui "https://github.com/jacobbhatt12/ops-dashboard/tree/main/dashboard"
click node_other_pages "https://github.com/jacobbhatt12/ops-dashboard/tree/main/dashboard"

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_monthly,node_report_log,node_github,node_hosting,node_analytics,node_pagespeed,node_contacts_list toneBlue
class node_overture,node_crawler,node_finder_settings,node_finder_runner,node_finder_api toneAmber
class node_gmail,node_lead_template,node_daily_runner,node_contact_rules,node_selector,node_scanner,node_message toneMint
class node_dashboard_server,node_dashboard_ui,node_other_pages toneRose
class node_lead_db,node_bot_store,node_operator toneIndigo
```

## Components

### Client reporting

- [Monthly report agent](https://github.com/jacobbhatt12/ops-dashboard/blob/main/monthly_agent.py): `monthly_agent.py`
- [Report send log](https://github.com/jacobbhatt12/ops-dashboard/blob/main/send_log.py): `send_log.py`
- **GitHub deploy status**
- **Hostinger site status**
- **GA4 traffic**
- **PageSpeed scores**
- **Client contacts**

### Lead discovery

- [Overture import](https://github.com/jacobbhatt12/ops-dashboard/blob/main/leadfinder/overture.py): `leadfinder/overture.py`
- [Website crawler](https://github.com/jacobbhatt12/ops-dashboard/blob/main/leadfinder/crawler.py): `leadfinder/crawler.py`
- [Finder settings](https://github.com/jacobbhatt12/ops-dashboard/blob/main/leadfinder/settings.py): `leadfinder/settings.py`
- [Finder job runner](https://github.com/jacobbhatt12/ops-dashboard/blob/main/leadfinder/run.py): `leadfinder/run.py`
- [Lead Finder API](https://github.com/jacobbhatt12/ops-dashboard/blob/main/leadfinder/api.py): `leadfinder/api.py`

### Outreach sending

- **Gmail service**
- [Lead email template](https://github.com/jacobbhatt12/ops-dashboard/blob/main/leadfinder/template.py): `leadfinder/template.py`
- [Daily send orchestrator](https://github.com/jacobbhatt12/ops-dashboard/blob/main/bot/run_daily.py): `bot/run_daily.py`
- [Contact eligibility](https://github.com/jacobbhatt12/ops-dashboard/blob/main/bot/contacts.py): `bot/contacts.py`
- [Batch selection](https://github.com/jacobbhatt12/ops-dashboard/blob/main/bot/selector.py): `bot/selector.py`
- [Opt-out and bounce scan](https://github.com/jacobbhatt12/ops-dashboard/blob/main/bot/scanner.py): `bot/scanner.py`
- [Outreach message](https://github.com/jacobbhatt12/ops-dashboard/blob/main/bot/message.py): `bot/message.py`

### Operations dashboard

- [Dashboard server](https://github.com/jacobbhatt12/ops-dashboard/blob/main/ops_dashboard.py): `ops_dashboard.py`
- [Dashboard pages](https://github.com/jacobbhatt12/ops-dashboard/tree/main/dashboard): `dashboard`
- [Agency records pages](https://github.com/jacobbhatt12/ops-dashboard/tree/main/dashboard): `dashboard`

### Persistent state

- [Lead lifecycle store](https://github.com/jacobbhatt12/ops-dashboard/blob/main/leadfinder/store.py): `leadfinder/store.py`
- [Send and block store](https://github.com/jacobbhatt12/ops-dashboard/blob/main/bot/store.py): `bot/store.py`

### Other components

- **Agency operator**

## Connections

- Agency operator → Dashboard pages: operates (evidence: `README.md`)
- Dashboard pages → Dashboard server: uses (evidence: `README.md`)
- Dashboard server → Lead Finder API: serves (evidence: `ops_dashboard.py`)
- Dashboard server → Monthly report agent: exposes (evidence: `ops_dashboard.py`)
- Dashboard server → Agency records pages: serves (evidence: `README.md`)
- Agency operator → Lead Finder API: reviews leads (evidence: `README.md`)
- Lead Finder API → Lead lifecycle store: reads and updates (evidence: `leadfinder/api.py`)
- Lead Finder API → Lead email template: renders preview (evidence: `leadfinder/api.py`)
- Lead Finder API → Finder job runner: starts jobs (evidence: `leadfinder/api.py`)
- Finder job runner → Finder settings: loads settings (evidence: `leadfinder/run.py`)
- Finder job runner → Overture import: imports places (evidence: `leadfinder/run.py`)
- Finder job runner → Website crawler: crawls sites (evidence: `leadfinder/run.py`)
- Finder job runner → Lead lifecycle store: stores leads (evidence: `leadfinder/run.py`)
- Finder job runner → Lead email template: uses template (evidence: `leadfinder/run.py`)
- Overture import → Lead lifecycle store: supplies businesses (evidence: `README.md`)
- Website crawler → Lead lifecycle store: updates checks (evidence: `README.md`)
- Finder settings → Finder job runner: configures jobs (evidence: `README.md`)
- Daily send orchestrator → Send and block store: loads send state (evidence: `bot/run_daily.py`)
- Daily send orchestrator → Contact eligibility: loads contacts (evidence: `bot/run_daily.py`)
- Daily send orchestrator → Opt-out and bounce scan: scans replies (evidence: `bot/run_daily.py`)
- Daily send orchestrator → Batch selection: selects batch (evidence: `bot/run_daily.py`)
- Daily send orchestrator → Gmail service: sends messages (evidence: `README.md`)
- Daily send orchestrator → Outreach message: renders outreach (evidence: `bot/run_daily.py`)
- Daily send orchestrator → Lead lifecycle store: uses approved leads (evidence: `README.md`)
- Opt-out and bounce scan → Gmail service: reads replies (evidence: `README.md`)
- Opt-out and bounce scan → Send and block store: blocks addresses (evidence: `README.md`)
- Batch selection → Send and block store: checks history (evidence: `README.md`)
- Daily send orchestrator → Lead email template: renders lead emails (evidence: `README.md`)
- Monthly report agent → GitHub deploy status: checks deployments (evidence: `monthly_agent.py`)
- Monthly report agent → Hostinger site status: collects site status (evidence: `README.md`)
- Monthly report agent → PageSpeed scores: collects scores (evidence: `README.md`)
- Monthly report agent → GA4 traffic: gets traffic (evidence: `monthly_agent.py`)
- Monthly report agent → Client contacts: reports to clients (evidence: `README.md`)
- Monthly report agent → Gmail service: sends reports (evidence: `README.md`)
- Monthly report agent → Report send log: records sends (evidence: `monthly_agent.py`)
