# xiongqvq/ai_find_customer architecture

> Architecture diagram of the GitHub repository xiongqvq/ai_find_customer, 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/xiongqvq/ai_find_customer
- Repository: https://github.com/xiongqvq/ai_find_customer

## Overview

AI Hunter is a B2B prospecting application: users submit a company site, product documents, or keywords and a target market; the backend interprets the input, searches for prospects, extracts lead details, and evaluates whether to continue. The UI also supports queued jobs, email drafting/review, campaigns, sending, and reply detection. The README documents the overall workflow and queue behavior; sampled source and the SOURCE INDEX support the cited internal links, but several runtime integrations are described only at product level.

Main entry points: [`backend/graph/builder.py`](https://github.com/xiongqvq/ai_find_customer/blob/main/backend/graph/builder.py) (Hunt graph), [`backend/tools/llm_client.py`](https://github.com/xiongqvq/ai_find_customer/blob/main/backend/tools/llm_client.py) (LLM client), [`backend/api/routes.py`](https://github.com/xiongqvq/ai_find_customer/blob/main/backend/api/routes.py) (Hunt routes), [`backend/api/app.py`](https://github.com/xiongqvq/ai_find_customer/blob/main/backend/api/app.py) (FastAPI API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["User interface"]
  node_frontend["React frontend<br/>[client.ts]"]
end

subgraph group_hunt["Lead discovery"]
  node_hunt_routes["Hunt routes<br/>[routes.py]"]
  node_parse["Input parsing"]
  node_graph["Hunt graph<br/>[builder.py]"]
  node_insight["Company insight<br/>[insight_agent.py]"]
  node_keywords["Keyword generation"]
  node_search["Prospect search<br/>[search_agent.py]"]
  node_lead_extract["Lead extraction"]
  node_evaluate["Round evaluation<br/>[evaluate.py]"]
  node_search_tools["Search channels"]
end

subgraph group_automation["Job automation"]
  node_automation_routes["Automation routes"]
  node_job_queue[("Persistent job queue<br/>[job_queue.py]")]
  node_metrics["Operations metrics<br/>[metrics.py]"]
end

subgraph group_email["Email operations"]
  node_email_craft["Email drafting"]
  node_email_routes["Email routes<br/>[email_routes.py]"]
  node_email_store[("Email state store<br/>[store.py]")]
  node_scheduler["Email scheduler<br/>[scheduler.py]"]
  node_reply["Reply detection<br/>[reply_detector.py]"]
end

subgraph group_platform["Shared platform"]
  node_api["FastAPI API<br/>[app.py]"]
  node_llm["LLM client<br/>[llm_client.py]"]
  node_llm_output["LLM output validation<br/>[llm_output.py]"]
  node_cost["Cost tracking<br/>[cost_tracker.py]"]
  node_hunt_store[("Hunt persistence<br/>[hunt_store.py]")]
  node_sse["Progress stream<br/>[sse.py]"]
  node_settings["Settings API<br/>[settings_routes.py]"]
  node_settings_store[("Settings persistence<br/>[settings_store.py]")]
end

node_user(("User"))
node_smtp{{"SMTP / IMAP"}}
node_search_service{{"Search providers"}}
node_model_service{{"Model providers"}}

node_user -->|"submits tasks"| node_frontend
node_frontend -->|"calls API"| node_api
node_api -->|"routes requests"| node_hunt_routes
node_hunt_routes -->|"parses input"| node_parse
node_hunt_routes -->|"runs hunt"| node_graph
node_graph -->|"runs stage"| node_insight
node_graph -->|"runs stage"| node_keywords
node_graph -->|"runs stage"| node_search
node_graph -->|"runs stage"| node_lead_extract
node_graph -->|"runs stage"| node_evaluate
node_graph -->|"runs optional stage"| node_email_craft
node_search -->|"queries channels"| node_search_tools
node_search_tools -.->|"searches providers"| node_search_service
node_insight -.->|"uses model"| node_llm
node_keywords -.->|"uses model"| node_llm
node_lead_extract -->|"uses model"| node_llm
node_email_craft -->|"uses model"| node_llm
node_llm -->|"invokes provider"| node_model_service
node_llm -->|"records usage"| node_cost
node_email_craft -->|"validates output"| node_llm_output
node_hunt_routes -->|"saves hunts"| node_hunt_store
node_hunt_routes -->|"publishes progress"| node_sse
node_api -->|"routes requests"| node_automation_routes
node_automation_routes -->|"manages jobs"| node_job_queue
node_metrics -->|"reads job state"| node_job_queue
node_api -->|"routes requests"| node_email_routes
node_email_routes -->|"reads and writes"| node_email_store
node_email_routes -->|"runs scheduler"| node_scheduler
node_email_routes -->|"checks replies"| node_reply
node_scheduler -->|"loads campaign state"| node_email_store
node_scheduler -.->|"sends messages"| node_smtp
node_reply -.->|"checks mailbox"| node_smtp
node_api -->|"routes settings"| node_settings
node_settings -->|"persists settings"| node_settings_store
node_settings -->|"tests connectivity"| node_smtp

click node_frontend "https://github.com/xiongqvq/ai_find_customer/blob/main/frontend/src/api/client.ts"
click node_api "https://github.com/xiongqvq/ai_find_customer/blob/main/backend/api/app.py"
click node_hunt_routes "https://github.com/xiongqvq/ai_find_customer/blob/main/backend/api/routes.py"
click node_parse "https://github.com/xiongqvq/ai_find_customer/blob/main/backend/agents/parse_description_agent.py"
click node_graph "https://github.com/xiongqvq/ai_find_customer/blob/main/backend/graph/builder.py"
click node_insight "https://github.com/xiongqvq/ai_find_customer/blob/main/backend/agents/insight_agent.py"
click node_keywords "https://github.com/xiongqvq/ai_find_customer/blob/main/backend/agents/keyword_gen_agent.py"
click node_search "https://github.com/xiongqvq/ai_find_customer/blob/main/backend/agents/search_agent.py"
click node_lead_extract "https://github.com/xiongqvq/ai_find_customer/blob/main/backend/agents/lead_extract_agent.py"
click node_evaluate "https://github.com/xiongqvq/ai_find_customer/blob/main/backend/graph/evaluate.py"
click node_email_craft "https://github.com/xiongqvq/ai_find_customer/blob/main/backend/agents/email_craft_agent.py"
click node_search_tools "https://github.com/xiongqvq/ai_find_customer/blob/main/backend/tools/google_maps_search.py"
click node_llm "https://github.com/xiongqvq/ai_find_customer/blob/main/backend/tools/llm_client.py"
click node_llm_output "https://github.com/xiongqvq/ai_find_customer/blob/main/backend/tools/llm_output.py"
click node_cost "https://github.com/xiongqvq/ai_find_customer/blob/main/backend/observability/cost_tracker.py"
click node_hunt_store "https://github.com/xiongqvq/ai_find_customer/blob/main/backend/api/hunt_store.py"
click node_sse "https://github.com/xiongqvq/ai_find_customer/blob/main/backend/api/sse.py"
click node_automation_routes "https://github.com/xiongqvq/ai_find_customer/blob/main/backend/api/automation_routes.py"
click node_job_queue "https://github.com/xiongqvq/ai_find_customer/blob/main/backend/automation/job_queue.py"
click node_metrics "https://github.com/xiongqvq/ai_find_customer/blob/main/backend/automation/metrics.py"
click node_email_routes "https://github.com/xiongqvq/ai_find_customer/blob/main/backend/api/email_routes.py"
click node_email_store "https://github.com/xiongqvq/ai_find_customer/blob/main/backend/emailing/store.py"
click node_scheduler "https://github.com/xiongqvq/ai_find_customer/blob/main/backend/emailing/scheduler.py"
click node_reply "https://github.com/xiongqvq/ai_find_customer/blob/main/backend/emailing/reply_detector.py"
click node_settings "https://github.com/xiongqvq/ai_find_customer/blob/main/backend/api/settings_routes.py"
click node_settings_store "https://github.com/xiongqvq/ai_find_customer/blob/main/backend/config/settings_store.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_frontend,node_user toneBlue
class node_hunt_routes,node_parse,node_graph,node_insight,node_keywords,node_search,node_lead_extract,node_evaluate,node_search_tools toneAmber
class node_automation_routes,node_job_queue,node_metrics toneMint
class node_email_craft,node_email_routes,node_email_store,node_scheduler,node_reply toneRose
class node_api,node_llm,node_llm_output,node_cost,node_hunt_store,node_sse,node_settings,node_settings_store,node_smtp,node_search_service,node_model_service toneIndigo
```

## Components

### User interface

- [React frontend](https://github.com/xiongqvq/ai_find_customer/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`

### Lead discovery

- [Hunt routes](https://github.com/xiongqvq/ai_find_customer/blob/main/backend/api/routes.py): `backend/api/routes.py`
- [Input parsing](https://github.com/xiongqvq/ai_find_customer/blob/main/backend/agents/parse_description_agent.py): `backend/agents/parse_description_agent.py`
- [Hunt graph](https://github.com/xiongqvq/ai_find_customer/blob/main/backend/graph/builder.py): `backend/graph/builder.py`
- [Company insight](https://github.com/xiongqvq/ai_find_customer/blob/main/backend/agents/insight_agent.py): `backend/agents/insight_agent.py`
- [Keyword generation](https://github.com/xiongqvq/ai_find_customer/blob/main/backend/agents/keyword_gen_agent.py): `backend/agents/keyword_gen_agent.py`
- [Prospect search](https://github.com/xiongqvq/ai_find_customer/blob/main/backend/agents/search_agent.py): `backend/agents/search_agent.py`
- [Lead extraction](https://github.com/xiongqvq/ai_find_customer/blob/main/backend/agents/lead_extract_agent.py): `backend/agents/lead_extract_agent.py`
- [Round evaluation](https://github.com/xiongqvq/ai_find_customer/blob/main/backend/graph/evaluate.py): `backend/graph/evaluate.py`
- [Search channels](https://github.com/xiongqvq/ai_find_customer/blob/main/backend/tools/google_maps_search.py): `backend/tools/google_maps_search.py`

### Job automation

- [Automation routes](https://github.com/xiongqvq/ai_find_customer/blob/main/backend/api/automation_routes.py): `backend/api/automation_routes.py`
- [Persistent job queue](https://github.com/xiongqvq/ai_find_customer/blob/main/backend/automation/job_queue.py): `backend/automation/job_queue.py`
- [Operations metrics](https://github.com/xiongqvq/ai_find_customer/blob/main/backend/automation/metrics.py): `backend/automation/metrics.py`

### Email operations

- [Email drafting](https://github.com/xiongqvq/ai_find_customer/blob/main/backend/agents/email_craft_agent.py): `backend/agents/email_craft_agent.py`
- [Email routes](https://github.com/xiongqvq/ai_find_customer/blob/main/backend/api/email_routes.py): `backend/api/email_routes.py`
- [Email state store](https://github.com/xiongqvq/ai_find_customer/blob/main/backend/emailing/store.py): `backend/emailing/store.py`
- [Email scheduler](https://github.com/xiongqvq/ai_find_customer/blob/main/backend/emailing/scheduler.py): `backend/emailing/scheduler.py`
- [Reply detection](https://github.com/xiongqvq/ai_find_customer/blob/main/backend/emailing/reply_detector.py): `backend/emailing/reply_detector.py`

### Shared platform

- [FastAPI API](https://github.com/xiongqvq/ai_find_customer/blob/main/backend/api/app.py): `backend/api/app.py`
- [LLM client](https://github.com/xiongqvq/ai_find_customer/blob/main/backend/tools/llm_client.py): `backend/tools/llm_client.py`
- [LLM output validation](https://github.com/xiongqvq/ai_find_customer/blob/main/backend/tools/llm_output.py): `backend/tools/llm_output.py`
- [Cost tracking](https://github.com/xiongqvq/ai_find_customer/blob/main/backend/observability/cost_tracker.py): `backend/observability/cost_tracker.py`
- [Hunt persistence](https://github.com/xiongqvq/ai_find_customer/blob/main/backend/api/hunt_store.py): `backend/api/hunt_store.py`
- [Progress stream](https://github.com/xiongqvq/ai_find_customer/blob/main/backend/api/sse.py): `backend/api/sse.py`
- [Settings API](https://github.com/xiongqvq/ai_find_customer/blob/main/backend/api/settings_routes.py): `backend/api/settings_routes.py`
- [Settings persistence](https://github.com/xiongqvq/ai_find_customer/blob/main/backend/config/settings_store.py): `backend/config/settings_store.py`

### Other components

- **User**
- **SMTP / IMAP**
- **Search providers**
- **Model providers**

## Connections

- User → React frontend: submits tasks (evidence: `README.md`)
- React frontend → FastAPI API: calls API (evidence: `README.md`)
- FastAPI API → Hunt routes: routes requests (evidence: `backend/api/app.py`)
- Hunt routes → Input parsing: parses input (evidence: `backend/api/routes.py`)
- Hunt routes → Hunt graph: runs hunt (evidence: `backend/api/routes.py`)
- Hunt graph → Company insight: runs stage (evidence: `README.md`)
- Hunt graph → Keyword generation: runs stage (evidence: `README.md`)
- Hunt graph → Prospect search: runs stage (evidence: `README.md`)
- Hunt graph → Lead extraction: runs stage (evidence: `README.md`)
- Hunt graph → Round evaluation: runs stage (evidence: `README.md`)
- Hunt graph → Email drafting: runs optional stage (evidence: `README.md`)
- Prospect search → Search channels: queries channels (evidence: `backend/agents/search_agent.py`)
- Search channels → Search providers: searches providers (evidence: `README.md`)
- Company insight → LLM client: uses model (evidence: `README.md`)
- Keyword generation → LLM client: uses model (evidence: `README.md`)
- Lead extraction → LLM client: uses model (evidence: `backend/agents/lead_extract_agent.py`)
- Email drafting → LLM client: uses model (evidence: `backend/agents/email_craft_agent.py`)
- LLM client → Model providers: invokes provider (evidence: `backend/tools/llm_client.py`)
- LLM client → Cost tracking: records usage (evidence: `backend/tools/llm_client.py`)
- Email drafting → LLM output validation: validates output (evidence: `backend/agents/email_craft_agent.py`)
- Hunt routes → Hunt persistence: saves hunts (evidence: `backend/api/routes.py`)
- Hunt routes → Progress stream: publishes progress (evidence: `backend/api/routes.py`)
- FastAPI API → Automation routes: routes requests (evidence: `backend/api/app.py`)
- Automation routes → Persistent job queue: manages jobs (evidence: `backend/api/automation_routes.py`)
- Operations metrics → Persistent job queue: reads job state (evidence: `backend/automation/metrics.py`)
- FastAPI API → Email routes: routes requests (evidence: `backend/api/app.py`)
- Email routes → Email state store: reads and writes (evidence: `backend/api/email_routes.py`)
- Email routes → Email scheduler: runs scheduler (evidence: `backend/api/email_routes.py`)
- Email routes → Reply detection: checks replies (evidence: `backend/api/email_routes.py`)
- Email scheduler → Email state store: loads campaign state (evidence: `backend/emailing/scheduler.py`)
- Email scheduler → SMTP / IMAP: sends messages (evidence: `README.md`)
- Reply detection → SMTP / IMAP: checks mailbox (evidence: `README.md`)
- FastAPI API → Settings API: routes settings (evidence: `backend/api/app.py`)
- Settings API → Settings persistence: persists settings (evidence: `backend/api/settings_routes.py`)
- Settings API → SMTP / IMAP: tests connectivity (evidence: `backend/api/settings_routes.py`)
