# ahmed2806/ai-client-acquisition-agent architecture

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

- Interactive diagram: https://gitdiagram.com/ahmed2806/ai-client-acquisition-agent
- Repository: https://github.com/ahmed2806/ai-client-acquisition-agent

## Overview

LeadPilot AI discovers and researches B2B businesses, evaluates product fit, qualifies opportunities, and presents saved leads for human review. The main workflow runs from the React discovery/chat interface through FastAPI into the multi-category or single-category agent pipeline, then to PostgreSQL and the lead dashboard. README documents Google Places, website research, local/hosted LLM inference, deterministic scoring, qualification, and review capabilities. Arrows are limited to relationships shown in excerpts or README; some dashboard-to-API calls and unsampled route details are not fully evidenced.

Main entry points: [`backend/app/agents/pipeline_agent.py`](https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/backend/app/agents/pipeline_agent.py) (Lead Pipeline), [`backend/app/main.py`](https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/backend/app/main.py) (FastAPI Application), [`backend/app/database.py`](https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/backend/app/database.py) (Database Session), [`frontend/src/App.tsx`](https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/frontend/src/App.tsx) (Workspace Router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Web Experience"]
  node_app["Workspace Router<br/>[App.tsx]"]
  node_discovery_ui["Discovery Page<br/>[DiscoveryPage.tsx]"]
  node_chat_ui["AI Chat Page<br/>[ChatPage.tsx]"]
  node_leads_ui["Lead Dashboard<br/>[LeadsPage.tsx]"]
  node_presence["Digital Presence"]
  node_api_client["API Client<br/>[api.ts]"]
end

subgraph group_api["API and Review"]
  node_fastapi["FastAPI Application<br/>[main.py]"]
  node_chat_route["Chat Endpoint<br/>[chat.py]"]
  node_leads_route["Lead Endpoints<br/>[leads.py]"]
  node_reviews_route["Review Endpoints<br/>[reviews.py]"]
  node_evidence_route["Evidence Endpoints<br/>[evidence.py]"]
end

subgraph group_workflow["Discovery Workflow"]
  node_multi_pipeline["Multi-Category Flow"]
  node_pipeline["Lead Pipeline<br/>[pipeline_agent.py]"]
  node_discovery["Business Discovery<br/>[discovery_agent.py]"]
  node_places["Google Places<br/>[google_places.py]"]
end

subgraph group_analysis["Research and Qualification"]
  node_website["Website Enrichment"]
  node_social_search["Social Search<br/>[social_search.py]"]
  node_social_verify["Profile Verification"]
  node_social_research["Social Research<br/>[social_research.py]"]
  node_research["Company Research<br/>[research_agent.py]"]
  node_opportunity["Opportunity Analysis"]
  node_inference["Batch Inference<br/>[batch_inference.py]"]
  node_llm["LLM Provider<br/>[llm.py]"]
  node_scoring["Fit Scoring<br/>[lead_scoring.py]"]
  node_qualification["Lead Qualification"]
end

subgraph group_persistence["Lead Storage"]
  node_persistence_service["Lead Persistence"]
  node_crud["Company CRUD<br/>[crud.py]"]
  node_db["Database Session<br/>[database.py]"]
  node_models[("Company and Scores<br/>[models.py]")]
  node_evidence_store["Evidence Store<br/>[evidence_store.py]"]
end

node_user(("Sales Researcher"))
node_postgres[("PostgreSQL")]
node_google["Google Places API"]
node_website_ext["Public Websites"]

node_user -->|"uses"| node_app
node_app -->|"routes to"| node_discovery_ui
node_app -->|"routes to"| node_chat_ui
node_app -->|"routes to"| node_leads_ui
node_discovery_ui -->|"requests via"| node_api_client
node_chat_ui -->|"sends chat"| node_api_client
node_leads_ui -->|"requests via"| node_api_client
node_discovery_ui -->|"renders"| node_presence
node_api_client -->|"HTTP requests"| node_fastapi
node_fastapi -->|"registers"| node_chat_route
node_fastapi -->|"registers"| node_leads_route
node_fastapi -->|"registers"| node_reviews_route
node_fastapi -->|"registers"| node_evidence_route
node_fastapi -->|"calls"| node_discovery
node_fastapi -->|"calls"| node_pipeline
node_chat_route -->|"invokes"| node_multi_pipeline
node_chat_route -->|"uses"| node_llm
node_multi_pipeline -->|"runs searches"| node_discovery
node_multi_pipeline -->|"processes leads"| node_pipeline
node_discovery -->|"queries"| node_places
node_places -->|"searches businesses"| node_google
node_pipeline -->|"looks up websites"| node_places
node_pipeline -->|"enriches sites"| node_website
node_website -->|"fetches content"| node_website_ext
node_pipeline -->|"searches profiles"| node_social_search
node_pipeline -->|"builds research"| node_social_research
node_website -->|"verifies profiles"| node_social_verify
node_social_search -->|"candidate checks"| node_social_verify
node_social_research -->|"uses verification"| node_social_verify
node_pipeline -->|"batches research"| node_research
node_pipeline -->|"batches assessment"| node_opportunity
node_research -->|"runs batches"| node_inference
node_opportunity -->|"runs batches"| node_inference
node_inference -->|"invokes model"| node_llm
node_opportunity -->|"calculates fit"| node_scoring
node_pipeline -.->|"qualifies leads"| node_qualification
node_pipeline -->|"saves eligible"| node_persistence_service
node_leads_route -->|"opens session"| node_db
node_leads_route -->|"reads records"| node_models
node_reviews_route -->|"opens session"| node_db
node_reviews_route -->|"checks evaluations"| node_models
node_evidence_route -->|"uses store"| node_evidence_store
node_evidence_store -->|"uses session"| node_db
node_persistence_service -->|"uses session"| node_db
node_persistence_service -->|"writes lead data"| node_models
node_crud -->|"manages companies"| node_models
node_db -->|"connects"| node_postgres
node_leads_ui -.->|"shows presence"| node_presence

click node_app "https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/frontend/src/App.tsx"
click node_discovery_ui "https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/frontend/src/pages/DiscoveryPage.tsx"
click node_chat_ui "https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/frontend/src/pages/ChatPage.tsx"
click node_leads_ui "https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/frontend/src/pages/LeadsPage.tsx"
click node_presence "https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/frontend/src/components/discovery/DigitalPresenceCard.tsx"
click node_api_client "https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/frontend/src/services/api.ts"
click node_fastapi "https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/backend/app/main.py"
click node_chat_route "https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/backend/app/routes/chat.py"
click node_leads_route "https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/backend/app/routes/leads.py"
click node_reviews_route "https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/backend/app/routes/reviews.py"
click node_evidence_route "https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/backend/app/routes/evidence.py"
click node_multi_pipeline "https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/backend/app/agents/multi_category_pipeline.py"
click node_pipeline "https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/backend/app/agents/pipeline_agent.py"
click node_discovery "https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/backend/app/agents/discovery_agent.py"
click node_places "https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/backend/app/services/google_places.py"
click node_website "https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/backend/app/services/website_enrichment.py"
click node_social_search "https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/backend/app/services/social_search.py"
click node_social_verify "https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/backend/app/services/social_verification.py"
click node_social_research "https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/backend/app/services/social_research.py"
click node_research "https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/backend/app/agents/research_agent.py"
click node_opportunity "https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/backend/app/agents/opportunity_agent.py"
click node_inference "https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/backend/app/services/batch_inference.py"
click node_llm "https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/backend/app/llm.py"
click node_scoring "https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/backend/app/services/lead_scoring.py"
click node_qualification "https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/backend/app/agents/qualification_agent.py"
click node_persistence_service "https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/backend/app/services/lead_persistence.py"
click node_crud "https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/backend/app/crud.py"
click node_db "https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/backend/app/database.py"
click node_models "https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/backend/app/models.py"
click node_evidence_store "https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/backend/app/services/evidence_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_app,node_discovery_ui,node_chat_ui,node_leads_ui,node_presence,node_api_client toneBlue
class node_fastapi,node_chat_route,node_leads_route,node_reviews_route,node_evidence_route,node_postgres toneAmber
class node_multi_pipeline,node_pipeline,node_discovery,node_places,node_google toneMint
class node_website,node_social_search,node_social_verify,node_social_research,node_research,node_opportunity,node_inference,node_llm,node_scoring,node_qualification toneRose
class node_persistence_service,node_crud,node_db,node_models,node_evidence_store,node_user,node_website_ext toneIndigo
```

## Components

### Web Experience

- [Workspace Router](https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Discovery Page](https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/frontend/src/pages/DiscoveryPage.tsx): `frontend/src/pages/DiscoveryPage.tsx`
- [AI Chat Page](https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/frontend/src/pages/ChatPage.tsx): `frontend/src/pages/ChatPage.tsx`
- [Lead Dashboard](https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/frontend/src/pages/LeadsPage.tsx): `frontend/src/pages/LeadsPage.tsx`
- [Digital Presence](https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/frontend/src/components/discovery/DigitalPresenceCard.tsx): `frontend/src/components/discovery/DigitalPresenceCard.tsx`
- [API Client](https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`

### API and Review

- [FastAPI Application](https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/backend/app/main.py): `backend/app/main.py`
- [Chat Endpoint](https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/backend/app/routes/chat.py): `backend/app/routes/chat.py`
- [Lead Endpoints](https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/backend/app/routes/leads.py): `backend/app/routes/leads.py`
- [Review Endpoints](https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/backend/app/routes/reviews.py): `backend/app/routes/reviews.py`
- [Evidence Endpoints](https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/backend/app/routes/evidence.py): `backend/app/routes/evidence.py`

### Discovery Workflow

- [Multi-Category Flow](https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/backend/app/agents/multi_category_pipeline.py): `backend/app/agents/multi_category_pipeline.py`
- [Lead Pipeline](https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/backend/app/agents/pipeline_agent.py): `backend/app/agents/pipeline_agent.py`
- [Business Discovery](https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/backend/app/agents/discovery_agent.py): `backend/app/agents/discovery_agent.py`
- [Google Places](https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/backend/app/services/google_places.py): `backend/app/services/google_places.py`

### Research and Qualification

- [Website Enrichment](https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/backend/app/services/website_enrichment.py): `backend/app/services/website_enrichment.py`
- [Social Search](https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/backend/app/services/social_search.py): `backend/app/services/social_search.py`
- [Profile Verification](https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/backend/app/services/social_verification.py): `backend/app/services/social_verification.py`
- [Social Research](https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/backend/app/services/social_research.py): `backend/app/services/social_research.py`
- [Company Research](https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/backend/app/agents/research_agent.py): `backend/app/agents/research_agent.py`
- [Opportunity Analysis](https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/backend/app/agents/opportunity_agent.py): `backend/app/agents/opportunity_agent.py`
- [Batch Inference](https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/backend/app/services/batch_inference.py): `backend/app/services/batch_inference.py`
- [LLM Provider](https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/backend/app/llm.py): `backend/app/llm.py`
- [Fit Scoring](https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/backend/app/services/lead_scoring.py): `backend/app/services/lead_scoring.py`
- [Lead Qualification](https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/backend/app/agents/qualification_agent.py): `backend/app/agents/qualification_agent.py`

### Lead Storage

- [Lead Persistence](https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/backend/app/services/lead_persistence.py): `backend/app/services/lead_persistence.py`
- [Company CRUD](https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/backend/app/crud.py): `backend/app/crud.py`
- [Database Session](https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/backend/app/database.py): `backend/app/database.py`
- [Company and Scores](https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/backend/app/models.py): `backend/app/models.py`
- [Evidence Store](https://github.com/ahmed2806/ai-client-acquisition-agent/blob/main/backend/app/services/evidence_store.py): `backend/app/services/evidence_store.py`

### Other components

- **Sales Researcher**
- **PostgreSQL**
- **Google Places API**
- **Public Websites**

## Connections

- Sales Researcher → Workspace Router: uses
- Workspace Router → Discovery Page: routes to (evidence: `frontend/src/App.tsx`)
- Workspace Router → AI Chat Page: routes to (evidence: `frontend/src/App.tsx`)
- Workspace Router → Lead Dashboard: routes to (evidence: `frontend/src/App.tsx`)
- Discovery Page → API Client: requests via (evidence: `frontend/src/pages/DiscoveryPage.tsx`)
- AI Chat Page → API Client: sends chat (evidence: `frontend/src/pages/ChatPage.tsx`)
- Lead Dashboard → API Client: requests via (evidence: `frontend/src/pages/LeadsPage.tsx`)
- Discovery Page → Digital Presence: renders (evidence: `frontend/src/pages/DiscoveryPage.tsx`)
- API Client → FastAPI Application: HTTP requests (evidence: `frontend/src/services/api.ts`)
- FastAPI Application → Chat Endpoint: registers (evidence: `backend/app/main.py`)
- FastAPI Application → Lead Endpoints: registers (evidence: `backend/app/main.py`)
- FastAPI Application → Review Endpoints: registers (evidence: `backend/app/main.py`)
- FastAPI Application → Evidence Endpoints: registers (evidence: `backend/app/main.py`)
- FastAPI Application → Business Discovery: calls (evidence: `backend/app/main.py`)
- FastAPI Application → Lead Pipeline: calls (evidence: `backend/app/main.py`)
- Chat Endpoint → Multi-Category Flow: invokes (evidence: `backend/app/routes/chat.py`)
- Chat Endpoint → LLM Provider: uses (evidence: `backend/app/routes/chat.py`)
- Multi-Category Flow → Business Discovery: runs searches (evidence: `backend/app/agents/multi_category_pipeline.py`)
- Multi-Category Flow → Lead Pipeline: processes leads (evidence: `backend/app/agents/multi_category_pipeline.py`)
- Business Discovery → Google Places: queries (evidence: `backend/app/agents/discovery_agent.py`)
- Google Places → Google Places API: searches businesses
- Lead Pipeline → Google Places: looks up websites (evidence: `backend/app/agents/pipeline_agent.py`)
- Lead Pipeline → Website Enrichment: enriches sites (evidence: `backend/app/agents/pipeline_agent.py`)
- Website Enrichment → Public Websites: fetches content
- Lead Pipeline → Social Search: searches profiles (evidence: `backend/app/agents/pipeline_agent.py`)
- Lead Pipeline → Social Research: builds research (evidence: `backend/app/agents/pipeline_agent.py`)
- Website Enrichment → Profile Verification: verifies profiles (evidence: `backend/app/services/website_enrichment.py`)
- Social Search → Profile Verification: candidate checks (evidence: `backend/app/services/social_search.py`)
- Social Research → Profile Verification: uses verification (evidence: `backend/app/services/social_research.py`)
- Lead Pipeline → Company Research: batches research (evidence: `backend/app/agents/pipeline_agent.py`)
- Lead Pipeline → Opportunity Analysis: batches assessment (evidence: `backend/app/agents/pipeline_agent.py`)
- Company Research → Batch Inference: runs batches (evidence: `backend/app/agents/research_agent.py`)
- Opportunity Analysis → Batch Inference: runs batches (evidence: `backend/app/agents/opportunity_agent.py`)
- Batch Inference → LLM Provider: invokes model (evidence: `backend/app/services/batch_inference.py`)
- Opportunity Analysis → Fit Scoring: calculates fit (evidence: `backend/app/agents/opportunity_agent.py`)
- Lead Pipeline → Lead Qualification: qualifies leads (evidence: `backend/app/agents/pipeline_agent.py`)
- Lead Pipeline → Lead Persistence: saves eligible (evidence: `backend/app/agents/pipeline_agent.py`)
- Lead Endpoints → Database Session: opens session (evidence: `backend/app/routes/leads.py`)
- Lead Endpoints → Company and Scores: reads records (evidence: `backend/app/routes/leads.py`)
- Review Endpoints → Database Session: opens session (evidence: `backend/app/routes/reviews.py`)
- Review Endpoints → Company and Scores: checks evaluations (evidence: `backend/app/routes/reviews.py`)
- Evidence Endpoints → Evidence Store: uses store (evidence: `backend/app/routes/evidence.py`)
- Evidence Store → Database Session: uses session (evidence: `backend/app/services/evidence_store.py`)
- Lead Persistence → Database Session: uses session (evidence: `backend/app/services/lead_persistence.py`)
- Lead Persistence → Company and Scores: writes lead data (evidence: `backend/app/services/lead_persistence.py`)
- Company CRUD → Company and Scores: manages companies (evidence: `backend/app/crud.py`)
- Database Session → PostgreSQL: connects (evidence: `backend/app/database.py`)
- Lead Dashboard → Digital Presence: shows presence