# victor-hugos/leadflow-automation architecture

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

- Interactive diagram: https://gitdiagram.com/victor-hugos/leadflow-automation
- Repository: https://github.com/victor-hugos/leadflow-automation

## Overview

Leadflow Automation is a FastAPI lead-processing application. A lead enters through the API, is business-validated and checked for duplicates, scored and prioritized, saved to SQLite, then sent to an optional webhook; the API returns the processing result. The app also serves a demo frontend, exposes health and lead-listing endpoints, and logs operational events. Edges follow the shown route orchestration and documented capabilities; the frontend and health implementations were not sampled, so their details are limited to README statements.

Main entry points: [`app/routes/leads.py`](https://github.com/victor-hugos/leadflow-automation/blob/main/app/routes/leads.py) (Lead endpoints), [`app/main.py`](https://github.com/victor-hugos/leadflow-automation/blob/main/app/main.py) (FastAPI app), [`app/database/connection.py`](https://github.com/victor-hugos/leadflow-automation/blob/main/app/database/connection.py) (SQLite connection), [`app/models/lead.py`](https://github.com/victor-hugos/leadflow-automation/blob/main/app/models/lead.py) (Lead schemas)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and UI"]
  node_app["FastAPI app<br/>[main.py]"]
  node_frontend["Demo frontend<br/>[index.html]"]
  node_health["Health endpoint<br/>[health.py]"]
  node_lead_routes["Lead endpoints<br/>[leads.py]"]
end

subgraph group_workflow["Lead workflow"]
  node_lead_model["Lead schemas<br/>[lead.py]"]
  node_validation["Business validation"]
  node_dedup["Duplicate lookup"]
  node_scoring["Lead scoring"]
  node_priority["Priority classification"]
end

subgraph group_storage["Persistence"]
  node_repository["Lead repository"]
  node_db_init["Schema initialization<br/>[init_db.py]"]
  node_connection["SQLite connection<br/>[connection.py]"]
  node_sqlite[("SQLite database")]
end

subgraph group_operations["Integrations and operations"]
  node_webhook["Webhook dispatch<br/>[webhook_service.py]"]
  node_logging["Structured logging<br/>[logger.py]"]
end

node_user(("Form / API user"))
node_external_webhook["Webhook receiver"]

node_user -->|"uses app"| node_app
node_app -->|"registers routes"| node_lead_routes
node_app -->|"registers routes"| node_health
node_app -->|"serves frontend"| node_frontend
node_app -->|"initializes schema"| node_db_init
node_app -->|"sets up logging"| node_logging
node_lead_routes -->|"uses schemas"| node_lead_model
node_lead_routes -->|"validates lead"| node_validation
node_lead_routes -->|"checks duplicates"| node_dedup
node_lead_routes -->|"calculates score"| node_scoring
node_lead_routes -->|"classifies priority"| node_priority
node_lead_routes -->|"saves lead"| node_repository
node_lead_routes -->|"queries listings"| node_connection
node_lead_routes -->|"dispatches lead"| node_webhook
node_lead_routes -->|"records events"| node_logging
node_validation -->|"validates fields"| node_lead_model
node_scoring -->|"scores fields"| node_lead_model
node_repository -->|"persists data"| node_lead_model
node_repository -->|"opens connection"| node_connection
node_dedup -->|"opens connection"| node_connection
node_db_init -->|"opens connection"| node_connection
node_connection -->|"connects to"| node_sqlite
node_webhook -.->|"posts payload"| node_external_webhook
node_webhook -->|"logs outcome"| node_logging

click node_app "https://github.com/victor-hugos/leadflow-automation/blob/main/app/main.py"
click node_frontend "https://github.com/victor-hugos/leadflow-automation/blob/main/frontend/index.html"
click node_health "https://github.com/victor-hugos/leadflow-automation/blob/main/app/routes/health.py"
click node_lead_routes "https://github.com/victor-hugos/leadflow-automation/blob/main/app/routes/leads.py"
click node_lead_model "https://github.com/victor-hugos/leadflow-automation/blob/main/app/models/lead.py"
click node_validation "https://github.com/victor-hugos/leadflow-automation/blob/main/app/services/lead_validation_service.py"
click node_dedup "https://github.com/victor-hugos/leadflow-automation/blob/main/app/services/lead_dedup_service.py"
click node_scoring "https://github.com/victor-hugos/leadflow-automation/blob/main/app/services/lead_scoring_service.py"
click node_priority "https://github.com/victor-hugos/leadflow-automation/blob/main/app/services/lead_priority_service.py"
click node_repository "https://github.com/victor-hugos/leadflow-automation/blob/main/app/services/lead_repository_service.py"
click node_db_init "https://github.com/victor-hugos/leadflow-automation/blob/main/app/database/init_db.py"
click node_connection "https://github.com/victor-hugos/leadflow-automation/blob/main/app/database/connection.py"
click node_sqlite "https://github.com/victor-hugos/leadflow-automation/tree/main/data"
click node_webhook "https://github.com/victor-hugos/leadflow-automation/blob/main/app/services/webhook_service.py"
click node_logging "https://github.com/victor-hugos/leadflow-automation/blob/main/app/utils/logger.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_app,node_frontend,node_health,node_lead_routes,node_user toneBlue
class node_lead_model,node_validation,node_dedup,node_scoring,node_priority toneAmber
class node_repository,node_db_init,node_connection,node_sqlite,node_external_webhook toneMint
class node_webhook,node_logging toneRose
```

## Components

### API and UI

- [FastAPI app](https://github.com/victor-hugos/leadflow-automation/blob/main/app/main.py): `app/main.py`
- [Demo frontend](https://github.com/victor-hugos/leadflow-automation/blob/main/frontend/index.html): `frontend/index.html`
- [Health endpoint](https://github.com/victor-hugos/leadflow-automation/blob/main/app/routes/health.py): `app/routes/health.py`
- [Lead endpoints](https://github.com/victor-hugos/leadflow-automation/blob/main/app/routes/leads.py): `app/routes/leads.py`

### Lead workflow

- [Lead schemas](https://github.com/victor-hugos/leadflow-automation/blob/main/app/models/lead.py): `app/models/lead.py`
- [Business validation](https://github.com/victor-hugos/leadflow-automation/blob/main/app/services/lead_validation_service.py): `app/services/lead_validation_service.py`
- [Duplicate lookup](https://github.com/victor-hugos/leadflow-automation/blob/main/app/services/lead_dedup_service.py): `app/services/lead_dedup_service.py`
- [Lead scoring](https://github.com/victor-hugos/leadflow-automation/blob/main/app/services/lead_scoring_service.py): `app/services/lead_scoring_service.py`
- [Priority classification](https://github.com/victor-hugos/leadflow-automation/blob/main/app/services/lead_priority_service.py): `app/services/lead_priority_service.py`

### Persistence

- [Lead repository](https://github.com/victor-hugos/leadflow-automation/blob/main/app/services/lead_repository_service.py): `app/services/lead_repository_service.py`
- [Schema initialization](https://github.com/victor-hugos/leadflow-automation/blob/main/app/database/init_db.py): `app/database/init_db.py`
- [SQLite connection](https://github.com/victor-hugos/leadflow-automation/blob/main/app/database/connection.py): `app/database/connection.py`
- [SQLite database](https://github.com/victor-hugos/leadflow-automation/tree/main/data): `data`

### Integrations and operations

- [Webhook dispatch](https://github.com/victor-hugos/leadflow-automation/blob/main/app/services/webhook_service.py): `app/services/webhook_service.py`
- [Structured logging](https://github.com/victor-hugos/leadflow-automation/blob/main/app/utils/logger.py): `app/utils/logger.py`

### Other components

- **Form / API user**
- **Webhook receiver**

## Connections

- Form / API user → FastAPI app: uses app (evidence: `README.md`)
- FastAPI app → Lead endpoints: registers routes (evidence: `app/main.py`)
- FastAPI app → Health endpoint: registers routes (evidence: `app/main.py`)
- FastAPI app → Demo frontend: serves frontend (evidence: `app/main.py`)
- FastAPI app → Schema initialization: initializes schema (evidence: `app/main.py`)
- FastAPI app → Structured logging: sets up logging (evidence: `app/main.py`)
- Lead endpoints → Lead schemas: uses schemas (evidence: `app/routes/leads.py`)
- Lead endpoints → Business validation: validates lead (evidence: `app/routes/leads.py`)
- Lead endpoints → Duplicate lookup: checks duplicates (evidence: `app/routes/leads.py`)
- Lead endpoints → Lead scoring: calculates score (evidence: `app/routes/leads.py`)
- Lead endpoints → Priority classification: classifies priority (evidence: `app/routes/leads.py`)
- Lead endpoints → Lead repository: saves lead (evidence: `app/routes/leads.py`)
- Lead endpoints → SQLite connection: queries listings (evidence: `app/routes/leads.py`)
- Lead endpoints → Webhook dispatch: dispatches lead (evidence: `app/routes/leads.py`)
- Lead endpoints → Structured logging: records events (evidence: `app/routes/leads.py`)
- Business validation → Lead schemas: validates fields (evidence: `app/services/lead_validation_service.py`)
- Lead scoring → Lead schemas: scores fields (evidence: `app/services/lead_scoring_service.py`)
- Lead repository → Lead schemas: persists data (evidence: `app/services/lead_repository_service.py`)
- Lead repository → SQLite connection: opens connection (evidence: `app/services/lead_repository_service.py`)
- Duplicate lookup → SQLite connection: opens connection (evidence: `app/services/lead_dedup_service.py`)
- Schema initialization → SQLite connection: opens connection (evidence: `app/database/init_db.py`)
- SQLite connection → SQLite database: connects to (evidence: `app/database/connection.py`)
- Webhook dispatch → Webhook receiver: posts payload (evidence: `app/services/webhook_service.py`)
- Webhook dispatch → Structured logging: logs outcome (evidence: `app/services/webhook_service.py`)
