# shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform architecture

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

- Interactive diagram: https://gitdiagram.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform
- Repository: https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform

## Overview

This is a lead-intelligence CRM with a human-reviewed outreach workflow: opportunities are discovered and normalized, leads enter a CRM, contacts can be enriched and verified, quality is scored, and AI drafts are reviewed before any dispatch. The graph preserves documented AI, campaign, suppression, webhook, and error-center capabilities. Evidence is limited to the README, source index, and sampled excerpts; unverified subsystem links are dashed.

Main entry points: [`backend/app/main.py`](https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/blob/main/backend/app/main.py) (API router), [`frontend/src/App.jsx`](https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/blob/main/frontend/src/App.jsx) (CRM dashboard), [`frontend/src/api/client.js`](https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/blob/main/frontend/src/api/client.js) (API client), [`backend/app/services/enrichment_service.py`](https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/blob/main/backend/app/services/enrichment_service.py) (Enrichment service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["CRM dashboard"]
  node_dashboard["CRM dashboard<br/>[App.jsx]"]
  node_lead_views["Lead pipeline<br/>[index.jsx]"]
  node_enrichment_views["Enrichment queue<br/>[index.jsx]"]
  node_approval_view["Draft approval<br/>[Approval.jsx]"]
  node_api_client["API client<br/>[client.js]"]
end

subgraph group_api["Backend API"]
  node_api_entry["API router<br/>[main.py]"]
  node_lead_routes["Lead routes<br/>[leads.py]"]
  node_campaign_routes["Campaign routes<br/>[campaigns.py]"]
  node_approval_routes["Approval routes<br/>[approvals.py]"]
  node_webhook_routes["Webhook routes<br/>[webhooks.py]"]
  node_error_routes["Error center<br/>[error_center.py]"]
  node_lead_repo["Lead repository<br/>[leads_repo.py]"]
  node_audit["Audit service<br/>[audit_service.py]"]
end

subgraph group_automation["Lead discovery"]
  node_scraper_registry["Source registry<br/>[registry.py]"]
  node_scraper_runner["Scraper runner<br/>[runner.py]"]
  node_scraper_base["Scraper interface<br/>[base.py]"]
  node_normalizer["Lead normalizer<br/>[normalizer.py]"]
end

subgraph group_intelligence["AI intelligence"]
  node_experience_parser["Experience parser"]
  node_ai_extractors["Lead extraction"]
  node_ai_scoring["Score explanation<br/>[score_explainer.py]"]
  node_ai_drafting["Gemini drafting<br/>[gemini_client.py]"]
  node_ai_guards["Draft safety checks"]
  node_ai_diagnosis["Error diagnosis<br/>[error_diagnoser.py]"]
end

subgraph group_data["Contact operations"]
  node_enrichment_service["Enrichment service"]
  node_verification_service["Verification service"]
  node_scoring_service["Quality scoring<br/>[scoring_service.py]"]
  node_postgres[("PostgreSQL CRM<br/>[db.py]")]
end

node_researcher(("Researcher"))
node_campaign_user(("Campaign manager"))
node_contactout["ContactOut"]
node_snov["Snov.io"]
node_email_verifier["Email verifier"]
node_gemini["Google Gemini"]

node_researcher -.->|"uses dashboard"| node_dashboard
node_dashboard -->|"routes to"| node_lead_views
node_dashboard -->|"routes to"| node_enrichment_views
node_dashboard -->|"routes to"| node_approval_view
node_lead_views -.->|"requests data"| node_api_client
node_enrichment_views -.->|"requests data"| node_api_client
node_approval_view -.->|"submits decisions"| node_api_client
node_api_client -.->|"HTTP requests"| node_api_entry
node_api_entry -->|"mounts"| node_lead_routes
node_api_entry -->|"mounts"| node_campaign_routes
node_api_entry -->|"mounts"| node_approval_routes
node_api_entry -->|"mounts"| node_webhook_routes
node_api_entry -->|"mounts"| node_error_routes
node_lead_routes -.->|"uses repository"| node_lead_repo
node_campaign_user -.->|"reviews drafts"| node_approval_view
node_approval_routes -.->|"records decisions"| node_audit
node_scraper_registry -->|"resolves class"| node_scraper_base
node_scraper_registry -->|"reads enabled sources"| node_postgres
node_scraper_runner -.->|"launches scraper"| node_scraper_registry
node_scraper_runner -.->|"runs extraction"| node_scraper_base
node_scraper_base -.->|"normalizes results"| node_normalizer
node_normalizer -.->|"supplies lead records"| node_lead_repo
node_experience_parser -.->|"supports extraction"| node_ai_extractors
node_lead_repo -.->|"provides lead data"| node_scoring_service
node_scoring_service -.->|"explains score"| node_ai_scoring
node_enrichment_service -->|"reads and writes"| node_postgres
node_enrichment_service -.->|"optional lookup"| node_contactout
node_enrichment_service -.->|"optional lookup"| node_snov
node_verification_service -.->|"verifies email"| node_email_verifier
node_verification_service -.->|"stores result"| node_postgres
node_ai_drafting -.->|"generates drafts"| node_gemini
node_ai_guards -.->|"checks output"| node_ai_drafting
node_error_routes -.->|"requests diagnosis"| node_ai_diagnosis

click node_dashboard "https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/blob/main/frontend/src/App.jsx"
click node_lead_views "https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/blob/main/frontend/src/pages/LeadPipeline/index.jsx"
click node_enrichment_views "https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/blob/main/frontend/src/pages/EnrichmentQueue/index.jsx"
click node_approval_view "https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/blob/main/frontend/src/pages/CampaignManager/Approval.jsx"
click node_api_client "https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/blob/main/frontend/src/api/client.js"
click node_api_entry "https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/blob/main/backend/app/main.py"
click node_lead_routes "https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/blob/main/backend/app/api/v1/leads.py"
click node_campaign_routes "https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/blob/main/backend/app/api/v1/campaigns.py"
click node_approval_routes "https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/blob/main/backend/app/api/v1/approvals.py"
click node_webhook_routes "https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/blob/main/backend/app/api/v1/webhooks.py"
click node_error_routes "https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/blob/main/backend/app/api/v1/error_center.py"
click node_lead_repo "https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/blob/main/backend/app/repositories/leads_repo.py"
click node_audit "https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/blob/main/backend/app/services/audit_service.py"
click node_scraper_registry "https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/blob/main/automation/scrapers/registry.py"
click node_scraper_runner "https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/blob/main/automation/scrapers/runner.py"
click node_scraper_base "https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/blob/main/automation/scrapers/base.py"
click node_normalizer "https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/blob/main/automation/scrapers/normalizer.py"
click node_experience_parser "https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/blob/main/ai/extraction/experience_parser.py"
click node_ai_extractors "https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/tree/main/ai/extraction"
click node_ai_scoring "https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/blob/main/ai/explain/score_explainer.py"
click node_ai_drafting "https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/blob/main/ai/gemini_client.py"
click node_ai_guards "https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/tree/main/ai/validators"
click node_ai_diagnosis "https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/blob/main/ai/diagnosis/error_diagnoser.py"
click node_enrichment_service "https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/blob/main/backend/app/services/enrichment_service.py"
click node_verification_service "https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/blob/main/backend/app/services/verification_service.py"
click node_scoring_service "https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/blob/main/backend/app/services/scoring_service.py"
click node_postgres "https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/blob/main/backend/app/core/db.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_lead_views,node_enrichment_views,node_approval_view,node_api_client toneBlue
class node_api_entry,node_lead_routes,node_campaign_routes,node_approval_routes,node_webhook_routes,node_error_routes,node_lead_repo,node_audit toneAmber
class node_scraper_registry,node_scraper_runner,node_scraper_base,node_normalizer toneMint
class node_experience_parser,node_ai_extractors,node_ai_scoring,node_ai_drafting,node_ai_guards,node_ai_diagnosis toneRose
class node_enrichment_service,node_verification_service,node_scoring_service,node_postgres,node_researcher,node_campaign_user,node_contactout,node_snov,node_email_verifier,node_gemini toneIndigo
```

## Components

### CRM dashboard

- [CRM dashboard](https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Lead pipeline](https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/blob/main/frontend/src/pages/LeadPipeline/index.jsx): `frontend/src/pages/LeadPipeline/index.jsx`
- [Enrichment queue](https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/blob/main/frontend/src/pages/EnrichmentQueue/index.jsx): `frontend/src/pages/EnrichmentQueue/index.jsx`
- [Draft approval](https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/blob/main/frontend/src/pages/CampaignManager/Approval.jsx): `frontend/src/pages/CampaignManager/Approval.jsx`
- [API client](https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/blob/main/frontend/src/api/client.js): `frontend/src/api/client.js`

### Backend API

- [API router](https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/blob/main/backend/app/main.py): `backend/app/main.py`
- [Lead routes](https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/blob/main/backend/app/api/v1/leads.py): `backend/app/api/v1/leads.py`
- [Campaign routes](https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/blob/main/backend/app/api/v1/campaigns.py): `backend/app/api/v1/campaigns.py`
- [Approval routes](https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/blob/main/backend/app/api/v1/approvals.py): `backend/app/api/v1/approvals.py`
- [Webhook routes](https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/blob/main/backend/app/api/v1/webhooks.py): `backend/app/api/v1/webhooks.py`
- [Error center](https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/blob/main/backend/app/api/v1/error_center.py): `backend/app/api/v1/error_center.py`
- [Lead repository](https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/blob/main/backend/app/repositories/leads_repo.py): `backend/app/repositories/leads_repo.py`
- [Audit service](https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/blob/main/backend/app/services/audit_service.py): `backend/app/services/audit_service.py`

### Lead discovery

- [Source registry](https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/blob/main/automation/scrapers/registry.py): `automation/scrapers/registry.py`
- [Scraper runner](https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/blob/main/automation/scrapers/runner.py): `automation/scrapers/runner.py`
- [Scraper interface](https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/blob/main/automation/scrapers/base.py): `automation/scrapers/base.py`
- [Lead normalizer](https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/blob/main/automation/scrapers/normalizer.py): `automation/scrapers/normalizer.py`

### AI intelligence

- [Experience parser](https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/blob/main/ai/extraction/experience_parser.py): `ai/extraction/experience_parser.py`
- [Lead extraction](https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/tree/main/ai/extraction): `ai/extraction`
- [Score explanation](https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/blob/main/ai/explain/score_explainer.py): `ai/explain/score_explainer.py`
- [Gemini drafting](https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/blob/main/ai/gemini_client.py): `ai/gemini_client.py`
- [Draft safety checks](https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/tree/main/ai/validators): `ai/validators`
- [Error diagnosis](https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/blob/main/ai/diagnosis/error_diagnoser.py): `ai/diagnosis/error_diagnoser.py`

### Contact operations

- [Enrichment service](https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/blob/main/backend/app/services/enrichment_service.py): `backend/app/services/enrichment_service.py`
- [Verification service](https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/blob/main/backend/app/services/verification_service.py): `backend/app/services/verification_service.py`
- [Quality scoring](https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/blob/main/backend/app/services/scoring_service.py): `backend/app/services/scoring_service.py`
- [PostgreSQL CRM](https://github.com/shankar-uxcloud/ai-powered-crm-and-outreach-automation-platform/blob/main/backend/app/core/db.py): `backend/app/core/db.py`

### Other components

- **Researcher**
- **Campaign manager**
- **ContactOut**
- **Snov.io**
- **Email verifier**
- **Google Gemini**

## Connections

- Researcher → CRM dashboard: uses dashboard
- CRM dashboard → Lead pipeline: routes to (evidence: `frontend/src/App.jsx`)
- CRM dashboard → Enrichment queue: routes to (evidence: `frontend/src/App.jsx`)
- CRM dashboard → Draft approval: routes to (evidence: `frontend/src/App.jsx`)
- Lead pipeline → API client: requests data
- Enrichment queue → API client: requests data
- Draft approval → API client: submits decisions
- API client → API router: HTTP requests
- API router → Lead routes: mounts (evidence: `backend/app/main.py`)
- API router → Campaign routes: mounts (evidence: `backend/app/main.py`)
- API router → Approval routes: mounts (evidence: `backend/app/main.py`)
- API router → Webhook routes: mounts (evidence: `backend/app/main.py`)
- API router → Error center: mounts (evidence: `backend/app/main.py`)
- Lead routes → Lead repository: uses repository
- Campaign manager → Draft approval: reviews drafts
- Approval routes → Audit service: records decisions
- Source registry → Scraper interface: resolves class (evidence: `automation/scrapers/registry.py`)
- Source registry → PostgreSQL CRM: reads enabled sources (evidence: `automation/scrapers/registry.py`)
- Scraper runner → Source registry: launches scraper
- Scraper runner → Scraper interface: runs extraction
- Scraper interface → Lead normalizer: normalizes results
- Lead normalizer → Lead repository: supplies lead records
- Experience parser → Lead extraction: supports extraction
- Lead repository → Quality scoring: provides lead data
- Quality scoring → Score explanation: explains score
- Enrichment service → PostgreSQL CRM: reads and writes (evidence: `backend/app/services/enrichment_service.py`)
- Enrichment service → ContactOut: optional lookup
- Enrichment service → Snov.io: optional lookup
- Verification service → Email verifier: verifies email
- Verification service → PostgreSQL CRM: stores result
- Gemini drafting → Google Gemini: generates drafts
- Draft safety checks → Gemini drafting: checks output
- Error center → Error diagnosis: requests diagnosis