# harishchand83077/outreach-automation architecture

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

- Interactive diagram: https://gitdiagram.com/harishchand83077/outreach-automation
- Repository: https://github.com/harishchand83077/outreach-automation

## Overview

Outreach-automation is a multi-tenant cold-outreach system: operators import leads, research companies, prepare drafts for human review, schedule approved mail, and process replies and opt-outs. The API and browser dashboard provide the user surface; a separate worker handles background work. The README documents the end-to-end workflow and safety controls. Source excerpts and the index support several internal links; unsampled route and worker behavior is represented only where the README establishes the relationship.

Main entry points: [`app/worker/handlers.py`](https://github.com/harishchand83077/outreach-automation/blob/main/app/worker/handlers.py) (Background worker), [`app/api/routers`](https://github.com/harishchand83077/outreach-automation/tree/main/app/api/routers) (API capabilities), [`app/services/reply/service.py`](https://github.com/harishchand83077/outreach-automation/blob/main/app/services/reply/service.py) (Reply handling), [`frontend/src/App.jsx`](https://github.com/harishchand83077/outreach-automation/blob/main/frontend/src/App.jsx) (Web dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_surface["User surfaces"]
  node_dashboard["Web dashboard<br/>[App.jsx]"]
  node_api["FastAPI application<br/>[app.py]"]
  node_routes["API capabilities"]
  node_extension["Browser extension<br/>[panel.ts]"]
end

subgraph group_workflow["Outreach workflow"]
  node_import["Lead import<br/>[service.py]"]
  node_research["Company research<br/>[service.py]"]
  node_search["Web search<br/>[search.py]"]
  node_drafting["Email drafting<br/>[generator.py]"]
  node_review["Draft review<br/>[drafts.py]"]
  node_reply["Reply handling<br/>[service.py]"]
  node_research_chain["Research search chain<br/>[chain.py]"]
end

subgraph group_runtime["Runtime operations"]
  node_worker["Background worker<br/>[handlers.py]"]
  node_mail["Mail transport<br/>[smtp.py]"]
  node_imap["Mailbox monitoring<br/>[imap.py]"]
  node_llm["LLM routing<br/>[router.py]"]
end

subgraph group_storage["Data and foundations"]
  node_postgres[("Postgres data<br/>[models.py]")]
  node_repository["Scoped data access<br/>[repo.py]"]
  node_queue["Job queue<br/>[queue.py]"]
  node_state["Lead state machine<br/>[state.py]"]
  node_settings["Validated settings<br/>[settings.py]"]
end

node_operator(("Campaign operator"))

node_operator -->|"uses"| node_dashboard
node_dashboard -->|"calls"| node_api
node_extension -.->|"submits leads"| node_api
node_api -->|"routes requests"| node_routes
node_routes -.->|"imports leads"| node_import
node_routes -.->|"requests research"| node_research
node_routes -->|"approves drafts"| node_review
node_worker -.->|"runs research"| node_research
node_research -->|"uses search chain"| node_research_chain
node_research_chain -->|"searches web"| node_search
node_worker -->|"creates drafts"| node_drafting
node_drafting -.->|"generates with"| node_llm
node_review -.->|"queues approved sends"| node_worker
node_worker -.->|"sends approved mail"| node_mail
node_imap -->|"ingests replies"| node_reply
node_reply -->|"cancels follow-ups"| node_queue
node_reply -->|"updates lead state"| node_state
node_repository -->|"reads and writes"| node_postgres
node_queue -->|"stores jobs"| node_postgres
node_worker -.->|"processes jobs"| node_queue
node_settings -.->|"configures providers"| node_llm
node_settings -->|"controls sending"| node_mail
node_operator -->|"reviews drafts"| node_review
node_operator -->|"manages campaigns"| node_dashboard
node_reply -.->|"reports outcomes"| node_operator

click node_dashboard "https://github.com/harishchand83077/outreach-automation/blob/main/frontend/src/App.jsx"
click node_api "https://github.com/harishchand83077/outreach-automation/blob/main/app/api/app.py"
click node_routes "https://github.com/harishchand83077/outreach-automation/tree/main/app/api/routers"
click node_extension "https://github.com/harishchand83077/outreach-automation/blob/main/extension/src/panel.ts"
click node_import "https://github.com/harishchand83077/outreach-automation/blob/main/app/services/importer/service.py"
click node_research "https://github.com/harishchand83077/outreach-automation/blob/main/app/services/research/service.py"
click node_search "https://github.com/harishchand83077/outreach-automation/blob/main/app/services/research/search.py"
click node_drafting "https://github.com/harishchand83077/outreach-automation/blob/main/app/services/drafting/generator.py"
click node_review "https://github.com/harishchand83077/outreach-automation/blob/main/app/db/drafts.py"
click node_reply "https://github.com/harishchand83077/outreach-automation/blob/main/app/services/reply/service.py"
click node_worker "https://github.com/harishchand83077/outreach-automation/blob/main/app/worker/handlers.py"
click node_mail "https://github.com/harishchand83077/outreach-automation/blob/main/app/services/mail/smtp.py"
click node_imap "https://github.com/harishchand83077/outreach-automation/blob/main/app/services/mail/imap.py"
click node_llm "https://github.com/harishchand83077/outreach-automation/blob/main/app/services/llm/router.py"
click node_postgres "https://github.com/harishchand83077/outreach-automation/blob/main/app/db/models.py"
click node_repository "https://github.com/harishchand83077/outreach-automation/blob/main/app/db/repo.py"
click node_queue "https://github.com/harishchand83077/outreach-automation/blob/main/app/db/queue.py"
click node_state "https://github.com/harishchand83077/outreach-automation/blob/main/app/domain/state.py"
click node_settings "https://github.com/harishchand83077/outreach-automation/blob/main/app/core/settings.py"
click node_research_chain "https://github.com/harishchand83077/outreach-automation/blob/main/app/services/research/chain.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_api,node_routes,node_extension toneBlue
class node_import,node_research,node_search,node_drafting,node_review,node_reply,node_research_chain toneAmber
class node_worker,node_mail,node_imap,node_llm toneMint
class node_postgres,node_repository,node_queue,node_state,node_settings toneRose
class node_operator toneIndigo
```

## Components

### User surfaces

- [Web dashboard](https://github.com/harishchand83077/outreach-automation/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [FastAPI application](https://github.com/harishchand83077/outreach-automation/blob/main/app/api/app.py): `app/api/app.py`
- [API capabilities](https://github.com/harishchand83077/outreach-automation/tree/main/app/api/routers): `app/api/routers`
- [Browser extension](https://github.com/harishchand83077/outreach-automation/blob/main/extension/src/panel.ts): `extension/src/panel.ts`

### Outreach workflow

- [Lead import](https://github.com/harishchand83077/outreach-automation/blob/main/app/services/importer/service.py): `app/services/importer/service.py`
- [Company research](https://github.com/harishchand83077/outreach-automation/blob/main/app/services/research/service.py): `app/services/research/service.py`
- [Web search](https://github.com/harishchand83077/outreach-automation/blob/main/app/services/research/search.py): `app/services/research/search.py`
- [Email drafting](https://github.com/harishchand83077/outreach-automation/blob/main/app/services/drafting/generator.py): `app/services/drafting/generator.py`
- [Draft review](https://github.com/harishchand83077/outreach-automation/blob/main/app/db/drafts.py): `app/db/drafts.py`
- [Reply handling](https://github.com/harishchand83077/outreach-automation/blob/main/app/services/reply/service.py): `app/services/reply/service.py`
- [Research search chain](https://github.com/harishchand83077/outreach-automation/blob/main/app/services/research/chain.py): `app/services/research/chain.py`

### Runtime operations

- [Background worker](https://github.com/harishchand83077/outreach-automation/blob/main/app/worker/handlers.py): `app/worker/handlers.py`
- [Mail transport](https://github.com/harishchand83077/outreach-automation/blob/main/app/services/mail/smtp.py): `app/services/mail/smtp.py`
- [Mailbox monitoring](https://github.com/harishchand83077/outreach-automation/blob/main/app/services/mail/imap.py): `app/services/mail/imap.py`
- [LLM routing](https://github.com/harishchand83077/outreach-automation/blob/main/app/services/llm/router.py): `app/services/llm/router.py`

### Data and foundations

- [Postgres data](https://github.com/harishchand83077/outreach-automation/blob/main/app/db/models.py): `app/db/models.py`
- [Scoped data access](https://github.com/harishchand83077/outreach-automation/blob/main/app/db/repo.py): `app/db/repo.py`
- [Job queue](https://github.com/harishchand83077/outreach-automation/blob/main/app/db/queue.py): `app/db/queue.py`
- [Lead state machine](https://github.com/harishchand83077/outreach-automation/blob/main/app/domain/state.py): `app/domain/state.py`
- [Validated settings](https://github.com/harishchand83077/outreach-automation/blob/main/app/core/settings.py): `app/core/settings.py`

### Other components

- **Campaign operator**

## Connections

- Campaign operator → Web dashboard: uses (evidence: `README.md`)
- Web dashboard → FastAPI application: calls (evidence: `frontend/src/App.jsx`)
- Browser extension → FastAPI application: submits leads
- FastAPI application → API capabilities: routes requests (evidence: `app/api/app.py`)
- API capabilities → Lead import: imports leads
- API capabilities → Company research: requests research
- API capabilities → Draft review: approves drafts (evidence: `app/api/routers/review.py`)
- Background worker → Company research: runs research (evidence: `app/worker/handlers.py`)
- Company research → Research search chain: uses search chain (evidence: `app/services/research/service.py`)
- Research search chain → Web search: searches web (evidence: `app/services/research/chain.py`)
- Background worker → Email drafting: creates drafts (evidence: `app/worker/handlers.py`)
- Email drafting → LLM routing: generates with
- Draft review → Background worker: queues approved sends (evidence: `app/worker/handlers.py`)
- Background worker → Mail transport: sends approved mail
- Mailbox monitoring → Reply handling: ingests replies (evidence: `app/services/reply/ingest.py`)
- Reply handling → Job queue: cancels follow-ups (evidence: `app/services/reply/service.py`)
- Reply handling → Lead state machine: updates lead state (evidence: `app/services/reply/service.py`)
- Scoped data access → Postgres data: reads and writes (evidence: `app/db/repo.py`)
- Job queue → Postgres data: stores jobs (evidence: `app/db/queue.py`)
- Background worker → Job queue: processes jobs (evidence: `app/worker/handlers.py`)
- Validated settings → LLM routing: configures providers
- Validated settings → Mail transport: controls sending (evidence: `README.md`)
- Campaign operator → Draft review: reviews drafts (evidence: `README.md`)
- Campaign operator → Web dashboard: manages campaigns (evidence: `README.md`)
- Reply handling → Campaign operator: reports outcomes
