# leadsmediasa/deepseek-lead-system architecture

> Architecture diagram of the GitHub repository leadsmediasa/deepseek-lead-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/leadsmediasa/deepseek-lead-system
- Repository: https://github.com/leadsmediasa/deepseek-lead-system

## Overview

DeepSeek Lead Generation System creates categorized Forex, Crypto, and Casino leads through a CLI or REST API, then validates and scores them for export; a Streamlit dashboard provides a separate lead-management interface. The README also describes AI generation, predictive scoring, behavioral analysis, and multiple lead categories. Source excerpts show validation/scoring and category generators, but do not establish live scraping or persistent lead storage; API analytics and export are described as mock or production placeholders.

Main entry points: [`run.py`](https://github.com/leadsmediasa/deepseek-lead-system/blob/main/run.py) (CLI launcher), [`core/engine.py`](https://github.com/leadsmediasa/deepseek-lead-system/blob/main/core/engine.py) (Generation engine), [`api/main.py`](https://github.com/leadsmediasa/deepseek-lead-system/blob/main/api/main.py) (REST API), [`core/generators.py`](https://github.com/leadsmediasa/deepseek-lead-system/blob/main/core/generators.py) (Category generators)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entrypoints["User interfaces"]
  node_cli["CLI launcher<br/>[run.py]"]
  node_rest_api["REST API<br/>[main.py]"]
  node_dashboard["Dashboard<br/>[app.py]"]
end

subgraph group_generation["Lead generation"]
  node_engine["Generation engine<br/>[engine.py]"]
  node_generators["Category generators<br/>[generators.py]"]
end

subgraph group_intelligence["AI and validation"]
  node_ai_features["AI enrichment<br/>[ai_ml_features.py]"]
  node_scoring["Lead scoring<br/>[ai_ml_features.py]"]
  node_prediction["Conversion prediction<br/>[ai_ml_features.py]"]
  node_validation["Lead validation<br/>[ai_ml_features.py]"]
end

subgraph group_outputs["Lead outputs"]
  node_exports["CSV and JSON exports<br/>[engine.py]"]
end

node_operator(("Operator"))
node_api_client(("API client"))

node_operator -->|"runs"| node_cli
node_operator -->|"uses"| node_dashboard
node_api_client -->|"requests"| node_rest_api
node_cli -->|"creates"| node_engine
node_cli -->|"selects category"| node_generators
node_cli -->|"starts server"| node_rest_api
node_cli -->|"starts dashboard"| node_dashboard
node_rest_api -->|"generates leads"| node_engine
node_rest_api -->|"selects category"| node_generators
node_engine -->|"generates records"| node_generators
node_engine -->|"validates leads"| node_validation
node_engine -->|"scores leads"| node_scoring
node_engine -->|"writes files"| node_exports
node_cli -->|"reports scores"| node_scoring
node_ai_features -.->|"supports scoring"| node_scoring
node_ai_features -.->|"supports prediction"| node_prediction

click node_cli "https://github.com/leadsmediasa/deepseek-lead-system/blob/main/run.py"
click node_rest_api "https://github.com/leadsmediasa/deepseek-lead-system/blob/main/api/main.py"
click node_dashboard "https://github.com/leadsmediasa/deepseek-lead-system/blob/main/dashboard/app.py"
click node_engine "https://github.com/leadsmediasa/deepseek-lead-system/blob/main/core/engine.py"
click node_generators "https://github.com/leadsmediasa/deepseek-lead-system/blob/main/core/generators.py"
click node_ai_features "https://github.com/leadsmediasa/deepseek-lead-system/blob/main/core/ai_ml_features.py"
click node_scoring "https://github.com/leadsmediasa/deepseek-lead-system/blob/main/core/ai_ml_features.py"
click node_prediction "https://github.com/leadsmediasa/deepseek-lead-system/blob/main/core/ai_ml_features.py"
click node_validation "https://github.com/leadsmediasa/deepseek-lead-system/blob/main/core/ai_ml_features.py"
click node_exports "https://github.com/leadsmediasa/deepseek-lead-system/blob/main/core/engine.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_rest_api,node_dashboard,node_api_client toneBlue
class node_engine,node_generators toneAmber
class node_ai_features,node_scoring,node_prediction,node_validation toneMint
class node_exports toneRose
class node_operator toneIndigo
```

## Components

### User interfaces

- [CLI launcher](https://github.com/leadsmediasa/deepseek-lead-system/blob/main/run.py): `run.py`
- [REST API](https://github.com/leadsmediasa/deepseek-lead-system/blob/main/api/main.py): `api/main.py`
- [Dashboard](https://github.com/leadsmediasa/deepseek-lead-system/blob/main/dashboard/app.py): `dashboard/app.py`

### Lead generation

- [Generation engine](https://github.com/leadsmediasa/deepseek-lead-system/blob/main/core/engine.py): `core/engine.py`
- [Category generators](https://github.com/leadsmediasa/deepseek-lead-system/blob/main/core/generators.py): `core/generators.py`

### AI and validation

- [AI enrichment](https://github.com/leadsmediasa/deepseek-lead-system/blob/main/core/ai_ml_features.py): `core/ai_ml_features.py`
- [Lead scoring](https://github.com/leadsmediasa/deepseek-lead-system/blob/main/core/ai_ml_features.py): `core/ai_ml_features.py`
- [Conversion prediction](https://github.com/leadsmediasa/deepseek-lead-system/blob/main/core/ai_ml_features.py): `core/ai_ml_features.py`
- [Lead validation](https://github.com/leadsmediasa/deepseek-lead-system/blob/main/core/ai_ml_features.py): `core/ai_ml_features.py`

### Lead outputs

- [CSV and JSON exports](https://github.com/leadsmediasa/deepseek-lead-system/blob/main/core/engine.py): `core/engine.py`

### Other components

- **Operator**
- **API client**

## Connections

- Operator → CLI launcher: runs (evidence: `run.py`)
- Operator → Dashboard: uses (evidence: `dashboard/app.py`)
- API client → REST API: requests (evidence: `api/main.py`)
- CLI launcher → Generation engine: creates (evidence: `run.py`)
- CLI launcher → Category generators: selects category (evidence: `run.py`)
- CLI launcher → REST API: starts server (evidence: `run.py`)
- CLI launcher → Dashboard: starts dashboard (evidence: `run.py`)
- REST API → Generation engine: generates leads (evidence: `api/main.py`)
- REST API → Category generators: selects category (evidence: `api/main.py`)
- Generation engine → Category generators: generates records (evidence: `core/engine.py`)
- Generation engine → Lead validation: validates leads (evidence: `core/engine.py`)
- Generation engine → Lead scoring: scores leads (evidence: `core/engine.py`)
- Generation engine → CSV and JSON exports: writes files (evidence: `core/engine.py`)
- CLI launcher → Lead scoring: reports scores (evidence: `run.py`)
- AI enrichment → Lead scoring: supports scoring (evidence: `core/ai_ml_features.py`)
- AI enrichment → Conversion prediction: supports prediction (evidence: `core/ai_ml_features.py`)
