# ahtesham-latif/flyrank-capstone-widgetplatform- architecture

> Architecture diagram of the GitHub repository ahtesham-latif/flyrank-capstone-widgetplatform-, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ahtesham-latif/flyrank-capstone-widgetplatform-
- Repository: https://github.com/ahtesham-latif/flyrank-capstone-widgetplatform-

## Overview

SignalLead lets widget owners configure embeddable lead forms, then captures submissions from visitors on external sites. The main flow is widget setup → script/config delivery → protected submission intake → enrichment and storage → tenant-scoped lead viewing, with optional webhook notification. The graph uses sampled backend source for those calls; dashboard details and several README-described security capabilities are represented only where their paths or wiring are supported by the tree.

Main entry points: [`src/app.js`](https://github.com/ahtesham-latif/flyrank-capstone-widgetplatform-/blob/main/src/app.js) (Express application), [`src/controllers/submission.controller.js`](https://github.com/ahtesham-latif/flyrank-capstone-widgetplatform-/blob/main/src/controllers/submission.controller.js) (Submission intake), [`src/routes/submission.routes.js`](https://github.com/ahtesham-latif/flyrank-capstone-widgetplatform-/blob/main/src/routes/submission.routes.js) (Submission routes), [`src/controllers/delivery.controller.js`](https://github.com/ahtesham-latif/flyrank-capstone-widgetplatform-/blob/main/src/controllers/delivery.controller.js) (Script and config delivery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Owner control plane"]
  node_ui["Control plane UI<br/>[App.tsx]"]
  node_ui_api["Frontend API client<br/>[index.ts]"]
  node_dashboard["Widget and lead views<br/>[Dashboard.tsx]"]
  node_demo["Widget demo<br/>[Demo.tsx]"]
end

subgraph group_boundary["API boundary"]
  node_app["Express application<br/>[app.js]"]
  node_auth_routes["Auth routes<br/>[auth.routes.js]"]
  node_auth_controller["Auth controller<br/>[auth.controller.js]"]
  node_auth_mw["Session authorization<br/>[auth.middleware.js]"]
  node_cors["Origin validation<br/>[cors.middleware.js]"]
  node_session["Session handling"]
  node_widget_routes["Widget routes<br/>[widget.routes.js]"]
  node_delivery_routes["Public delivery routes<br/>[delivery.routes.js]"]
  node_submission_routes["Submission routes"]
  node_limiter["Submission rate limit"]
end

subgraph group_delivery["Widget delivery"]
  node_widget_controller["Widget management"]
  node_delivery_controller["Script and config delivery"]
end

subgraph group_capture["Lead processing"]
  node_submission_controller["Submission intake"]
  node_geo["Geo-IP enrichment<br/>[geoip.service.js]"]
  node_webhook["Webhook notification<br/>[webhook.service.js]"]
end

subgraph group_data["Persistence and integrations"]
  node_widget_repo["Widget repository"]
  node_user_repo["User repository<br/>[user.repository.js]"]
  node_submission_repo["Submission repository"]
  node_db[("PostgreSQL database<br/>[db.js]")]
end

node_owner(("Widget owner"))
node_site(("Customer website"))
node_visitor(("Website visitor"))
node_geo_primary["ip-api.com"]
node_geo_fallback["ipapi.co"]
node_n8n["n8n webhook endpoint"]

node_owner -->|"uses"| node_ui
node_ui -->|"renders"| node_dashboard
node_ui -->|"renders"| node_demo
node_dashboard -->|"requests data"| node_ui_api
node_ui_api -->|"calls API"| node_app
node_app -->|"checks origins"| node_cors
node_app -->|"establishes sessions"| node_session
node_app -->|"mounts"| node_auth_routes
node_app -->|"mounts"| node_widget_routes
node_app -->|"mounts"| node_delivery_routes
node_app -->|"mounts"| node_submission_routes
node_auth_routes -->|"dispatches"| node_auth_controller
node_widget_routes -->|"requires authentication"| node_auth_mw
node_widget_routes -->|"dispatches"| node_widget_controller
node_submission_routes -->|"protects lead listing"| node_auth_mw
node_submission_routes -->|"limits public intake"| node_limiter
node_submission_routes -->|"dispatches"| node_submission_controller
node_widget_controller -->|"manages widgets"| node_widget_repo
node_delivery_routes -->|"dispatches"| node_delivery_controller
node_delivery_controller -->|"reads widget config"| node_widget_repo
node_site -->|"loads script"| node_delivery_routes
node_delivery_controller -->|"delivers embed script"| node_site
node_site -->|"requests config"| node_delivery_controller
node_visitor -->|"submits form"| node_site
node_site -->|"posts submission"| node_submission_routes
node_submission_controller -->|"resolves widget"| node_widget_repo
node_submission_controller -->|"loads owner"| node_user_repo
node_submission_controller -->|"enriches IP"| node_geo
node_geo -.->|"looks up IP"| node_geo_primary
node_geo -.->|"falls back"| node_geo_fallback
node_submission_controller -->|"saves and lists leads"| node_submission_repo
node_submission_controller -->|"notifies asynchronously"| node_webhook
node_webhook -.->|"sends notification"| node_n8n
node_widget_repo -->|"reads and writes"| node_db
node_user_repo -->|"reads users"| node_db
node_submission_repo -->|"reads and writes"| node_db

click node_ui "https://github.com/ahtesham-latif/flyrank-capstone-widgetplatform-/blob/main/frontend/src/App.tsx"
click node_ui_api "https://github.com/ahtesham-latif/flyrank-capstone-widgetplatform-/blob/main/frontend/src/api/index.ts"
click node_dashboard "https://github.com/ahtesham-latif/flyrank-capstone-widgetplatform-/blob/main/frontend/src/pages/Dashboard.tsx"
click node_demo "https://github.com/ahtesham-latif/flyrank-capstone-widgetplatform-/blob/main/frontend/src/pages/Demo.tsx"
click node_app "https://github.com/ahtesham-latif/flyrank-capstone-widgetplatform-/blob/main/src/app.js"
click node_auth_routes "https://github.com/ahtesham-latif/flyrank-capstone-widgetplatform-/blob/main/src/routes/auth.routes.js"
click node_auth_controller "https://github.com/ahtesham-latif/flyrank-capstone-widgetplatform-/blob/main/src/controllers/auth.controller.js"
click node_auth_mw "https://github.com/ahtesham-latif/flyrank-capstone-widgetplatform-/blob/main/src/middlewares/auth.middleware.js"
click node_cors "https://github.com/ahtesham-latif/flyrank-capstone-widgetplatform-/blob/main/src/middlewares/cors.middleware.js"
click node_session "https://github.com/ahtesham-latif/flyrank-capstone-widgetplatform-/blob/main/src/middlewares/session.middleware.js"
click node_widget_routes "https://github.com/ahtesham-latif/flyrank-capstone-widgetplatform-/blob/main/src/routes/widget.routes.js"
click node_widget_controller "https://github.com/ahtesham-latif/flyrank-capstone-widgetplatform-/blob/main/src/controllers/widget.controller.js"
click node_delivery_routes "https://github.com/ahtesham-latif/flyrank-capstone-widgetplatform-/blob/main/src/routes/delivery.routes.js"
click node_delivery_controller "https://github.com/ahtesham-latif/flyrank-capstone-widgetplatform-/blob/main/src/controllers/delivery.controller.js"
click node_submission_routes "https://github.com/ahtesham-latif/flyrank-capstone-widgetplatform-/blob/main/src/routes/submission.routes.js"
click node_limiter "https://github.com/ahtesham-latif/flyrank-capstone-widgetplatform-/blob/main/src/middlewares/rateLimit.middleware.js"
click node_submission_controller "https://github.com/ahtesham-latif/flyrank-capstone-widgetplatform-/blob/main/src/controllers/submission.controller.js"
click node_geo "https://github.com/ahtesham-latif/flyrank-capstone-widgetplatform-/blob/main/src/services/geoip.service.js"
click node_webhook "https://github.com/ahtesham-latif/flyrank-capstone-widgetplatform-/blob/main/src/services/webhook.service.js"
click node_widget_repo "https://github.com/ahtesham-latif/flyrank-capstone-widgetplatform-/blob/main/src/repositories/widget.repository.js"
click node_user_repo "https://github.com/ahtesham-latif/flyrank-capstone-widgetplatform-/blob/main/src/repositories/user.repository.js"
click node_submission_repo "https://github.com/ahtesham-latif/flyrank-capstone-widgetplatform-/blob/main/src/repositories/submission.repository.js"
click node_db "https://github.com/ahtesham-latif/flyrank-capstone-widgetplatform-/blob/main/src/config/db.js"

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_ui,node_ui_api,node_dashboard,node_demo toneBlue
class node_app,node_auth_routes,node_auth_controller,node_auth_mw,node_cors,node_session,node_widget_routes,node_delivery_routes,node_submission_routes,node_limiter toneAmber
class node_widget_controller,node_delivery_controller,node_geo_primary,node_geo_fallback,node_n8n toneMint
class node_submission_controller,node_geo,node_webhook toneRose
class node_widget_repo,node_user_repo,node_submission_repo,node_db,node_owner,node_site,node_visitor toneIndigo
```

## Components

### Owner control plane

- [Control plane UI](https://github.com/ahtesham-latif/flyrank-capstone-widgetplatform-/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Frontend API client](https://github.com/ahtesham-latif/flyrank-capstone-widgetplatform-/blob/main/frontend/src/api/index.ts): `frontend/src/api/index.ts`
- [Widget and lead views](https://github.com/ahtesham-latif/flyrank-capstone-widgetplatform-/blob/main/frontend/src/pages/Dashboard.tsx): `frontend/src/pages/Dashboard.tsx`
- [Widget demo](https://github.com/ahtesham-latif/flyrank-capstone-widgetplatform-/blob/main/frontend/src/pages/Demo.tsx): `frontend/src/pages/Demo.tsx`

### API boundary

- [Express application](https://github.com/ahtesham-latif/flyrank-capstone-widgetplatform-/blob/main/src/app.js): `src/app.js`
- [Auth routes](https://github.com/ahtesham-latif/flyrank-capstone-widgetplatform-/blob/main/src/routes/auth.routes.js): `src/routes/auth.routes.js`
- [Auth controller](https://github.com/ahtesham-latif/flyrank-capstone-widgetplatform-/blob/main/src/controllers/auth.controller.js): `src/controllers/auth.controller.js`
- [Session authorization](https://github.com/ahtesham-latif/flyrank-capstone-widgetplatform-/blob/main/src/middlewares/auth.middleware.js): `src/middlewares/auth.middleware.js`
- [Origin validation](https://github.com/ahtesham-latif/flyrank-capstone-widgetplatform-/blob/main/src/middlewares/cors.middleware.js): `src/middlewares/cors.middleware.js`
- [Session handling](https://github.com/ahtesham-latif/flyrank-capstone-widgetplatform-/blob/main/src/middlewares/session.middleware.js): `src/middlewares/session.middleware.js`
- [Widget routes](https://github.com/ahtesham-latif/flyrank-capstone-widgetplatform-/blob/main/src/routes/widget.routes.js): `src/routes/widget.routes.js`
- [Public delivery routes](https://github.com/ahtesham-latif/flyrank-capstone-widgetplatform-/blob/main/src/routes/delivery.routes.js): `src/routes/delivery.routes.js`
- [Submission routes](https://github.com/ahtesham-latif/flyrank-capstone-widgetplatform-/blob/main/src/routes/submission.routes.js): `src/routes/submission.routes.js`
- [Submission rate limit](https://github.com/ahtesham-latif/flyrank-capstone-widgetplatform-/blob/main/src/middlewares/rateLimit.middleware.js): `src/middlewares/rateLimit.middleware.js`

### Widget delivery

- [Widget management](https://github.com/ahtesham-latif/flyrank-capstone-widgetplatform-/blob/main/src/controllers/widget.controller.js): `src/controllers/widget.controller.js`
- [Script and config delivery](https://github.com/ahtesham-latif/flyrank-capstone-widgetplatform-/blob/main/src/controllers/delivery.controller.js): `src/controllers/delivery.controller.js`

### Lead processing

- [Submission intake](https://github.com/ahtesham-latif/flyrank-capstone-widgetplatform-/blob/main/src/controllers/submission.controller.js): `src/controllers/submission.controller.js`
- [Geo-IP enrichment](https://github.com/ahtesham-latif/flyrank-capstone-widgetplatform-/blob/main/src/services/geoip.service.js): `src/services/geoip.service.js`
- [Webhook notification](https://github.com/ahtesham-latif/flyrank-capstone-widgetplatform-/blob/main/src/services/webhook.service.js): `src/services/webhook.service.js`

### Persistence and integrations

- [Widget repository](https://github.com/ahtesham-latif/flyrank-capstone-widgetplatform-/blob/main/src/repositories/widget.repository.js): `src/repositories/widget.repository.js`
- [User repository](https://github.com/ahtesham-latif/flyrank-capstone-widgetplatform-/blob/main/src/repositories/user.repository.js): `src/repositories/user.repository.js`
- [Submission repository](https://github.com/ahtesham-latif/flyrank-capstone-widgetplatform-/blob/main/src/repositories/submission.repository.js): `src/repositories/submission.repository.js`
- [PostgreSQL database](https://github.com/ahtesham-latif/flyrank-capstone-widgetplatform-/blob/main/src/config/db.js): `src/config/db.js`

### Other components

- **Widget owner**
- **Customer website**
- **Website visitor**
- **ip-api.com**
- **ipapi.co**
- **n8n webhook endpoint**

## Connections

- Widget owner → Control plane UI: uses
- Control plane UI → Widget and lead views: renders
- Control plane UI → Widget demo: renders
- Widget and lead views → Frontend API client: requests data
- Frontend API client → Express application: calls API
- Express application → Origin validation: checks origins
- Express application → Session handling: establishes sessions
- Express application → Auth routes: mounts
- Express application → Widget routes: mounts
- Express application → Public delivery routes: mounts
- Express application → Submission routes: mounts
- Auth routes → Auth controller: dispatches
- Widget routes → Session authorization: requires authentication
- Widget routes → Widget management: dispatches
- Submission routes → Session authorization: protects lead listing
- Submission routes → Submission rate limit: limits public intake
- Submission routes → Submission intake: dispatches
- Widget management → Widget repository: manages widgets
- Public delivery routes → Script and config delivery: dispatches
- Script and config delivery → Widget repository: reads widget config
- Customer website → Public delivery routes: loads script
- Script and config delivery → Customer website: delivers embed script
- Customer website → Script and config delivery: requests config
- Website visitor → Customer website: submits form
- Customer website → Submission routes: posts submission
- Submission intake → Widget repository: resolves widget
- Submission intake → User repository: loads owner
- Submission intake → Geo-IP enrichment: enriches IP
- Geo-IP enrichment → ip-api.com: looks up IP
- Geo-IP enrichment → ipapi.co: falls back
- Submission intake → Submission repository: saves and lists leads
- Submission intake → Webhook notification: notifies asynchronously
- Webhook notification → n8n webhook endpoint: sends notification
- Widget repository → PostgreSQL database: reads and writes
- User repository → PostgreSQL database: reads users
- Submission repository → PostgreSQL database: reads and writes