# daniel-joseph-web/vera-pay architecture

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

- Interactive diagram: https://gitdiagram.com/daniel-joseph-web/vera-pay
- Repository: https://github.com/daniel-joseph-web/vera-pay

## Overview

Verapay is a remittance-protection platform for sending funds to Nigerian providers, with payment release gated by invoice, payee, and project-proof checks. The main user journey starts a payment, analyzes the submitted bill and beneficiary, presents a verification decision, then approves payout or requests a refund. Family shared pots, contractor evidence capture, and milestone projects are distinct product branches. Backend route and service calls are evidenced in sampled source; some frontend-to-API wiring and unsampled capability links are documented only at a high level, so those links are dashed.

Main entry points: [`backend/src/server.ts`](https://github.com/daniel-joseph-web/vera-pay/blob/main/backend/src/server.ts) (Express API), [`backend/src/controllers/verification.controller.ts`](https://github.com/daniel-joseph-web/vera-pay/blob/main/backend/src/controllers/verification.controller.ts) (Verification orchestration), [`frontend/src/app/(dashboard)/pay/[id]/verify/page.tsx`](https://github.com/daniel-joseph-web/vera-pay/blob/main/frontend/src/app/(dashboard)/pay/%5Bid%5D/verify/page.tsx) (Verification decision), [`backend/src/controllers/payment.controller.ts`](https://github.com/daniel-joseph-web/vera-pay/blob/main/backend/src/controllers/payment.controller.ts) (Payment orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_landing["Landing and plans<br/>[page.tsx]"]
  node_dashboard["Escrow dashboard<br/>[page.tsx]"]
  node_audit["Forensic audit grid<br/>[VerapayAGGrid.tsx]"]
  node_newpay["Start payment<br/>[page.tsx]"]
  node_paystore["Payment state<br/>[usePaymentStore.ts]"]
  node_verifyui["Verification decision<br/>[page.tsx]"]
  node_decision["Traffic-light result"]
  node_quoteui["Quote comparison"]
  node_family["Family shared pots<br/>[page.tsx]"]
  node_projectlist["Project tracking<br/>[page.tsx]"]
  node_projectdetail["Milestone progress<br/>[page.tsx]"]
  node_stepper["Milestone stepper"]
  node_contractor["Contractor evidence upload<br/>[page.tsx]"]
  node_camera["Evidence camera<br/>[InAppCamera.tsx]"]
end

subgraph group_verification["Verification"]
  node_verifyroutes["Verification routes"]
  node_verifyctl["Verification orchestration"]
  node_ocr["Invoice OCR"]
  node_quoteagent["Quote agent"]
  node_forensics["Image forensics<br/>[dhash.service.ts]"]
  node_payeecheck["Payee verification"]
end

subgraph group_payments["Payments"]
  node_api["Express API<br/>[server.ts]"]
  node_paymentroutes["Payment routes<br/>[payment.routes.ts]"]
  node_paymentctl["Payment orchestration"]
  node_paypal["PayPal escrow"]
  node_payout["Naira payout"]
end

subgraph group_operations["Integrations"]
  node_webhooks["Payment webhooks<br/>[webhook.routes.ts]"]
  node_zapier["Event automation<br/>[zapier.service.ts]"]
  node_elastic["Photo hash search<br/>[elastic.service.ts]"]
  node_paypalservice["PayPal service"]
  node_paystackservice["Paystack service"]
  node_gemini["Gemini AI"]
end

node_sender(("Sender"))
node_contractoractor(("Contractor"))

node_sender -->|"visits"| node_landing
node_sender -->|"starts payment"| node_newpay
node_sender -->|"reviews activity"| node_dashboard
node_newpay -.->|"updates state"| node_paystore
node_newpay -.->|"submits payment"| node_api
node_paystore -.->|"supplies state"| node_verifyui
node_verifyui -->|"renders"| node_decision
node_verifyui -->|"presents comparison"| node_quoteui
node_verifyui -.->|"requests checks"| node_api
node_dashboard -->|"renders audit"| node_audit
node_sender -->|"manages support"| node_family
node_sender -->|"tracks projects"| node_projectlist
node_projectlist -->|"opens milestone"| node_projectdetail
node_projectdetail -->|"renders progress"| node_stepper
node_contractoractor -->|"uploads proof"| node_contractor
node_contractor -->|"captures evidence"| node_camera
node_contractor -.->|"submits evidence"| node_api
node_api -->|"mounts routes"| node_paymentroutes
node_api -->|"mounts routes"| node_verifyroutes
node_api -->|"mounts routes"| node_webhooks
node_paymentroutes -->|"dispatches"| node_paymentctl
node_verifyroutes -->|"dispatches"| node_verifyctl
node_paymentctl -->|"creates orders and refunds"| node_paypal
node_paymentctl -->|"dispatches payout"| node_payout
node_paymentctl -->|"dispatches events"| node_zapier
node_verifyctl -->|"parses invoice"| node_ocr
node_verifyctl -->|"hashes invoice image"| node_forensics
node_verifyctl -->|"checks material quote"| node_quoteagent
node_verifyctl -->|"resolves beneficiary"| node_payeecheck
node_webhooks -->|"dispatches test event"| node_zapier
node_paypal -->|"calls API"| node_paypalservice
node_payout -->|"calls API"| node_paystackservice
node_ocr -->|"analyzes image"| node_gemini
node_forensics -.->|"indexes hashes"| node_elastic

click node_landing "https://github.com/daniel-joseph-web/vera-pay/blob/main/frontend/src/app/page.tsx"
click node_dashboard "https://github.com/daniel-joseph-web/vera-pay/blob/main/frontend/src/app/(dashboard)/dashboard/page.tsx"
click node_audit "https://github.com/daniel-joseph-web/vera-pay/blob/main/frontend/src/components/dashboard/VerapayAGGrid.tsx"
click node_newpay "https://github.com/daniel-joseph-web/vera-pay/blob/main/frontend/src/app/(dashboard)/pay/new/page.tsx"
click node_paystore "https://github.com/daniel-joseph-web/vera-pay/blob/main/frontend/src/stores/usePaymentStore.ts"
click node_verifyui "https://github.com/daniel-joseph-web/vera-pay/blob/main/frontend/src/app/(dashboard)/pay/%5Bid%5D/verify/page.tsx"
click node_decision "https://github.com/daniel-joseph-web/vera-pay/blob/main/frontend/src/components/verification/TrafficLightDecisionCard.tsx"
click node_quoteui "https://github.com/daniel-joseph-web/vera-pay/blob/main/frontend/src/components/verification/QuoteComparisonModal.tsx"
click node_family "https://github.com/daniel-joseph-web/vera-pay/blob/main/frontend/src/app/(dashboard)/family/page.tsx"
click node_projectlist "https://github.com/daniel-joseph-web/vera-pay/blob/main/frontend/src/app/(dashboard)/projects/page.tsx"
click node_projectdetail "https://github.com/daniel-joseph-web/vera-pay/blob/main/frontend/src/app/(dashboard)/projects/%5Bid%5D/page.tsx"
click node_stepper "https://github.com/daniel-joseph-web/vera-pay/blob/main/frontend/src/components/projects/MilestoneProgressStepper.tsx"
click node_contractor "https://github.com/daniel-joseph-web/vera-pay/blob/main/frontend/src/app/(mobile-contractor)/contractor/upload/%5Btoken%5D/page.tsx"
click node_camera "https://github.com/daniel-joseph-web/vera-pay/blob/main/frontend/src/components/camera/InAppCamera.tsx"
click node_api "https://github.com/daniel-joseph-web/vera-pay/blob/main/backend/src/server.ts"
click node_paymentroutes "https://github.com/daniel-joseph-web/vera-pay/blob/main/backend/src/routes/payment.routes.ts"
click node_paymentctl "https://github.com/daniel-joseph-web/vera-pay/blob/main/backend/src/controllers/payment.controller.ts"
click node_verifyroutes "https://github.com/daniel-joseph-web/vera-pay/blob/main/backend/src/routes/verification.routes.ts"
click node_verifyctl "https://github.com/daniel-joseph-web/vera-pay/blob/main/backend/src/controllers/verification.controller.ts"
click node_ocr "https://github.com/daniel-joseph-web/vera-pay/blob/main/backend/src/services/ai/gemini-ocr.service.ts"
click node_quoteagent "https://github.com/daniel-joseph-web/vera-pay/blob/main/backend/src/services/ai/quote-agent.service.ts"
click node_forensics "https://github.com/daniel-joseph-web/vera-pay/blob/main/backend/src/services/forensics/dhash.service.ts"
click node_payeecheck "https://github.com/daniel-joseph-web/vera-pay/blob/main/backend/src/services/payee/cac-nuban.service.ts"
click node_paypal "https://github.com/daniel-joseph-web/vera-pay/blob/main/backend/src/services/escrow/paypal-escrow.service.ts"
click node_payout "https://github.com/daniel-joseph-web/vera-pay/blob/main/backend/src/services/escrow/paystack-payout.service.ts"
click node_webhooks "https://github.com/daniel-joseph-web/vera-pay/blob/main/backend/src/routes/webhook.routes.ts"
click node_zapier "https://github.com/daniel-joseph-web/vera-pay/blob/main/backend/src/services/integrations/zapier.service.ts"
click node_elastic "https://github.com/daniel-joseph-web/vera-pay/blob/main/backend/src/services/integrations/elastic.service.ts"

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_landing,node_dashboard,node_audit,node_newpay,node_paystore,node_verifyui,node_decision,node_quoteui,node_family,node_projectlist,node_projectdetail,node_stepper,node_contractor,node_camera toneBlue
class node_verifyroutes,node_verifyctl,node_ocr,node_quoteagent,node_forensics,node_payeecheck toneAmber
class node_api,node_paymentroutes,node_paymentctl,node_paypal,node_payout toneMint
class node_webhooks,node_zapier,node_elastic,node_paypalservice,node_paystackservice,node_gemini toneRose
class node_sender,node_contractoractor toneIndigo
```

## Components

### User experience

- [Landing and plans](https://github.com/daniel-joseph-web/vera-pay/blob/main/frontend/src/app/page.tsx): `frontend/src/app/page.tsx`
- [Escrow dashboard](https://github.com/daniel-joseph-web/vera-pay/blob/main/frontend/src/app/(dashboard)/dashboard/page.tsx): `frontend/src/app/(dashboard)/dashboard/page.tsx`
- [Forensic audit grid](https://github.com/daniel-joseph-web/vera-pay/blob/main/frontend/src/components/dashboard/VerapayAGGrid.tsx): `frontend/src/components/dashboard/VerapayAGGrid.tsx`
- [Start payment](https://github.com/daniel-joseph-web/vera-pay/blob/main/frontend/src/app/(dashboard)/pay/new/page.tsx): `frontend/src/app/(dashboard)/pay/new/page.tsx`
- [Payment state](https://github.com/daniel-joseph-web/vera-pay/blob/main/frontend/src/stores/usePaymentStore.ts): `frontend/src/stores/usePaymentStore.ts`
- [Verification decision](https://github.com/daniel-joseph-web/vera-pay/blob/main/frontend/src/app/(dashboard)/pay/%5Bid%5D/verify/page.tsx): `frontend/src/app/(dashboard)/pay/[id]/verify/page.tsx`
- [Traffic-light result](https://github.com/daniel-joseph-web/vera-pay/blob/main/frontend/src/components/verification/TrafficLightDecisionCard.tsx): `frontend/src/components/verification/TrafficLightDecisionCard.tsx`
- [Quote comparison](https://github.com/daniel-joseph-web/vera-pay/blob/main/frontend/src/components/verification/QuoteComparisonModal.tsx): `frontend/src/components/verification/QuoteComparisonModal.tsx`
- [Family shared pots](https://github.com/daniel-joseph-web/vera-pay/blob/main/frontend/src/app/(dashboard)/family/page.tsx): `frontend/src/app/(dashboard)/family/page.tsx`
- [Project tracking](https://github.com/daniel-joseph-web/vera-pay/blob/main/frontend/src/app/(dashboard)/projects/page.tsx): `frontend/src/app/(dashboard)/projects/page.tsx`
- [Milestone progress](https://github.com/daniel-joseph-web/vera-pay/blob/main/frontend/src/app/(dashboard)/projects/%5Bid%5D/page.tsx): `frontend/src/app/(dashboard)/projects/[id]/page.tsx`
- [Milestone stepper](https://github.com/daniel-joseph-web/vera-pay/blob/main/frontend/src/components/projects/MilestoneProgressStepper.tsx): `frontend/src/components/projects/MilestoneProgressStepper.tsx`
- [Contractor evidence upload](https://github.com/daniel-joseph-web/vera-pay/blob/main/frontend/src/app/(mobile-contractor)/contractor/upload/%5Btoken%5D/page.tsx): `frontend/src/app/(mobile-contractor)/contractor/upload/[token]/page.tsx`
- [Evidence camera](https://github.com/daniel-joseph-web/vera-pay/blob/main/frontend/src/components/camera/InAppCamera.tsx): `frontend/src/components/camera/InAppCamera.tsx`

### Verification

- [Verification routes](https://github.com/daniel-joseph-web/vera-pay/blob/main/backend/src/routes/verification.routes.ts): `backend/src/routes/verification.routes.ts`
- [Verification orchestration](https://github.com/daniel-joseph-web/vera-pay/blob/main/backend/src/controllers/verification.controller.ts): `backend/src/controllers/verification.controller.ts`
- [Invoice OCR](https://github.com/daniel-joseph-web/vera-pay/blob/main/backend/src/services/ai/gemini-ocr.service.ts): `backend/src/services/ai/gemini-ocr.service.ts`
- [Quote agent](https://github.com/daniel-joseph-web/vera-pay/blob/main/backend/src/services/ai/quote-agent.service.ts): `backend/src/services/ai/quote-agent.service.ts`
- [Image forensics](https://github.com/daniel-joseph-web/vera-pay/blob/main/backend/src/services/forensics/dhash.service.ts): `backend/src/services/forensics/dhash.service.ts`
- [Payee verification](https://github.com/daniel-joseph-web/vera-pay/blob/main/backend/src/services/payee/cac-nuban.service.ts): `backend/src/services/payee/cac-nuban.service.ts`

### Payments

- [Express API](https://github.com/daniel-joseph-web/vera-pay/blob/main/backend/src/server.ts): `backend/src/server.ts`
- [Payment routes](https://github.com/daniel-joseph-web/vera-pay/blob/main/backend/src/routes/payment.routes.ts): `backend/src/routes/payment.routes.ts`
- [Payment orchestration](https://github.com/daniel-joseph-web/vera-pay/blob/main/backend/src/controllers/payment.controller.ts): `backend/src/controllers/payment.controller.ts`
- [PayPal escrow](https://github.com/daniel-joseph-web/vera-pay/blob/main/backend/src/services/escrow/paypal-escrow.service.ts): `backend/src/services/escrow/paypal-escrow.service.ts`
- [Naira payout](https://github.com/daniel-joseph-web/vera-pay/blob/main/backend/src/services/escrow/paystack-payout.service.ts): `backend/src/services/escrow/paystack-payout.service.ts`

### Integrations

- [Payment webhooks](https://github.com/daniel-joseph-web/vera-pay/blob/main/backend/src/routes/webhook.routes.ts): `backend/src/routes/webhook.routes.ts`
- [Event automation](https://github.com/daniel-joseph-web/vera-pay/blob/main/backend/src/services/integrations/zapier.service.ts): `backend/src/services/integrations/zapier.service.ts`
- [Photo hash search](https://github.com/daniel-joseph-web/vera-pay/blob/main/backend/src/services/integrations/elastic.service.ts): `backend/src/services/integrations/elastic.service.ts`
- **PayPal service**
- **Paystack service**
- **Gemini AI**

### Other components

- **Sender**
- **Contractor**

## Connections

- Sender → Landing and plans: visits
- Sender → Start payment: starts payment
- Sender → Escrow dashboard: reviews activity
- Start payment → Payment state: updates state
- Start payment → Express API: submits payment
- Payment state → Verification decision: supplies state
- Verification decision → Traffic-light result: renders
- Verification decision → Quote comparison: presents comparison
- Verification decision → Express API: requests checks
- Escrow dashboard → Forensic audit grid: renders audit
- Sender → Family shared pots: manages support
- Sender → Project tracking: tracks projects
- Project tracking → Milestone progress: opens milestone
- Milestone progress → Milestone stepper: renders progress
- Contractor → Contractor evidence upload: uploads proof
- Contractor evidence upload → Evidence camera: captures evidence
- Contractor evidence upload → Express API: submits evidence
- Express API → Payment routes: mounts routes (evidence: `backend/src/server.ts`)
- Express API → Verification routes: mounts routes (evidence: `backend/src/server.ts`)
- Express API → Payment webhooks: mounts routes (evidence: `backend/src/server.ts`)
- Payment routes → Payment orchestration: dispatches (evidence: `backend/src/routes/payment.routes.ts`)
- Verification routes → Verification orchestration: dispatches (evidence: `backend/src/routes/verification.routes.ts`)
- Payment orchestration → PayPal escrow: creates orders and refunds (evidence: `backend/src/controllers/payment.controller.ts`)
- Payment orchestration → Naira payout: dispatches payout (evidence: `backend/src/controllers/payment.controller.ts`)
- Payment orchestration → Event automation: dispatches events (evidence: `backend/src/controllers/payment.controller.ts`)
- Verification orchestration → Invoice OCR: parses invoice (evidence: `backend/src/controllers/verification.controller.ts`)
- Verification orchestration → Image forensics: hashes invoice image (evidence: `backend/src/controllers/verification.controller.ts`)
- Verification orchestration → Quote agent: checks material quote (evidence: `backend/src/controllers/verification.controller.ts`)
- Verification orchestration → Payee verification: resolves beneficiary (evidence: `backend/src/controllers/verification.controller.ts`)
- Payment webhooks → Event automation: dispatches test event (evidence: `backend/src/routes/webhook.routes.ts`)
- PayPal escrow → PayPal service: calls API
- Naira payout → Paystack service: calls API
- Invoice OCR → Gemini AI: analyzes image (evidence: `backend/src/services/ai/gemini-ocr.service.ts`)
- Image forensics → Photo hash search: indexes hashes