# albara-ai/flyrank-capstone-widget-platform architecture

> Architecture diagram of the GitHub repository albara-ai/flyrank-capstone-widget-platform, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/albara-ai/flyrank-capstone-widget-platform
- Repository: https://github.com/albara-ai/flyrank-capstone-widget-platform

## Overview

FlyRank is an embeddable widget and lead-capture platform. Owners configure widgets and embed them on customer sites; visitors submit leads, which are validated, enriched, stored, and queued for background notification and optional intent classification. Owners can review leads and statistics, while cashier and admin flows handle redemption and tenant administration. The README documents these capabilities; some service and route internals were not sampled, so those connections are shown only where documented.

Main entry points: [`app/static/widget.js`](https://github.com/albara-ai/flyrank-capstone-widget-platform/blob/main/app/static/widget.js) (Embedded widget), [`app/api/v1/public.py`](https://github.com/albara-ai/flyrank-capstone-widget-platform/blob/main/app/api/v1/public.py) (Public API), [`app/repositories/submissions.py`](https://github.com/albara-ai/flyrank-capstone-widget-platform/blob/main/app/repositories/submissions.py) (Lead and job storage), [`app/core/db.py`](https://github.com/albara-ai/flyrank-capstone-widget-platform/blob/main/app/core/db.py) (PostgreSQL)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_delivery["Widget delivery"]
  node_widget_ui["Embedded widget<br/>[widget.js]"]
end

subgraph group_intake["Submission intake"]
  node_public_api["Public API<br/>[public.py]"]
  node_submission_input["Submission schema<br/>[submissions.py]"]
  node_submission_service["Submission workflow<br/>[submissions.py]"]
  node_geo_enrichment["Geo enrichment<br/>[geo.py]"]
end

subgraph group_processing["Background processing"]
  node_worker["Job worker<br/>[worker.py]"]
  node_job_handlers["Job handlers<br/>[registry.py]"]
  node_classification["Intent classification<br/>[classification.py]"]
  node_notification["Email notification<br/>[notifications.py]"]
end

subgraph group_management["Owner and admin"]
  node_widget_api["Widget management<br/>[widgets.py]"]
  node_leads_api["Leads and stats<br/>[leads.py]"]
  node_account_api["Account and cashier<br/>[redeem.py]"]
  node_admin_api["Admin console API<br/>[admin.py]"]
  node_owner_ui["Owner and admin UI<br/>[ui.py]"]
end

subgraph group_platform["Platform services"]
  node_geo_providers["Geo providers<br/>[base.py]"]
  node_submission_store[("Lead and job storage<br/>[submissions.py]")]
  node_llm_providers["LLM provider chain<br/>[factory.py]"]
  node_tenant_service["Tenant and keys<br/>[tenants.py]"]
  node_database[("PostgreSQL<br/>[db.py]")]
end

node_owner(("Widget owner"))
node_customer_site["Customer site"]
node_visitor(("Site visitor"))

node_owner -->|"manages widgets"| node_widget_api
node_owner -->|"reviews leads"| node_leads_api
node_customer_site -->|"loads script"| node_widget_ui
node_widget_ui -->|"fetches config"| node_public_api
node_visitor -->|"fills form"| node_widget_ui
node_widget_ui -->|"posts submission"| node_public_api
node_public_api -->|"validates input"| node_submission_input
node_public_api -->|"processes submission"| node_submission_service
node_submission_service -->|"enriches location"| node_geo_enrichment
node_geo_enrichment -->|"queries providers"| node_geo_providers
node_submission_service -->|"stores lead and jobs"| node_submission_store
node_submission_store -->|"writes records"| node_database
node_worker -->|"dispatches jobs"| node_job_handlers
node_job_handlers -->|"classifies intent"| node_classification
node_classification -->|"uses provider chain"| node_llm_providers
node_job_handlers -->|"sends notification"| node_notification
node_worker -->|"claims and updates jobs"| node_submission_store
node_widget_api -.->|"manages widget data"| node_database
node_leads_api -.->|"reads leads"| node_submission_store
node_account_api -.->|"checks account"| node_tenant_service
node_admin_api -->|"administers tenants"| node_tenant_service
node_owner -->|"uses web pages"| node_owner_ui
node_owner_ui -.->|"calls management API"| node_widget_api
node_owner_ui -.->|"views dashboard"| node_leads_api
node_admin_api -.->|"administers records"| node_database
node_tenant_service -.->|"stores tenants and keys"| node_database

click node_widget_ui "https://github.com/albara-ai/flyrank-capstone-widget-platform/blob/main/app/static/widget.js"
click node_public_api "https://github.com/albara-ai/flyrank-capstone-widget-platform/blob/main/app/api/v1/public.py"
click node_submission_input "https://github.com/albara-ai/flyrank-capstone-widget-platform/blob/main/app/domain/submissions.py"
click node_submission_service "https://github.com/albara-ai/flyrank-capstone-widget-platform/blob/main/app/services/submissions.py"
click node_geo_enrichment "https://github.com/albara-ai/flyrank-capstone-widget-platform/blob/main/app/services/geo.py"
click node_geo_providers "https://github.com/albara-ai/flyrank-capstone-widget-platform/blob/main/app/providers/geo/base.py"
click node_submission_store "https://github.com/albara-ai/flyrank-capstone-widget-platform/blob/main/app/repositories/submissions.py"
click node_worker "https://github.com/albara-ai/flyrank-capstone-widget-platform/blob/main/app/jobs/worker.py"
click node_job_handlers "https://github.com/albara-ai/flyrank-capstone-widget-platform/blob/main/app/jobs/registry.py"
click node_classification "https://github.com/albara-ai/flyrank-capstone-widget-platform/blob/main/app/services/classification.py"
click node_llm_providers "https://github.com/albara-ai/flyrank-capstone-widget-platform/blob/main/app/providers/factory.py"
click node_notification "https://github.com/albara-ai/flyrank-capstone-widget-platform/blob/main/app/services/notifications.py"
click node_widget_api "https://github.com/albara-ai/flyrank-capstone-widget-platform/blob/main/app/api/v1/widgets.py"
click node_leads_api "https://github.com/albara-ai/flyrank-capstone-widget-platform/blob/main/app/api/v1/leads.py"
click node_account_api "https://github.com/albara-ai/flyrank-capstone-widget-platform/blob/main/app/api/v1/redeem.py"
click node_admin_api "https://github.com/albara-ai/flyrank-capstone-widget-platform/blob/main/app/api/v1/admin.py"
click node_owner_ui "https://github.com/albara-ai/flyrank-capstone-widget-platform/blob/main/app/api/ui.py"
click node_tenant_service "https://github.com/albara-ai/flyrank-capstone-widget-platform/blob/main/app/services/tenants.py"
click node_database "https://github.com/albara-ai/flyrank-capstone-widget-platform/blob/main/app/core/db.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_widget_ui toneBlue
class node_public_api,node_submission_input,node_submission_service,node_geo_enrichment toneAmber
class node_worker,node_job_handlers,node_classification,node_notification toneMint
class node_widget_api,node_leads_api,node_account_api,node_admin_api,node_owner_ui toneRose
class node_geo_providers,node_submission_store,node_llm_providers,node_tenant_service,node_database,node_owner,node_customer_site,node_visitor toneIndigo
```

## Components

### Widget delivery

- [Embedded widget](https://github.com/albara-ai/flyrank-capstone-widget-platform/blob/main/app/static/widget.js): `app/static/widget.js`

### Submission intake

- [Public API](https://github.com/albara-ai/flyrank-capstone-widget-platform/blob/main/app/api/v1/public.py): `app/api/v1/public.py`
- [Submission schema](https://github.com/albara-ai/flyrank-capstone-widget-platform/blob/main/app/domain/submissions.py): `app/domain/submissions.py`
- [Submission workflow](https://github.com/albara-ai/flyrank-capstone-widget-platform/blob/main/app/services/submissions.py): `app/services/submissions.py`
- [Geo enrichment](https://github.com/albara-ai/flyrank-capstone-widget-platform/blob/main/app/services/geo.py): `app/services/geo.py`

### Background processing

- [Job worker](https://github.com/albara-ai/flyrank-capstone-widget-platform/blob/main/app/jobs/worker.py): `app/jobs/worker.py`
- [Job handlers](https://github.com/albara-ai/flyrank-capstone-widget-platform/blob/main/app/jobs/registry.py): `app/jobs/registry.py`
- [Intent classification](https://github.com/albara-ai/flyrank-capstone-widget-platform/blob/main/app/services/classification.py): `app/services/classification.py`
- [Email notification](https://github.com/albara-ai/flyrank-capstone-widget-platform/blob/main/app/services/notifications.py): `app/services/notifications.py`

### Owner and admin

- [Widget management](https://github.com/albara-ai/flyrank-capstone-widget-platform/blob/main/app/api/v1/widgets.py): `app/api/v1/widgets.py`
- [Leads and stats](https://github.com/albara-ai/flyrank-capstone-widget-platform/blob/main/app/api/v1/leads.py): `app/api/v1/leads.py`
- [Account and cashier](https://github.com/albara-ai/flyrank-capstone-widget-platform/blob/main/app/api/v1/redeem.py): `app/api/v1/redeem.py`
- [Admin console API](https://github.com/albara-ai/flyrank-capstone-widget-platform/blob/main/app/api/v1/admin.py): `app/api/v1/admin.py`
- [Owner and admin UI](https://github.com/albara-ai/flyrank-capstone-widget-platform/blob/main/app/api/ui.py): `app/api/ui.py`

### Platform services

- [Geo providers](https://github.com/albara-ai/flyrank-capstone-widget-platform/blob/main/app/providers/geo/base.py): `app/providers/geo/base.py`
- [Lead and job storage](https://github.com/albara-ai/flyrank-capstone-widget-platform/blob/main/app/repositories/submissions.py): `app/repositories/submissions.py`
- [LLM provider chain](https://github.com/albara-ai/flyrank-capstone-widget-platform/blob/main/app/providers/factory.py): `app/providers/factory.py`
- [Tenant and keys](https://github.com/albara-ai/flyrank-capstone-widget-platform/blob/main/app/services/tenants.py): `app/services/tenants.py`
- [PostgreSQL](https://github.com/albara-ai/flyrank-capstone-widget-platform/blob/main/app/core/db.py): `app/core/db.py`

### Other components

- **Widget owner**
- **Customer site**
- **Site visitor**

## Connections

- Widget owner → Widget management: manages widgets
- Widget owner → Leads and stats: reviews leads
- Customer site → Embedded widget: loads script
- Embedded widget → Public API: fetches config
- Site visitor → Embedded widget: fills form
- Embedded widget → Public API: posts submission
- Public API → Submission schema: validates input (evidence: `app/api/v1/public.py`)
- Public API → Submission workflow: processes submission (evidence: `app/api/v1/public.py`)
- Submission workflow → Geo enrichment: enriches location
- Geo enrichment → Geo providers: queries providers
- Submission workflow → Lead and job storage: stores lead and jobs
- Lead and job storage → PostgreSQL: writes records (evidence: `app/repositories/submissions.py`)
- Job worker → Job handlers: dispatches jobs (evidence: `app/jobs/worker.py`)
- Job handlers → Intent classification: classifies intent (evidence: `app/jobs/registry.py`)
- Intent classification → LLM provider chain: uses provider chain (evidence: `app/services/classification.py`)
- Job handlers → Email notification: sends notification (evidence: `app/jobs/registry.py`)
- Job worker → Lead and job storage: claims and updates jobs (evidence: `app/jobs/worker.py`)
- Widget management → PostgreSQL: manages widget data
- Leads and stats → Lead and job storage: reads leads
- Account and cashier → Tenant and keys: checks account
- Admin console API → Tenant and keys: administers tenants (evidence: `app/api/v1/admin.py`)
- Widget owner → Owner and admin UI: uses web pages
- Owner and admin UI → Widget management: calls management API
- Owner and admin UI → Leads and stats: views dashboard
- Admin console API → PostgreSQL: administers records
- Tenant and keys → PostgreSQL: stores tenants and keys (evidence: `app/services/tenants.py`)
