# gopi514-chand/autonomous-lead-enrichment-agent architecture

> Architecture diagram of the GitHub repository gopi514-chand/autonomous-lead-enrichment-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gopi514-chand/autonomous-lead-enrichment-agent
- Repository: https://github.com/gopi514-chand/autonomous-lead-enrichment-agent

## Overview

AI Lead Enrichment Agent accepts company domains through a Flask interface or CLI, crawls public company pages, extracts and validates structured lead records, and presents or saves JSON results. The README documents page discovery, DOM cleaning, social-link detection, optional OpenAI extraction, and a deterministic fallback. The `lead_enricher.py` excerpt is incomplete, so uncertain internal call wiring is omitted; the documented capabilities remain represented.

Main entry points: [`lead_enricher.py`](https://github.com/gopi514-chand/autonomous-lead-enrichment-agent/blob/main/lead_enricher.py) (Enrichment workflow), [`app.py`](https://github.com/gopi514-chand/autonomous-lead-enrichment-agent/blob/main/app.py) (Flask interface), [`templates/index.html`](https://github.com/gopi514-chand/autonomous-lead-enrichment-agent/blob/main/templates/index.html) (Browser form)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry points"]
  node_web_ui["Browser form<br/>[index.html]"]
  node_flask["Flask interface<br/>[app.py]"]
  node_cli["CLI entry point<br/>[lead_enricher.py]"]
end

subgraph group_crawl["Website collection"]
  node_normalize["Domain normalization<br/>[lead_enricher.py]"]
  node_crawler["Domain crawler<br/>[lead_enricher.py]"]
  node_browser["Playwright browser"]
  node_page_discovery["Page discovery<br/>[lead_enricher.py]"]
  node_content_cleaning["DOM cleaning<br/>[lead_enricher.py]"]
  node_social_detection["Social-link detection<br/>[lead_enricher.py]"]
end

subgraph group_extract["Profile extraction"]
  node_enrichment["Enrichment workflow<br/>[lead_enricher.py]"]
  node_llm["OpenAI extraction<br/>[lead_enricher.py]"]
  node_fallback["Heuristic extraction<br/>[lead_enricher.py]"]
  node_profile["Profile validation<br/>[lead_enricher.py]"]
end

subgraph group_delivery["Results and state"]
  node_json_output["JSON output<br/>[lead_enricher.py]"]
  node_job_state["In-memory job state<br/>[app.py]"]
end

node_user(("Prospecting user"))
node_cli_user(("CLI operator"))
node_public_sites["Company websites"]
node_openai["OpenAI service"]

node_user -->|"enters domains"| node_web_ui
node_web_ui -->|"submits form"| node_flask
node_flask -->|"enriches domains"| node_enrichment
node_flask -->|"tracks jobs"| node_job_state
node_cli_user -->|"provides domains"| node_cli
node_cli -->|"enriches domains"| node_enrichment
node_cli -->|"writes records"| node_json_output
node_enrichment -->|"normalizes domain"| node_normalize
node_enrichment -->|"crawls domain"| node_crawler
node_crawler -->|"loads pages"| node_browser
node_browser -->|"requests pages"| node_public_sites
node_crawler -->|"discovers links"| node_page_discovery
node_crawler -->|"cleans page content"| node_content_cleaning
node_crawler -->|"detects social links"| node_social_detection
node_enrichment -.->|"tries extraction"| node_llm
node_llm -.->|"requests extraction"| node_openai
node_enrichment -->|"falls back"| node_fallback
node_fallback -->|"uses discovered links"| node_social_detection
node_fallback -->|"validates record"| node_profile
node_llm -.->|"validates record"| node_profile
node_profile -->|"returns profile"| node_enrichment
node_enrichment -->|"returns results"| node_flask

click node_web_ui "https://github.com/gopi514-chand/autonomous-lead-enrichment-agent/blob/main/templates/index.html"
click node_flask "https://github.com/gopi514-chand/autonomous-lead-enrichment-agent/blob/main/app.py"
click node_cli "https://github.com/gopi514-chand/autonomous-lead-enrichment-agent/blob/main/lead_enricher.py"
click node_normalize "https://github.com/gopi514-chand/autonomous-lead-enrichment-agent/blob/main/lead_enricher.py"
click node_crawler "https://github.com/gopi514-chand/autonomous-lead-enrichment-agent/blob/main/lead_enricher.py"
click node_page_discovery "https://github.com/gopi514-chand/autonomous-lead-enrichment-agent/blob/main/lead_enricher.py"
click node_content_cleaning "https://github.com/gopi514-chand/autonomous-lead-enrichment-agent/blob/main/lead_enricher.py"
click node_social_detection "https://github.com/gopi514-chand/autonomous-lead-enrichment-agent/blob/main/lead_enricher.py"
click node_enrichment "https://github.com/gopi514-chand/autonomous-lead-enrichment-agent/blob/main/lead_enricher.py"
click node_llm "https://github.com/gopi514-chand/autonomous-lead-enrichment-agent/blob/main/lead_enricher.py"
click node_fallback "https://github.com/gopi514-chand/autonomous-lead-enrichment-agent/blob/main/lead_enricher.py"
click node_profile "https://github.com/gopi514-chand/autonomous-lead-enrichment-agent/blob/main/lead_enricher.py"
click node_json_output "https://github.com/gopi514-chand/autonomous-lead-enrichment-agent/blob/main/lead_enricher.py"
click node_job_state "https://github.com/gopi514-chand/autonomous-lead-enrichment-agent/blob/main/app.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_web_ui,node_flask,node_cli,node_user toneBlue
class node_normalize,node_crawler,node_browser,node_page_discovery,node_content_cleaning,node_social_detection toneAmber
class node_enrichment,node_llm,node_fallback,node_profile toneMint
class node_json_output,node_job_state toneRose
class node_cli_user,node_public_sites,node_openai toneIndigo
```

## Components

### User entry points

- [Browser form](https://github.com/gopi514-chand/autonomous-lead-enrichment-agent/blob/main/templates/index.html): `templates/index.html`
- [Flask interface](https://github.com/gopi514-chand/autonomous-lead-enrichment-agent/blob/main/app.py): `app.py`
- [CLI entry point](https://github.com/gopi514-chand/autonomous-lead-enrichment-agent/blob/main/lead_enricher.py): `lead_enricher.py`

### Website collection

- [Domain normalization](https://github.com/gopi514-chand/autonomous-lead-enrichment-agent/blob/main/lead_enricher.py): `lead_enricher.py`
- [Domain crawler](https://github.com/gopi514-chand/autonomous-lead-enrichment-agent/blob/main/lead_enricher.py): `lead_enricher.py`
- **Playwright browser**
- [Page discovery](https://github.com/gopi514-chand/autonomous-lead-enrichment-agent/blob/main/lead_enricher.py): `lead_enricher.py`
- [DOM cleaning](https://github.com/gopi514-chand/autonomous-lead-enrichment-agent/blob/main/lead_enricher.py): `lead_enricher.py`
- [Social-link detection](https://github.com/gopi514-chand/autonomous-lead-enrichment-agent/blob/main/lead_enricher.py): `lead_enricher.py`

### Profile extraction

- [Enrichment workflow](https://github.com/gopi514-chand/autonomous-lead-enrichment-agent/blob/main/lead_enricher.py): `lead_enricher.py`
- [OpenAI extraction](https://github.com/gopi514-chand/autonomous-lead-enrichment-agent/blob/main/lead_enricher.py): `lead_enricher.py`
- [Heuristic extraction](https://github.com/gopi514-chand/autonomous-lead-enrichment-agent/blob/main/lead_enricher.py): `lead_enricher.py`
- [Profile validation](https://github.com/gopi514-chand/autonomous-lead-enrichment-agent/blob/main/lead_enricher.py): `lead_enricher.py`

### Results and state

- [JSON output](https://github.com/gopi514-chand/autonomous-lead-enrichment-agent/blob/main/lead_enricher.py): `lead_enricher.py`
- [In-memory job state](https://github.com/gopi514-chand/autonomous-lead-enrichment-agent/blob/main/app.py): `app.py`

### Other components

- **Prospecting user**
- **CLI operator**
- **Company websites**
- **OpenAI service**

## Connections

- Prospecting user → Browser form: enters domains
- Browser form → Flask interface: submits form
- Flask interface → Enrichment workflow: enriches domains
- Flask interface → In-memory job state: tracks jobs
- CLI operator → CLI entry point: provides domains
- CLI entry point → Enrichment workflow: enriches domains
- CLI entry point → JSON output: writes records
- Enrichment workflow → Domain normalization: normalizes domain
- Enrichment workflow → Domain crawler: crawls domain
- Domain crawler → Playwright browser: loads pages
- Playwright browser → Company websites: requests pages
- Domain crawler → Page discovery: discovers links
- Domain crawler → DOM cleaning: cleans page content
- Domain crawler → Social-link detection: detects social links
- Enrichment workflow → OpenAI extraction: tries extraction
- OpenAI extraction → OpenAI service: requests extraction
- Enrichment workflow → Heuristic extraction: falls back
- Heuristic extraction → Social-link detection: uses discovered links
- Heuristic extraction → Profile validation: validates record
- OpenAI extraction → Profile validation: validates record
- Profile validation → Enrichment workflow: returns profile
- Enrichment workflow → Flask interface: returns results