# lucas-m-fr/sales-intel-engine architecture

> Architecture diagram of the GitHub repository lucas-m-fr/sales-intel-engine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lucas-m-fr/sales-intel-engine
- Repository: https://github.com/lucas-m-fr/sales-intel-engine
- Video tour (about a minute): https://gitdiagram.com/lucas-m-fr/sales-intel-engine/video

## Overview

Sales Intelligence Engine turns a user’s target into downloadable, evidence-backed business tables. The CLI and Streamlit UI each orchestrate planning, lead discovery, page capture, optional review enrichment, extraction, and verification; Streamlit also displays and offers CSV downloads. Shared batch files hold leads, evidence, and table outputs. NVIDIA supplies query refinement and structured extraction, while Firecrawl searches and scrapes public sites. The graph shows only relationships documented in the README or visible in the supplied excerpts; unsampled modules and unshown interactions are not inferred.

Main entry points: [`streamlit_app.py`](https://github.com/lucas-m-fr/sales-intel-engine/blob/main/streamlit_app.py) (Streamlit app), [`main.py`](https://github.com/lucas-m-fr/sales-intel-engine/blob/main/main.py) (CLI runner), [`src/interaction.py`](https://github.com/lucas-m-fr/sales-intel-engine/blob/main/src/interaction.py) (Page capture), [`src/discovery.py`](https://github.com/lucas-m-fr/sales-intel-engine/blob/main/src/discovery.py) (Batch archive)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry points"]
  node_cli["CLI runner<br/>[main.py]"]
  node_webui["Streamlit app<br/>[streamlit_app.py]"]
end

subgraph group_research["Lead research"]
  node_planner["Search planner<br/>[planner.py]"]
  node_discovery["Lead discovery<br/>[discovery.py]"]
end

subgraph group_evidence["Evidence capture"]
  node_capture["Page capture<br/>[interaction.py]"]
  node_reviews["Review enrichment"]
end

subgraph group_intelligence["Extraction and output"]
  node_extractor["Table extraction<br/>[extractor.py]"]
  node_validator["Evidence validation<br/>[validator.py]"]
  node_monitor["Progress monitor<br/>[monitor.py]"]
end

subgraph group_runtime["Runtime services"]
  node_archive[("Batch archive<br/>[discovery.py]")]
  node_config["Runtime configuration<br/>[config.py]"]
  node_llm["NVIDIA client<br/>[llm.py]"]
end

node_user(("Target user"))
node_firecrawl{{"Firecrawl service"}}
node_nvidia{{"NVIDIA NIM"}}
node_browser{{"Playwright browser"}}

node_user -->|"provides target"| node_cli
node_user -->|"provides target"| node_webui
node_cli -->|"requests strategy"| node_planner
node_cli -->|"requests leads"| node_discovery
node_cli -->|"starts capture"| node_capture
node_cli -->|"starts enrichment"| node_reviews
node_cli -->|"starts extraction"| node_extractor
node_cli -->|"validates tables"| node_validator
node_webui -->|"requests strategy"| node_planner
node_webui -->|"requests leads"| node_discovery
node_webui -->|"starts capture"| node_capture
node_webui -->|"starts enrichment"| node_reviews
node_webui -->|"starts extraction"| node_extractor
node_webui -->|"validates tables"| node_validator
node_webui -->|"shows downloads"| node_user
node_planner -->|"requests completion"| node_llm
node_extractor -->|"requests extraction"| node_llm
node_llm -->|"sends prompts"| node_nvidia
node_discovery -->|"searches leads"| node_firecrawl
node_capture -->|"scrapes fallback"| node_firecrawl
node_capture -->|"captures pages"| node_browser
node_reviews -->|"searches and scrapes"| node_firecrawl
node_discovery -->|"writes lead batch"| node_archive
node_capture -->|"writes page evidence"| node_archive
node_reviews -->|"writes review evidence"| node_archive
node_extractor -->|"reads evidence; writes tables"| node_archive
node_validator -->|"checks evidence and tables"| node_archive
node_monitor -->|"reports batch status"| node_archive
node_discovery -->|"loads API key and archive path"| node_config
node_capture -->|"loads API key"| node_config
node_reviews -->|"loads API key"| node_config
node_planner -->|"reads model settings"| node_config
node_llm -->|"reads NVIDIA settings"| node_config

click node_cli "https://github.com/lucas-m-fr/sales-intel-engine/blob/main/main.py"
click node_webui "https://github.com/lucas-m-fr/sales-intel-engine/blob/main/streamlit_app.py"
click node_planner "https://github.com/lucas-m-fr/sales-intel-engine/blob/main/src/planner.py"
click node_discovery "https://github.com/lucas-m-fr/sales-intel-engine/blob/main/src/discovery.py"
click node_capture "https://github.com/lucas-m-fr/sales-intel-engine/blob/main/src/interaction.py"
click node_reviews "https://github.com/lucas-m-fr/sales-intel-engine/blob/main/src/review_enrichment.py"
click node_extractor "https://github.com/lucas-m-fr/sales-intel-engine/blob/main/src/extractor.py"
click node_validator "https://github.com/lucas-m-fr/sales-intel-engine/blob/main/src/validator.py"
click node_monitor "https://github.com/lucas-m-fr/sales-intel-engine/blob/main/src/monitor.py"
click node_archive "https://github.com/lucas-m-fr/sales-intel-engine/blob/main/src/discovery.py"
click node_config "https://github.com/lucas-m-fr/sales-intel-engine/blob/main/src/config.py"
click node_llm "https://github.com/lucas-m-fr/sales-intel-engine/blob/main/src/llm.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_cli,node_webui,node_user,node_browser toneBlue
class node_planner,node_discovery toneAmber
class node_capture,node_reviews toneMint
class node_extractor,node_validator,node_monitor toneRose
class node_archive,node_config,node_llm,node_firecrawl,node_nvidia toneIndigo
```

## Components

### User entry points

- [CLI runner](https://github.com/lucas-m-fr/sales-intel-engine/blob/main/main.py): `main.py`
- [Streamlit app](https://github.com/lucas-m-fr/sales-intel-engine/blob/main/streamlit_app.py): `streamlit_app.py`

### Lead research

- [Search planner](https://github.com/lucas-m-fr/sales-intel-engine/blob/main/src/planner.py): `src/planner.py`
- [Lead discovery](https://github.com/lucas-m-fr/sales-intel-engine/blob/main/src/discovery.py): `src/discovery.py`

### Evidence capture

- [Page capture](https://github.com/lucas-m-fr/sales-intel-engine/blob/main/src/interaction.py): `src/interaction.py`
- [Review enrichment](https://github.com/lucas-m-fr/sales-intel-engine/blob/main/src/review_enrichment.py): `src/review_enrichment.py`

### Extraction and output

- [Table extraction](https://github.com/lucas-m-fr/sales-intel-engine/blob/main/src/extractor.py): `src/extractor.py`
- [Evidence validation](https://github.com/lucas-m-fr/sales-intel-engine/blob/main/src/validator.py): `src/validator.py`
- [Progress monitor](https://github.com/lucas-m-fr/sales-intel-engine/blob/main/src/monitor.py): `src/monitor.py`

### Runtime services

- [Batch archive](https://github.com/lucas-m-fr/sales-intel-engine/blob/main/src/discovery.py): `src/discovery.py`
- [Runtime configuration](https://github.com/lucas-m-fr/sales-intel-engine/blob/main/src/config.py): `src/config.py`
- [NVIDIA client](https://github.com/lucas-m-fr/sales-intel-engine/blob/main/src/llm.py): `src/llm.py`

### Other components

- **Target user**
- **Firecrawl service**
- **NVIDIA NIM**
- **Playwright browser**

## Connections

- Target user → CLI runner: provides target (evidence: `main.py`)
- Target user → Streamlit app: provides target (evidence: `streamlit_app.py`)
- CLI runner → Search planner: requests strategy (evidence: `main.py`)
- CLI runner → Lead discovery: requests leads (evidence: `main.py`)
- CLI runner → Page capture: starts capture (evidence: `main.py`)
- CLI runner → Review enrichment: starts enrichment (evidence: `main.py`)
- CLI runner → Table extraction: starts extraction (evidence: `main.py`)
- CLI runner → Evidence validation: validates tables (evidence: `main.py`)
- Streamlit app → Search planner: requests strategy (evidence: `streamlit_app.py`)
- Streamlit app → Lead discovery: requests leads (evidence: `streamlit_app.py`)
- Streamlit app → Page capture: starts capture (evidence: `streamlit_app.py`)
- Streamlit app → Review enrichment: starts enrichment (evidence: `streamlit_app.py`)
- Streamlit app → Table extraction: starts extraction (evidence: `streamlit_app.py`)
- Streamlit app → Evidence validation: validates tables (evidence: `streamlit_app.py`)
- Streamlit app → Target user: shows downloads (evidence: `streamlit_app.py`)
- Search planner → NVIDIA client: requests completion (evidence: `src/planner.py`)
- Table extraction → NVIDIA client: requests extraction (evidence: `src/extractor.py`)
- NVIDIA client → NVIDIA NIM: sends prompts (evidence: `src/llm.py`)
- Lead discovery → Firecrawl service: searches leads (evidence: `src/discovery.py`)
- Page capture → Firecrawl service: scrapes fallback (evidence: `src/interaction.py`)
- Page capture → Playwright browser: captures pages (evidence: `src/interaction.py`)
- Review enrichment → Firecrawl service: searches and scrapes (evidence: `src/review_enrichment.py`)
- Lead discovery → Batch archive: writes lead batch (evidence: `src/discovery.py`)
- Page capture → Batch archive: writes page evidence (evidence: `src/interaction.py`)
- Review enrichment → Batch archive: writes review evidence (evidence: `src/review_enrichment.py`)
- Table extraction → Batch archive: reads evidence; writes tables (evidence: `src/extractor.py`)
- Evidence validation → Batch archive: checks evidence and tables (evidence: `src/validator.py`)
- Progress monitor → Batch archive: reports batch status (evidence: `src/monitor.py`)
- Lead discovery → Runtime configuration: loads API key and archive path (evidence: `src/discovery.py`)
- Page capture → Runtime configuration: loads API key (evidence: `src/interaction.py`)
- Review enrichment → Runtime configuration: loads API key (evidence: `src/review_enrichment.py`)
- Search planner → Runtime configuration: reads model settings (evidence: `src/planner.py`)
- NVIDIA client → Runtime configuration: reads NVIDIA settings (evidence: `src/llm.py`)