# sebai-dhia/leadforge architecture

> Architecture diagram of the GitHub repository sebai-dhia/leadforge, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sebai-dhia/leadforge
- Repository: https://github.com/sebai-dhia/leadforge

## Overview

Leadforge is a freelancer-facing lead-generation web application. A user signs in, describes their service and target area, then starts searches; n8n finds businesses, the API stores and ranks leads, and the user reviews drafts and tracks outreach. The README documents the search, contact-lookup, and message-draft workflow integrations and their external providers. Several backend and workflow implementations were not sampled, so those relationships are shown only where the README supports them; unsampled subsystem internals are represented by their existing source directories.

Main entry points: [`app/backend/src/main/java/com/leadfinder/search/SearchController.java`](https://github.com/sebai-dhia/leadforge/blob/main/app/backend/src/main/java/com/leadfinder/search/SearchController.java) (Search and lead API), [`app/frontend/src/app/app.ts`](https://github.com/sebai-dhia/leadforge/blob/main/app/frontend/src/app/app.ts) (Angular web app), [`app/workflow-src`](https://github.com/sebai-dhia/leadforge/tree/main/app/workflow-src) (n8n workflows), [`app/backend/src/main/java/com/leadfinder/admin/AdminService.java`](https://github.com/sebai-dhia/leadforge/blob/main/app/backend/src/main/java/com/leadfinder/admin/AdminService.java) (Admin services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_webapp["Angular web app<br/>[app.ts]"]
  node_authui["Sign-in and onboarding<br/>[login.ts]"]
  node_searchui["Search area picker<br/>[searches.ts]"]
  node_leadui["Lead review and tracking<br/>[leads.ts]"]
  node_profileui["Profile and preferences<br/>[profile.ts]"]
  node_adminui["Admin dashboard<br/>[admin.ts]"]
end

subgraph group_identity["Identity and accounts"]
  node_authapi["Authentication API"]
  node_accounts["User and session services"]
end

subgraph group_leads["Lead discovery and outreach"]
  node_searchapi["Search and lead API"]
  node_leadservice["Lead deduplication and enrichment<br/>[LeadService.java]"]
  node_workflow["n8n workflows"]
  node_places["Geoapify places"]
  node_websearch["Serper web search"]
  node_gemini["Gemini drafting"]
  node_leadsstore[("Lead and search records")]
end

subgraph group_platform["API platform"]
  node_postgres[("PostgreSQL")]
  node_settings["Runtime settings"]
  node_usage["Usage limits and metering<br/>[UsageService.java]"]
  node_adminapi["Admin services<br/>[AdminService.java]"]
end

subgraph group_messaging["Reminders and alerts"]
  node_telegram["Telegram reminders"]
  node_alert["Admin alerting<br/>[AlertService.java]"]
  node_telegramservice["Telegram service<br/>[TelegramBot.java]"]
end

node_freelancer(("Freelancer"))

node_freelancer -->|"uses"| node_webapp
node_webapp -->|"routes to"| node_authui
node_webapp -->|"routes to"| node_searchui
node_webapp -->|"routes to"| node_leadui
node_webapp -->|"routes to"| node_profileui
node_webapp -->|"routes to"| node_adminui
node_authui -->|"authenticates through"| node_authapi
node_authapi -->|"manages sessions"| node_accounts
node_accounts -.->|"reads and writes"| node_postgres
node_searchui -->|"submits search"| node_searchapi
node_leadui -->|"requests leads"| node_searchapi
node_profileui -.->|"uses API"| node_searchapi
node_adminui -.->|"uses API"| node_adminapi
node_searchapi -->|"dispatches search"| node_workflow
node_workflow -->|"returns results"| node_searchapi
node_workflow -->|"finds places"| node_places
node_workflow -->|"searches web"| node_websearch
node_workflow -->|"drafts messages"| node_gemini
node_searchapi -.->|"processes leads"| node_leadservice
node_leadservice -->|"deduplicates and saves"| node_leadsstore
node_searchapi -.->|"persists searches"| node_postgres
node_searchapi -.->|"checks limits"| node_usage
node_settings -->|"loads overrides"| node_postgres
node_adminapi -->|"summarizes users"| node_accounts
node_adminapi -->|"summarizes usage"| node_usage
node_telegram -.->|"sends reminders"| node_telegramservice
node_usage -->|"reports global caps"| node_alert
node_alert -->|"sends alert"| node_telegramservice

click node_webapp "https://github.com/sebai-dhia/leadforge/blob/main/app/frontend/src/app/app.ts"
click node_authui "https://github.com/sebai-dhia/leadforge/blob/main/app/frontend/src/app/features/login/login.ts"
click node_searchui "https://github.com/sebai-dhia/leadforge/blob/main/app/frontend/src/app/features/searches/searches.ts"
click node_leadui "https://github.com/sebai-dhia/leadforge/blob/main/app/frontend/src/app/features/leads/leads.ts"
click node_profileui "https://github.com/sebai-dhia/leadforge/blob/main/app/frontend/src/app/features/profile/profile.ts"
click node_adminui "https://github.com/sebai-dhia/leadforge/blob/main/app/frontend/src/app/features/admin/admin.ts"
click node_authapi "https://github.com/sebai-dhia/leadforge/blob/main/app/backend/src/main/java/com/leadfinder/auth/AuthController.java"
click node_accounts "https://github.com/sebai-dhia/leadforge/blob/main/app/backend/src/main/java/com/leadfinder/auth/ActiveSessionRegistry.java"
click node_searchapi "https://github.com/sebai-dhia/leadforge/blob/main/app/backend/src/main/java/com/leadfinder/search/SearchController.java"
click node_leadservice "https://github.com/sebai-dhia/leadforge/blob/main/app/backend/src/main/java/com/leadfinder/search/LeadService.java"
click node_workflow "https://github.com/sebai-dhia/leadforge/tree/main/app/workflow-src"
click node_leadsstore "https://github.com/sebai-dhia/leadforge/blob/main/app/backend/src/main/java/com/leadfinder/search/LeadRepository.java"
click node_settings "https://github.com/sebai-dhia/leadforge/blob/main/app/backend/src/main/java/com/leadfinder/settings/RuntimeSettings.java"
click node_usage "https://github.com/sebai-dhia/leadforge/blob/main/app/backend/src/main/java/com/leadfinder/usage/UsageService.java"
click node_adminapi "https://github.com/sebai-dhia/leadforge/blob/main/app/backend/src/main/java/com/leadfinder/admin/AdminService.java"
click node_telegram "https://github.com/sebai-dhia/leadforge/blob/main/app/backend/src/main/java/com/leadfinder/telegram/FollowUpReminder.java"
click node_alert "https://github.com/sebai-dhia/leadforge/blob/main/app/backend/src/main/java/com/leadfinder/alert/AlertService.java"
click node_telegramservice "https://github.com/sebai-dhia/leadforge/blob/main/app/backend/src/main/java/com/leadfinder/telegram/TelegramBot.java"

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_webapp,node_authui,node_searchui,node_leadui,node_profileui,node_adminui toneBlue
class node_authapi,node_accounts toneAmber
class node_searchapi,node_leadservice,node_workflow,node_places,node_websearch,node_gemini,node_leadsstore toneMint
class node_postgres,node_settings,node_usage,node_adminapi toneRose
class node_telegram,node_alert,node_telegramservice,node_freelancer toneIndigo
```

## Components

### Web application

- [Angular web app](https://github.com/sebai-dhia/leadforge/blob/main/app/frontend/src/app/app.ts): `app/frontend/src/app/app.ts`
- [Sign-in and onboarding](https://github.com/sebai-dhia/leadforge/blob/main/app/frontend/src/app/features/login/login.ts): `app/frontend/src/app/features/login/login.ts`
- [Search area picker](https://github.com/sebai-dhia/leadforge/blob/main/app/frontend/src/app/features/searches/searches.ts): `app/frontend/src/app/features/searches/searches.ts`
- [Lead review and tracking](https://github.com/sebai-dhia/leadforge/blob/main/app/frontend/src/app/features/leads/leads.ts): `app/frontend/src/app/features/leads/leads.ts`
- [Profile and preferences](https://github.com/sebai-dhia/leadforge/blob/main/app/frontend/src/app/features/profile/profile.ts): `app/frontend/src/app/features/profile/profile.ts`
- [Admin dashboard](https://github.com/sebai-dhia/leadforge/blob/main/app/frontend/src/app/features/admin/admin.ts): `app/frontend/src/app/features/admin/admin.ts`

### Identity and accounts

- [Authentication API](https://github.com/sebai-dhia/leadforge/blob/main/app/backend/src/main/java/com/leadfinder/auth/AuthController.java): `app/backend/src/main/java/com/leadfinder/auth/AuthController.java`
- [User and session services](https://github.com/sebai-dhia/leadforge/blob/main/app/backend/src/main/java/com/leadfinder/auth/ActiveSessionRegistry.java): `app/backend/src/main/java/com/leadfinder/auth/ActiveSessionRegistry.java`

### Lead discovery and outreach

- [Search and lead API](https://github.com/sebai-dhia/leadforge/blob/main/app/backend/src/main/java/com/leadfinder/search/SearchController.java): `app/backend/src/main/java/com/leadfinder/search/SearchController.java`
- [Lead deduplication and enrichment](https://github.com/sebai-dhia/leadforge/blob/main/app/backend/src/main/java/com/leadfinder/search/LeadService.java): `app/backend/src/main/java/com/leadfinder/search/LeadService.java`
- [n8n workflows](https://github.com/sebai-dhia/leadforge/tree/main/app/workflow-src): `app/workflow-src`
- **Geoapify places**
- **Serper web search**
- **Gemini drafting**
- [Lead and search records](https://github.com/sebai-dhia/leadforge/blob/main/app/backend/src/main/java/com/leadfinder/search/LeadRepository.java): `app/backend/src/main/java/com/leadfinder/search/LeadRepository.java`

### API platform

- **PostgreSQL**
- [Runtime settings](https://github.com/sebai-dhia/leadforge/blob/main/app/backend/src/main/java/com/leadfinder/settings/RuntimeSettings.java): `app/backend/src/main/java/com/leadfinder/settings/RuntimeSettings.java`
- [Usage limits and metering](https://github.com/sebai-dhia/leadforge/blob/main/app/backend/src/main/java/com/leadfinder/usage/UsageService.java): `app/backend/src/main/java/com/leadfinder/usage/UsageService.java`
- [Admin services](https://github.com/sebai-dhia/leadforge/blob/main/app/backend/src/main/java/com/leadfinder/admin/AdminService.java): `app/backend/src/main/java/com/leadfinder/admin/AdminService.java`

### Reminders and alerts

- [Telegram reminders](https://github.com/sebai-dhia/leadforge/blob/main/app/backend/src/main/java/com/leadfinder/telegram/FollowUpReminder.java): `app/backend/src/main/java/com/leadfinder/telegram/FollowUpReminder.java`
- [Admin alerting](https://github.com/sebai-dhia/leadforge/blob/main/app/backend/src/main/java/com/leadfinder/alert/AlertService.java): `app/backend/src/main/java/com/leadfinder/alert/AlertService.java`
- [Telegram service](https://github.com/sebai-dhia/leadforge/blob/main/app/backend/src/main/java/com/leadfinder/telegram/TelegramBot.java): `app/backend/src/main/java/com/leadfinder/telegram/TelegramBot.java`

### Other components

- **Freelancer**

## Connections

- Freelancer → Angular web app: uses (evidence: `README.md`)
- Angular web app → Sign-in and onboarding: routes to
- Angular web app → Search area picker: routes to
- Angular web app → Lead review and tracking: routes to
- Angular web app → Profile and preferences: routes to
- Angular web app → Admin dashboard: routes to
- Sign-in and onboarding → Authentication API: authenticates through (evidence: `README.md`)
- Authentication API → User and session services: manages sessions (evidence: `app/backend/src/main/java/com/leadfinder/auth/AuthController.java`)
- User and session services → PostgreSQL: reads and writes
- Search area picker → Search and lead API: submits search (evidence: `README.md`)
- Lead review and tracking → Search and lead API: requests leads (evidence: `README.md`)
- Profile and preferences → Search and lead API: uses API
- Admin dashboard → Admin services: uses API
- Search and lead API → n8n workflows: dispatches search (evidence: `README.md`)
- n8n workflows → Search and lead API: returns results (evidence: `README.md`)
- n8n workflows → Geoapify places: finds places (evidence: `README.md`)
- n8n workflows → Serper web search: searches web (evidence: `README.md`)
- n8n workflows → Gemini drafting: drafts messages (evidence: `README.md`)
- Search and lead API → Lead deduplication and enrichment: processes leads
- Lead deduplication and enrichment → Lead and search records: deduplicates and saves (evidence: `app/backend/src/main/java/com/leadfinder/search/LeadService.java`)
- Search and lead API → PostgreSQL: persists searches
- Search and lead API → Usage limits and metering: checks limits
- Runtime settings → PostgreSQL: loads overrides (evidence: `app/backend/src/main/java/com/leadfinder/settings/RuntimeSettings.java`)
- Admin services → User and session services: summarizes users (evidence: `app/backend/src/main/java/com/leadfinder/admin/AdminService.java`)
- Admin services → Usage limits and metering: summarizes usage (evidence: `app/backend/src/main/java/com/leadfinder/admin/AdminService.java`)
- Telegram reminders → Telegram service: sends reminders
- Usage limits and metering → Admin alerting: reports global caps (evidence: `app/backend/src/main/java/com/leadfinder/usage/UsageService.java`)
- Admin alerting → Telegram service: sends alert (evidence: `app/backend/src/main/java/com/leadfinder/alert/AlertService.java`)
