# uttomkumar143/trafficvaulthub architecture

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

- Interactive diagram: https://gitdiagram.com/uttomkumar143/trafficvaulthub
- Repository: https://github.com/uttomkumar143/trafficvaulthub
- Video tour (about a minute): https://gitdiagram.com/uttomkumar143/trafficvaulthub/video

## Overview

TrafficVaultHub is a CPA affiliate-network platform with a React SPA and a Hono API on Cloudflare Workers. Its central workflow is offer discovery and setup, tracked referrals and attribution, conversion validation and risk/compliance review, then ledger accounting, advertiser billing and affiliate payouts. Operations also include identity, tenant-scoped access, support, reporting, notifications, APIs and webhooks. The graph combines sampled wiring with README-described product capabilities; several domain links are documented capability relationships rather than inspected call paths.

Main entry points: [`backend/src/app.ts`](https://github.com/uttomkumar143/trafficvaulthub/blob/main/backend/src/app.ts) (Hono API and wiring), [`frontend/src/lib/api.ts`](https://github.com/uttomkumar143/trafficvaulthub/blob/main/frontend/src/lib/api.ts) (API client), [`backend/src/modules/conversions/service.ts`](https://github.com/uttomkumar143/trafficvaulthub/blob/main/backend/src/modules/conversions/service.ts) (Conversion validation), [`backend/src/modules/ledger/journal.ts`](https://github.com/uttomkumar143/trafficvaulthub/blob/main/backend/src/modules/ledger/journal.ts) (Immutable ledger)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_spa["React application<br/>[app.tsx]"]
  node_frontend_api["API client<br/>[api.ts]"]
  node_auth_ui["Authentication UI<br/>[auth-context.tsx]"]
  node_offer_ui["Offer marketplace UI<br/>[api.ts]"]
  node_dash_ui["Affiliate dashboard UI<br/>[api.ts]"]
end

subgraph group_identity["Identity and access"]
  node_auth["Authentication service<br/>[service.ts]"]
  node_auth_store[("Identity persistence<br/>[repository.ts]")]
  node_tenant["Tenant and RBAC<br/>[require-org.ts]"]
  node_orgs["Organizations"]
  node_platform_lib["Worker bindings and tenant helpers"]
end

subgraph group_market["Marketplace and tracking"]
  node_offers["Offer policy and lifecycle<br/>[service.ts]"]
  node_advertisers["Advertiser profiles"]
  node_affiliates["Affiliate profiles<br/>[service.ts]"]
  node_tracking["Tracking and SmartLinks"]
  node_attribution["Attribution"]
end

subgraph group_operations["Risk and operations"]
  node_conversions["Conversion validation<br/>[service.ts]"]
  node_fraud["Fraud risk engine<br/>[risk-engine.ts]"]
  node_compliance["Compliance review<br/>[service.ts]"]
  node_support["Support and disputes"]
end

subgraph group_finance["Finance and delivery"]
  node_ledger[("Immutable ledger<br/>[journal.ts]")]
  node_billing["Advertiser billing<br/>[service.ts]"]
  node_payouts["Affiliate payouts<br/>[service.ts]"]
  node_reconciliation["Reconciliation<br/>[service.ts]"]
  node_webhooks["Webhooks<br/>[service.ts]"]
  node_webhook_transport["Webhook transport<br/>[transport.ts]"]
  node_integrations["External integrations"]
end

node_users(("Network users"))
node_worker["Hono API and wiring<br/>[app.ts]"]

node_users -->|"use"| node_spa
node_spa -.->|"requests"| node_frontend_api
node_frontend_api -.->|"calls REST API"| node_worker
node_worker -->|"wires services"| node_auth
node_worker -->|"wires services"| node_offers
node_worker -->|"wires services"| node_tracking
node_worker -->|"configures transport"| node_webhook_transport
node_worker -->|"configures adapters"| node_integrations
node_auth_ui -.->|"uses"| node_frontend_api
node_offer_ui -.->|"uses"| node_frontend_api
node_dash_ui -.->|"uses"| node_frontend_api
node_auth -->|"persists identity"| node_auth_store
node_tenant -->|"resolves membership"| node_orgs
node_offers -->|"checks advertiser"| node_advertisers
node_offers -->|"invalidates eligibility cache"| node_tracking
node_users -->|"manage offers"| node_offers
node_users -->|"apply as publisher"| node_affiliates
node_tracking -->|"records attribution"| node_attribution
node_tracking -->|"tracks conversions"| node_conversions
node_conversions -->|"checks risk"| node_fraud
node_conversions -->|"supports review"| node_compliance
node_conversions -.->|"accounts approved activity"| node_ledger
node_ledger -.->|"supports billing"| node_billing
node_ledger -->|"funds payouts"| node_payouts
node_ledger -.->|"reconciles balances"| node_reconciliation
node_users -->|"request assistance"| node_support
node_webhooks -->|"dispatches deliveries"| node_webhook_transport
node_webhooks -.->|"delivers event notifications"| node_integrations
node_platform_lib -->|"provides bindings"| node_tenant

click node_spa "https://github.com/uttomkumar143/trafficvaulthub/blob/main/frontend/src/app/app.tsx"
click node_frontend_api "https://github.com/uttomkumar143/trafficvaulthub/blob/main/frontend/src/lib/api.ts"
click node_auth_ui "https://github.com/uttomkumar143/trafficvaulthub/blob/main/frontend/src/features/auth/auth-context.tsx"
click node_offer_ui "https://github.com/uttomkumar143/trafficvaulthub/blob/main/frontend/src/features/offers/api.ts"
click node_dash_ui "https://github.com/uttomkumar143/trafficvaulthub/blob/main/frontend/src/features/affiliate-dashboard/api.ts"
click node_worker "https://github.com/uttomkumar143/trafficvaulthub/blob/main/backend/src/app.ts"
click node_auth "https://github.com/uttomkumar143/trafficvaulthub/blob/main/backend/src/modules/auth/service.ts"
click node_auth_store "https://github.com/uttomkumar143/trafficvaulthub/blob/main/backend/src/modules/auth/repository.ts"
click node_tenant "https://github.com/uttomkumar143/trafficvaulthub/blob/main/backend/src/middleware/require-org.ts"
click node_orgs "https://github.com/uttomkumar143/trafficvaulthub/tree/main/backend/src/modules/organizations"
click node_offers "https://github.com/uttomkumar143/trafficvaulthub/blob/main/backend/src/modules/offers/service.ts"
click node_advertisers "https://github.com/uttomkumar143/trafficvaulthub/tree/main/backend/src/modules/advertisers"
click node_affiliates "https://github.com/uttomkumar143/trafficvaulthub/blob/main/backend/src/modules/affiliates/service.ts"
click node_tracking "https://github.com/uttomkumar143/trafficvaulthub/tree/main/backend/src/modules/tracking"
click node_attribution "https://github.com/uttomkumar143/trafficvaulthub/blob/main/backend/src/modules/tracking/attribution-service.ts"
click node_conversions "https://github.com/uttomkumar143/trafficvaulthub/blob/main/backend/src/modules/conversions/service.ts"
click node_fraud "https://github.com/uttomkumar143/trafficvaulthub/blob/main/backend/src/modules/fraud/risk-engine.ts"
click node_compliance "https://github.com/uttomkumar143/trafficvaulthub/blob/main/backend/src/modules/compliance/service.ts"
click node_support "https://github.com/uttomkumar143/trafficvaulthub/tree/main/backend/src/modules/support"
click node_ledger "https://github.com/uttomkumar143/trafficvaulthub/blob/main/backend/src/modules/ledger/journal.ts"
click node_billing "https://github.com/uttomkumar143/trafficvaulthub/blob/main/backend/src/modules/billing/service.ts"
click node_payouts "https://github.com/uttomkumar143/trafficvaulthub/blob/main/backend/src/modules/payouts/service.ts"
click node_reconciliation "https://github.com/uttomkumar143/trafficvaulthub/blob/main/backend/src/modules/reconciliation/service.ts"
click node_webhooks "https://github.com/uttomkumar143/trafficvaulthub/blob/main/backend/src/modules/webhooks/service.ts"
click node_webhook_transport "https://github.com/uttomkumar143/trafficvaulthub/blob/main/backend/src/modules/webhooks/transport.ts"
click node_integrations "https://github.com/uttomkumar143/trafficvaulthub/tree/main/backend/src/integrations"
click node_platform_lib "https://github.com/uttomkumar143/trafficvaulthub/tree/main/backend/src/lib"

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_spa,node_frontend_api,node_auth_ui,node_offer_ui,node_dash_ui,node_users toneBlue
class node_auth,node_auth_store,node_tenant,node_orgs,node_platform_lib toneAmber
class node_offers,node_advertisers,node_affiliates,node_tracking,node_attribution,node_worker toneMint
class node_conversions,node_fraud,node_compliance,node_support toneRose
class node_ledger,node_billing,node_payouts,node_reconciliation,node_webhooks,node_webhook_transport,node_integrations toneIndigo
```

## Components

### User experience

- [React application](https://github.com/uttomkumar143/trafficvaulthub/blob/main/frontend/src/app/app.tsx): `frontend/src/app/app.tsx`
- [API client](https://github.com/uttomkumar143/trafficvaulthub/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`
- [Authentication UI](https://github.com/uttomkumar143/trafficvaulthub/blob/main/frontend/src/features/auth/auth-context.tsx): `frontend/src/features/auth/auth-context.tsx`
- [Offer marketplace UI](https://github.com/uttomkumar143/trafficvaulthub/blob/main/frontend/src/features/offers/api.ts): `frontend/src/features/offers/api.ts`
- [Affiliate dashboard UI](https://github.com/uttomkumar143/trafficvaulthub/blob/main/frontend/src/features/affiliate-dashboard/api.ts): `frontend/src/features/affiliate-dashboard/api.ts`

### Identity and access

- [Authentication service](https://github.com/uttomkumar143/trafficvaulthub/blob/main/backend/src/modules/auth/service.ts): `backend/src/modules/auth/service.ts`
- [Identity persistence](https://github.com/uttomkumar143/trafficvaulthub/blob/main/backend/src/modules/auth/repository.ts): `backend/src/modules/auth/repository.ts`
- [Tenant and RBAC](https://github.com/uttomkumar143/trafficvaulthub/blob/main/backend/src/middleware/require-org.ts): `backend/src/middleware/require-org.ts`
- [Organizations](https://github.com/uttomkumar143/trafficvaulthub/tree/main/backend/src/modules/organizations): `backend/src/modules/organizations`
- [Worker bindings and tenant helpers](https://github.com/uttomkumar143/trafficvaulthub/tree/main/backend/src/lib): `backend/src/lib`

### Marketplace and tracking

- [Offer policy and lifecycle](https://github.com/uttomkumar143/trafficvaulthub/blob/main/backend/src/modules/offers/service.ts): `backend/src/modules/offers/service.ts`
- [Advertiser profiles](https://github.com/uttomkumar143/trafficvaulthub/tree/main/backend/src/modules/advertisers): `backend/src/modules/advertisers`
- [Affiliate profiles](https://github.com/uttomkumar143/trafficvaulthub/blob/main/backend/src/modules/affiliates/service.ts): `backend/src/modules/affiliates/service.ts`
- [Tracking and SmartLinks](https://github.com/uttomkumar143/trafficvaulthub/tree/main/backend/src/modules/tracking): `backend/src/modules/tracking`
- [Attribution](https://github.com/uttomkumar143/trafficvaulthub/blob/main/backend/src/modules/tracking/attribution-service.ts): `backend/src/modules/tracking/attribution-service.ts`

### Risk and operations

- [Conversion validation](https://github.com/uttomkumar143/trafficvaulthub/blob/main/backend/src/modules/conversions/service.ts): `backend/src/modules/conversions/service.ts`
- [Fraud risk engine](https://github.com/uttomkumar143/trafficvaulthub/blob/main/backend/src/modules/fraud/risk-engine.ts): `backend/src/modules/fraud/risk-engine.ts`
- [Compliance review](https://github.com/uttomkumar143/trafficvaulthub/blob/main/backend/src/modules/compliance/service.ts): `backend/src/modules/compliance/service.ts`
- [Support and disputes](https://github.com/uttomkumar143/trafficvaulthub/tree/main/backend/src/modules/support): `backend/src/modules/support`

### Finance and delivery

- [Immutable ledger](https://github.com/uttomkumar143/trafficvaulthub/blob/main/backend/src/modules/ledger/journal.ts): `backend/src/modules/ledger/journal.ts`
- [Advertiser billing](https://github.com/uttomkumar143/trafficvaulthub/blob/main/backend/src/modules/billing/service.ts): `backend/src/modules/billing/service.ts`
- [Affiliate payouts](https://github.com/uttomkumar143/trafficvaulthub/blob/main/backend/src/modules/payouts/service.ts): `backend/src/modules/payouts/service.ts`
- [Reconciliation](https://github.com/uttomkumar143/trafficvaulthub/blob/main/backend/src/modules/reconciliation/service.ts): `backend/src/modules/reconciliation/service.ts`
- [Webhooks](https://github.com/uttomkumar143/trafficvaulthub/blob/main/backend/src/modules/webhooks/service.ts): `backend/src/modules/webhooks/service.ts`
- [Webhook transport](https://github.com/uttomkumar143/trafficvaulthub/blob/main/backend/src/modules/webhooks/transport.ts): `backend/src/modules/webhooks/transport.ts`
- [External integrations](https://github.com/uttomkumar143/trafficvaulthub/tree/main/backend/src/integrations): `backend/src/integrations`

### Other components

- **Network users**
- [Hono API and wiring](https://github.com/uttomkumar143/trafficvaulthub/blob/main/backend/src/app.ts): `backend/src/app.ts`

## Connections

- Network users → React application: use (evidence: `README.md`)
- React application → API client: requests
- API client → Hono API and wiring: calls REST API
- Hono API and wiring → Authentication service: wires services (evidence: `backend/src/app.ts`)
- Hono API and wiring → Offer policy and lifecycle: wires services (evidence: `backend/src/app.ts`)
- Hono API and wiring → Tracking and SmartLinks: wires services (evidence: `backend/src/app.ts`)
- Hono API and wiring → Webhook transport: configures transport (evidence: `backend/src/app.ts`)
- Hono API and wiring → External integrations: configures adapters (evidence: `backend/src/app.ts`)
- Authentication UI → API client: uses
- Offer marketplace UI → API client: uses
- Affiliate dashboard UI → API client: uses
- Authentication service → Identity persistence: persists identity (evidence: `backend/src/modules/auth/service.ts`)
- Tenant and RBAC → Organizations: resolves membership (evidence: `backend/src/middleware/require-org.ts`)
- Offer policy and lifecycle → Advertiser profiles: checks advertiser (evidence: `backend/src/modules/offers/service.ts`)
- Offer policy and lifecycle → Tracking and SmartLinks: invalidates eligibility cache (evidence: `backend/src/modules/offers/service.ts`)
- Network users → Offer policy and lifecycle: manage offers (evidence: `README.md`)
- Network users → Affiliate profiles: apply as publisher (evidence: `README.md`)
- Tracking and SmartLinks → Attribution: records attribution (evidence: `README.md`)
- Tracking and SmartLinks → Conversion validation: tracks conversions (evidence: `README.md`)
- Conversion validation → Fraud risk engine: checks risk (evidence: `README.md`)
- Conversion validation → Compliance review: supports review (evidence: `README.md`)
- Conversion validation → Immutable ledger: accounts approved activity
- Immutable ledger → Advertiser billing: supports billing
- Immutable ledger → Affiliate payouts: funds payouts (evidence: `backend/src/modules/payouts/service.ts`)
- Immutable ledger → Reconciliation: reconciles balances
- Network users → Support and disputes: request assistance (evidence: `README.md`)
- Webhooks → Webhook transport: dispatches deliveries (evidence: `backend/src/modules/webhooks/service.ts`)
- Webhooks → External integrations: delivers event notifications
- Worker bindings and tenant helpers → Tenant and RBAC: provides bindings (evidence: `backend/src/lib/bindings.ts`)