# adeel-parvaiz/qualifyr architecture

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

- Interactive diagram: https://gitdiagram.com/adeel-parvaiz/qualifyr
- Repository: https://github.com/adeel-parvaiz/qualifyr

## Overview

Qualifyr turns an offer into a ranked, evidence-backed company shortlist, with a web dashboard and optional human-approved outreach. Its lead-to-cash extension drafts proposals, creates PayPal invoices after approval, and uses payment outcomes to calibrate scoring. The README describes the major product stages; the pipeline excerpt confirms its processing sequence, while the source index supports several module relationships. Many subsystem implementations were not sampled, so their internal links are omitted rather than inferred.

Main entry points: [`gtm_engine/pipeline.py`](https://github.com/adeel-parvaiz/qualifyr/blob/main/gtm_engine/pipeline.py) (Campaign pipeline), [`web/src/app/(app)/campaigns/page.tsx`](https://github.com/adeel-parvaiz/qualifyr/blob/main/web/src/app/(app)/campaigns/page.tsx) (Dashboard UI), [`gtm_engine/paypal/service.py`](https://github.com/adeel-parvaiz/qualifyr/blob/main/gtm_engine/paypal/service.py) (Payment workflow), [`gtm_engine/api/main.py`](https://github.com/adeel-parvaiz/qualifyr/blob/main/gtm_engine/api/main.py) (FastAPI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web product"]
  node_webapp["Dashboard UI<br/>[page.tsx]"]
  node_webapi["Web API client<br/>[api.ts]"]
  node_api["FastAPI<br/>[main.py]"]
end

subgraph group_campaign["Campaign setup"]
  node_config["Campaign config<br/>[schema.py]"]
  node_nlparser["Offer parser<br/>[nl_parser.py]"]
  node_pipeline["Campaign pipeline<br/>[pipeline.py]"]
end

subgraph group_leads["Lead research"]
  node_discovery["Company discovery"]
  node_targeting["Offer targeting<br/>[targeting.py]"]
  node_scraping["Website crawling"]
  node_qualification["Buyer qualification"]
  node_intent["Buying intent"]
  node_enrichment["Contact enrichment"]
  node_validation["Lead validation"]
  node_scoring["Lead scoring<br/>[scoring.py]"]
  node_models["Lead data models<br/>[models.py]"]
end

subgraph group_delivery["Lead delivery"]
  node_database[("Postgres storage<br/>[database.py]")]
  node_exports["Lead exports"]
  node_outreach["Approval-gated outreach"]
end

subgraph group_revenue["PayPal revenue"]
  node_paypalroutes["PayPal routes<br/>[paypal_routes.py]"]
  node_paypalservice["Payment workflow<br/>[service.py]"]
  node_paypalstore[("Payment records<br/>[store.py]")]
  node_paypalclient["PayPal client<br/>[client.py]"]
  node_calibration["Score calibration<br/>[calibration.py]"]
end

node_user(("Sales user"))

node_user -->|"describes offer"| node_webapp
node_webapp -->|"requests data"| node_webapi
node_webapi -->|"calls API"| node_api
node_api -->|"reads and writes"| node_database
node_user -->|"describes offer"| node_nlparser
node_nlparser -->|"builds targets"| node_config
node_pipeline -->|"discovers companies"| node_discovery
node_pipeline -->|"crawls sites"| node_scraping
node_pipeline -->|"classifies buyers"| node_qualification
node_pipeline -->|"enriches leads"| node_enrichment
node_pipeline -->|"validates leads"| node_validation
node_pipeline -->|"scores leads"| node_scoring
node_pipeline -->|"stores results"| node_database
node_pipeline -->|"derives targets"| node_targeting
node_targeting -->|"loads settings"| node_config
node_targeting -.->|"optional intent"| node_intent
node_database -->|"stores leads"| node_models
node_webapp -->|"exports CSV"| node_exports
node_webapp -->|"reviews drafts"| node_outreach
node_api -->|"mounts routes"| node_paypalroutes
node_paypalroutes -->|"handles payments"| node_paypalservice
node_paypalservice -->|"records payment state"| node_paypalstore
node_paypalservice -->|"calls PayPal"| node_paypalclient
node_paypalservice -->|"calibrates scores"| node_calibration
node_paypalclient -.->|"verifies webhooks"| node_paypalroutes

click node_webapp "https://github.com/adeel-parvaiz/qualifyr/blob/main/web/src/app/(app)/campaigns/page.tsx"
click node_webapi "https://github.com/adeel-parvaiz/qualifyr/blob/main/web/src/lib/api.ts"
click node_api "https://github.com/adeel-parvaiz/qualifyr/blob/main/gtm_engine/api/main.py"
click node_config "https://github.com/adeel-parvaiz/qualifyr/blob/main/gtm_engine/config/schema.py"
click node_nlparser "https://github.com/adeel-parvaiz/qualifyr/blob/main/gtm_engine/campaign/nl_parser.py"
click node_pipeline "https://github.com/adeel-parvaiz/qualifyr/blob/main/gtm_engine/pipeline.py"
click node_discovery "https://github.com/adeel-parvaiz/qualifyr/tree/main/gtm_engine/discovery"
click node_targeting "https://github.com/adeel-parvaiz/qualifyr/blob/main/gtm_engine/discovery/targeting.py"
click node_scraping "https://github.com/adeel-parvaiz/qualifyr/tree/main/gtm_engine/scraping"
click node_qualification "https://github.com/adeel-parvaiz/qualifyr/tree/main/gtm_engine/qualification"
click node_intent "https://github.com/adeel-parvaiz/qualifyr/tree/main/gtm_engine/intent"
click node_enrichment "https://github.com/adeel-parvaiz/qualifyr/tree/main/gtm_engine/enrichment"
click node_validation "https://github.com/adeel-parvaiz/qualifyr/tree/main/gtm_engine/validation"
click node_scoring "https://github.com/adeel-parvaiz/qualifyr/blob/main/gtm_engine/scoring/scoring.py"
click node_models "https://github.com/adeel-parvaiz/qualifyr/blob/main/gtm_engine/models.py"
click node_database "https://github.com/adeel-parvaiz/qualifyr/blob/main/gtm_engine/storage/database.py"
click node_exports "https://github.com/adeel-parvaiz/qualifyr/tree/main/gtm_engine/export"
click node_outreach "https://github.com/adeel-parvaiz/qualifyr/tree/main/gtm_engine/outreach"
click node_paypalroutes "https://github.com/adeel-parvaiz/qualifyr/blob/main/gtm_engine/api/paypal_routes.py"
click node_paypalservice "https://github.com/adeel-parvaiz/qualifyr/blob/main/gtm_engine/paypal/service.py"
click node_paypalstore "https://github.com/adeel-parvaiz/qualifyr/blob/main/gtm_engine/paypal/store.py"
click node_paypalclient "https://github.com/adeel-parvaiz/qualifyr/blob/main/gtm_engine/paypal/client.py"
click node_calibration "https://github.com/adeel-parvaiz/qualifyr/blob/main/gtm_engine/paypal/calibration.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_webapp,node_webapi,node_api,node_user toneBlue
class node_config,node_nlparser,node_pipeline toneAmber
class node_discovery,node_targeting,node_scraping,node_qualification,node_intent,node_enrichment,node_validation,node_scoring,node_models toneMint
class node_database,node_exports,node_outreach toneRose
class node_paypalroutes,node_paypalservice,node_paypalstore,node_paypalclient,node_calibration toneIndigo
```

## Components

### Web product

- [Dashboard UI](https://github.com/adeel-parvaiz/qualifyr/blob/main/web/src/app/(app)/campaigns/page.tsx): `web/src/app/(app)/campaigns/page.tsx`
- [Web API client](https://github.com/adeel-parvaiz/qualifyr/blob/main/web/src/lib/api.ts): `web/src/lib/api.ts`
- [FastAPI](https://github.com/adeel-parvaiz/qualifyr/blob/main/gtm_engine/api/main.py): `gtm_engine/api/main.py`

### Campaign setup

- [Campaign config](https://github.com/adeel-parvaiz/qualifyr/blob/main/gtm_engine/config/schema.py): `gtm_engine/config/schema.py`
- [Offer parser](https://github.com/adeel-parvaiz/qualifyr/blob/main/gtm_engine/campaign/nl_parser.py): `gtm_engine/campaign/nl_parser.py`
- [Campaign pipeline](https://github.com/adeel-parvaiz/qualifyr/blob/main/gtm_engine/pipeline.py): `gtm_engine/pipeline.py`

### Lead research

- [Company discovery](https://github.com/adeel-parvaiz/qualifyr/tree/main/gtm_engine/discovery): `gtm_engine/discovery`
- [Offer targeting](https://github.com/adeel-parvaiz/qualifyr/blob/main/gtm_engine/discovery/targeting.py): `gtm_engine/discovery/targeting.py`
- [Website crawling](https://github.com/adeel-parvaiz/qualifyr/tree/main/gtm_engine/scraping): `gtm_engine/scraping`
- [Buyer qualification](https://github.com/adeel-parvaiz/qualifyr/tree/main/gtm_engine/qualification): `gtm_engine/qualification`
- [Buying intent](https://github.com/adeel-parvaiz/qualifyr/tree/main/gtm_engine/intent): `gtm_engine/intent`
- [Contact enrichment](https://github.com/adeel-parvaiz/qualifyr/tree/main/gtm_engine/enrichment): `gtm_engine/enrichment`
- [Lead validation](https://github.com/adeel-parvaiz/qualifyr/tree/main/gtm_engine/validation): `gtm_engine/validation`
- [Lead scoring](https://github.com/adeel-parvaiz/qualifyr/blob/main/gtm_engine/scoring/scoring.py): `gtm_engine/scoring/scoring.py`
- [Lead data models](https://github.com/adeel-parvaiz/qualifyr/blob/main/gtm_engine/models.py): `gtm_engine/models.py`

### Lead delivery

- [Postgres storage](https://github.com/adeel-parvaiz/qualifyr/blob/main/gtm_engine/storage/database.py): `gtm_engine/storage/database.py`
- [Lead exports](https://github.com/adeel-parvaiz/qualifyr/tree/main/gtm_engine/export): `gtm_engine/export`
- [Approval-gated outreach](https://github.com/adeel-parvaiz/qualifyr/tree/main/gtm_engine/outreach): `gtm_engine/outreach`

### PayPal revenue

- [PayPal routes](https://github.com/adeel-parvaiz/qualifyr/blob/main/gtm_engine/api/paypal_routes.py): `gtm_engine/api/paypal_routes.py`
- [Payment workflow](https://github.com/adeel-parvaiz/qualifyr/blob/main/gtm_engine/paypal/service.py): `gtm_engine/paypal/service.py`
- [Payment records](https://github.com/adeel-parvaiz/qualifyr/blob/main/gtm_engine/paypal/store.py): `gtm_engine/paypal/store.py`
- [PayPal client](https://github.com/adeel-parvaiz/qualifyr/blob/main/gtm_engine/paypal/client.py): `gtm_engine/paypal/client.py`
- [Score calibration](https://github.com/adeel-parvaiz/qualifyr/blob/main/gtm_engine/paypal/calibration.py): `gtm_engine/paypal/calibration.py`

### Other components

- **Sales user**

## Connections

- Sales user → Dashboard UI: describes offer (evidence: `README.md`)
- Dashboard UI → Web API client: requests data (evidence: `README.md`)
- Web API client → FastAPI: calls API (evidence: `README.md`)
- FastAPI → Postgres storage: reads and writes (evidence: `gtm_engine/api/main.py`)
- Sales user → Offer parser: describes offer (evidence: `README.md`)
- Offer parser → Campaign config: builds targets (evidence: `gtm_engine/campaign/nl_parser.py`)
- Campaign pipeline → Company discovery: discovers companies (evidence: `gtm_engine/pipeline.py`)
- Campaign pipeline → Website crawling: crawls sites (evidence: `gtm_engine/pipeline.py`)
- Campaign pipeline → Buyer qualification: classifies buyers (evidence: `gtm_engine/pipeline.py`)
- Campaign pipeline → Contact enrichment: enriches leads (evidence: `gtm_engine/pipeline.py`)
- Campaign pipeline → Lead validation: validates leads (evidence: `gtm_engine/pipeline.py`)
- Campaign pipeline → Lead scoring: scores leads (evidence: `gtm_engine/pipeline.py`)
- Campaign pipeline → Postgres storage: stores results (evidence: `README.md`)
- Campaign pipeline → Offer targeting: derives targets (evidence: `gtm_engine/pipeline.py`)
- Offer targeting → Campaign config: loads settings (evidence: `gtm_engine/discovery/targeting.py`)
- Offer targeting → Buying intent: optional intent
- Postgres storage → Lead data models: stores leads (evidence: `gtm_engine/storage/database.py`)
- Dashboard UI → Lead exports: exports CSV (evidence: `README.md`)
- Dashboard UI → Approval-gated outreach: reviews drafts (evidence: `README.md`)
- FastAPI → PayPal routes: mounts routes (evidence: `gtm_engine/api/paypal_routes.py`)
- PayPal routes → Payment workflow: handles payments (evidence: `gtm_engine/api/paypal_routes.py`)
- Payment workflow → Payment records: records payment state (evidence: `gtm_engine/paypal/service.py`)
- Payment workflow → PayPal client: calls PayPal (evidence: `gtm_engine/paypal/service.py`)
- Payment workflow → Score calibration: calibrates scores (evidence: `gtm_engine/paypal/service.py`)
- PayPal client → PayPal routes: verifies webhooks (evidence: `gtm_engine/api/paypal_routes.py`)