# aisolutions-hash/ai_pitch_agent architecture

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

- Interactive diagram: https://gitdiagram.com/aisolutions-hash/ai_pitch_agent
- Repository: https://github.com/aisolutions-hash/ai_pitch_agent

## Overview

AI Sales Agent is a Django B2B sales application whose main workflow is discovering and analyzing prospects, storing contacts, generating pitches, and sending tracked campaigns. The README also documents supplier email extraction, dashboard contact management, and scheduled scraping. A separate FastAPI application and its contact, email, social, and system routers are present in the tree; the README’s migration discussion is not reliable evidence for their wiring, so only routing setup visible in `sales_fastapi/main.py` is shown. Some feature links follow README-described flows because their view implementations were not sampled.

Main entry points: [`sales_project/urls.py`](https://github.com/aisolutions-hash/ai_pitch_agent/blob/main/sales_project/urls.py) (Django request routes), [`ai_agent_pitch/auto_campaign_service.py`](https://github.com/aisolutions-hash/ai_pitch_agent/blob/main/ai_agent_pitch/auto_campaign_service.py) (Campaign runner), [`scraper/services.py`](https://github.com/aisolutions-hash/ai_pitch_agent/blob/main/scraper/services.py) (Scrape and analyze), [`dashboard/views.py`](https://github.com/aisolutions-hash/ai_pitch_agent/blob/main/dashboard/views.py) (Dashboard and contacts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Django application"]
  node_django["Django request routes<br/>[urls.py]"]
  node_dashboard["Dashboard and contacts<br/>[views.py]"]
  node_django_models[("Django records<br/>[models.py]")]
end

subgraph group_prospect["Prospect discovery"]
  node_extractor["Supplier extractor<br/>[views.py]"]
  node_scrape_views["Scraper endpoints<br/>[views.py]"]
  node_scrape_service["Scrape and analyze<br/>[services.py]"]
end

subgraph group_campaign["Pitch and campaigns"]
  node_pitch_generator["Pitch generator<br/>[views.py]"]
  node_pitch_utils["Pitch utilities<br/>[utils.py]"]
  node_campaign_views["Campaign endpoints<br/>[views.py]"]
  node_auto_campaign["Campaign runner"]
  node_personalization["Email personalization<br/>[gemma_service.py]"]
end

subgraph group_integrations["External services"]
  node_gcs["Contact and run storage<br/>[gcs.py]"]
  node_sheets["Google Sheets<br/>[sheets_util.py]"]
  node_gmail["Gmail integration<br/>[gmail.py]"]
  node_gemini(("Gemini AI"))
  node_serpapi(("SerpAPI"))
  node_mail(("Email provider"))
end

subgraph group_api["FastAPI application"]
  node_fastapi["FastAPI app<br/>[main.py]"]
  node_api_routers["API routers"]
  node_api_services["Integration services<br/>[services.py]"]
  node_api_db[("API database<br/>[database.py]")]
end

node_browser(("Browser user"))
node_scheduler(("Cloud Scheduler"))

node_browser -->|"sends requests"| node_django
node_django -->|"routes dashboard"| node_dashboard
node_django -->|"routes extraction"| node_extractor
node_django -->|"routes scraping"| node_scrape_views
node_django -->|"routes generation"| node_pitch_generator
node_django -->|"routes campaigns"| node_campaign_views
node_dashboard -->|"manages contacts"| node_gcs
node_dashboard -->|"reads and writes"| node_django_models
node_extractor -->|"exports suppliers"| node_sheets
node_scrape_views -->|"runs scraping"| node_scrape_service
node_scheduler -->|"triggers scheduled run"| node_scrape_views
node_scrape_service -->|"searches profiles"| node_serpapi
node_scrape_service -->|"analyzes profiles"| node_gemini
node_scrape_service -->|"upserts contacts"| node_gcs
node_scrape_service -->|"exports profiles"| node_sheets
node_pitch_generator -->|"uses utilities"| node_pitch_utils
node_pitch_generator -->|"stores pitch records"| node_django_models
node_campaign_views -->|"starts campaign"| node_auto_campaign
node_auto_campaign -->|"loads contacts and saves progress"| node_gcs
node_auto_campaign -->|"records campaign results"| node_django_models
node_auto_campaign -->|"personalizes messages"| node_personalization
node_auto_campaign -->|"resolves sender"| node_gmail
node_auto_campaign -->|"sends campaign email"| node_mail
node_personalization -.->|"requests generation"| node_gemini
node_fastapi -->|"registers routers"| node_api_routers
node_fastapi -->|"initializes database"| node_api_db
node_api_services -->|"sends SMTP mail"| node_mail

click node_django "https://github.com/aisolutions-hash/ai_pitch_agent/blob/main/sales_project/urls.py"
click node_dashboard "https://github.com/aisolutions-hash/ai_pitch_agent/blob/main/dashboard/views.py"
click node_django_models "https://github.com/aisolutions-hash/ai_pitch_agent/blob/main/ai_agent_pitch/models.py"
click node_extractor "https://github.com/aisolutions-hash/ai_pitch_agent/blob/main/extractor/views.py"
click node_scrape_views "https://github.com/aisolutions-hash/ai_pitch_agent/blob/main/scraper/views.py"
click node_scrape_service "https://github.com/aisolutions-hash/ai_pitch_agent/blob/main/scraper/services.py"
click node_pitch_generator "https://github.com/aisolutions-hash/ai_pitch_agent/blob/main/pitch_generator/views.py"
click node_pitch_utils "https://github.com/aisolutions-hash/ai_pitch_agent/blob/main/pitch_generator/utils.py"
click node_campaign_views "https://github.com/aisolutions-hash/ai_pitch_agent/blob/main/ai_agent_pitch/views.py"
click node_auto_campaign "https://github.com/aisolutions-hash/ai_pitch_agent/blob/main/ai_agent_pitch/auto_campaign_service.py"
click node_personalization "https://github.com/aisolutions-hash/ai_pitch_agent/blob/main/ai_agent_pitch/gemma_service.py"
click node_gcs "https://github.com/aisolutions-hash/ai_pitch_agent/blob/main/dashboard/gcs.py"
click node_sheets "https://github.com/aisolutions-hash/ai_pitch_agent/blob/main/scraper/sheets_util.py"
click node_gmail "https://github.com/aisolutions-hash/ai_pitch_agent/blob/main/dashboard/gmail.py"
click node_fastapi "https://github.com/aisolutions-hash/ai_pitch_agent/blob/main/sales_fastapi/main.py"
click node_api_routers "https://github.com/aisolutions-hash/ai_pitch_agent/tree/main/sales_fastapi/routers"
click node_api_services "https://github.com/aisolutions-hash/ai_pitch_agent/blob/main/sales_fastapi/services.py"
click node_api_db "https://github.com/aisolutions-hash/ai_pitch_agent/blob/main/sales_fastapi/database.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_django,node_dashboard,node_django_models,node_browser toneBlue
class node_extractor,node_scrape_views,node_scrape_service toneAmber
class node_pitch_generator,node_pitch_utils,node_campaign_views,node_auto_campaign,node_personalization toneMint
class node_gcs,node_sheets,node_gmail,node_gemini,node_serpapi,node_mail,node_scheduler toneRose
class node_fastapi,node_api_routers,node_api_services,node_api_db toneIndigo
```

## Components

### Django application

- [Django request routes](https://github.com/aisolutions-hash/ai_pitch_agent/blob/main/sales_project/urls.py): `sales_project/urls.py`
- [Dashboard and contacts](https://github.com/aisolutions-hash/ai_pitch_agent/blob/main/dashboard/views.py): `dashboard/views.py`
- [Django records](https://github.com/aisolutions-hash/ai_pitch_agent/blob/main/ai_agent_pitch/models.py): `ai_agent_pitch/models.py`

### Prospect discovery

- [Supplier extractor](https://github.com/aisolutions-hash/ai_pitch_agent/blob/main/extractor/views.py): `extractor/views.py`
- [Scraper endpoints](https://github.com/aisolutions-hash/ai_pitch_agent/blob/main/scraper/views.py): `scraper/views.py`
- [Scrape and analyze](https://github.com/aisolutions-hash/ai_pitch_agent/blob/main/scraper/services.py): `scraper/services.py`

### Pitch and campaigns

- [Pitch generator](https://github.com/aisolutions-hash/ai_pitch_agent/blob/main/pitch_generator/views.py): `pitch_generator/views.py`
- [Pitch utilities](https://github.com/aisolutions-hash/ai_pitch_agent/blob/main/pitch_generator/utils.py): `pitch_generator/utils.py`
- [Campaign endpoints](https://github.com/aisolutions-hash/ai_pitch_agent/blob/main/ai_agent_pitch/views.py): `ai_agent_pitch/views.py`
- [Campaign runner](https://github.com/aisolutions-hash/ai_pitch_agent/blob/main/ai_agent_pitch/auto_campaign_service.py): `ai_agent_pitch/auto_campaign_service.py`
- [Email personalization](https://github.com/aisolutions-hash/ai_pitch_agent/blob/main/ai_agent_pitch/gemma_service.py): `ai_agent_pitch/gemma_service.py`

### External services

- [Contact and run storage](https://github.com/aisolutions-hash/ai_pitch_agent/blob/main/dashboard/gcs.py): `dashboard/gcs.py`
- [Google Sheets](https://github.com/aisolutions-hash/ai_pitch_agent/blob/main/scraper/sheets_util.py): `scraper/sheets_util.py`
- [Gmail integration](https://github.com/aisolutions-hash/ai_pitch_agent/blob/main/dashboard/gmail.py): `dashboard/gmail.py`
- **Gemini AI**
- **SerpAPI**
- **Email provider**

### FastAPI application

- [FastAPI app](https://github.com/aisolutions-hash/ai_pitch_agent/blob/main/sales_fastapi/main.py): `sales_fastapi/main.py`
- [API routers](https://github.com/aisolutions-hash/ai_pitch_agent/tree/main/sales_fastapi/routers): `sales_fastapi/routers`
- [Integration services](https://github.com/aisolutions-hash/ai_pitch_agent/blob/main/sales_fastapi/services.py): `sales_fastapi/services.py`
- [API database](https://github.com/aisolutions-hash/ai_pitch_agent/blob/main/sales_fastapi/database.py): `sales_fastapi/database.py`

### Other components

- **Browser user**
- **Cloud Scheduler**

## Connections

- Browser user → Django request routes: sends requests
- Django request routes → Dashboard and contacts: routes dashboard
- Django request routes → Supplier extractor: routes extraction
- Django request routes → Scraper endpoints: routes scraping
- Django request routes → Pitch generator: routes generation
- Django request routes → Campaign endpoints: routes campaigns
- Dashboard and contacts → Contact and run storage: manages contacts
- Dashboard and contacts → Django records: reads and writes
- Supplier extractor → Google Sheets: exports suppliers
- Scraper endpoints → Scrape and analyze: runs scraping
- Cloud Scheduler → Scraper endpoints: triggers scheduled run
- Scrape and analyze → SerpAPI: searches profiles
- Scrape and analyze → Gemini AI: analyzes profiles
- Scrape and analyze → Contact and run storage: upserts contacts
- Scrape and analyze → Google Sheets: exports profiles
- Pitch generator → Pitch utilities: uses utilities
- Pitch generator → Django records: stores pitch records
- Campaign endpoints → Campaign runner: starts campaign
- Campaign runner → Contact and run storage: loads contacts and saves progress
- Campaign runner → Django records: records campaign results
- Campaign runner → Email personalization: personalizes messages
- Campaign runner → Gmail integration: resolves sender
- Campaign runner → Email provider: sends campaign email
- Email personalization → Gemini AI: requests generation
- FastAPI app → API routers: registers routers
- FastAPI app → API database: initializes database
- Integration services → Email provider: sends SMTP mail