# vulpfin/foxpay architecture

> Architecture diagram of the GitHub repository vulpfin/foxpay, 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/vulpfin/foxpay
- Repository: https://github.com/vulpfin/foxpay

## Overview

FoxPay is a merchant-scoped payment orchestration service: merchants create payment intents through one API, and FoxPay presents eligible provider checkout routes while providers handle payment entry and money movement. Signed provider events and reconciliation—not browser redirects—establish payment state. Separate seller and consumer experiences support onboarding, account dashboards, and provider connections; background jobs handle reconciliation, token health, and outgoing webhooks. The graph uses README statements and indexed references for relationships; unsampled implementation details are not inferred.

Main entry points: [`apps/payments/services.py`](https://github.com/vulpfin/foxpay/blob/master/apps/payments/services.py) (Payment services), [`apps/payments/merchant_views.py`](https://github.com/vulpfin/foxpay/blob/master/apps/payments/merchant_views.py) (Seller portal), [`apps/payments/tasks.py`](https://github.com/vulpfin/foxpay/blob/master/apps/payments/tasks.py) (Background tasks), [`apps/payments/webhook_delivery.py`](https://github.com/vulpfin/foxpay/blob/master/apps/payments/webhook_delivery.py) (Merchant webhooks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Accounts and API"]
  node_account["Consumer dashboard<br/>[views.py]"]
  node_identity["TG11 identity<br/>[identity.py]"]
  node_seller["Seller portal<br/>[merchant_views.py]"]
  node_api["Payment API<br/>[views.py]"]
end

subgraph group_payments["Payment orchestration"]
  node_service["Payment services<br/>[services.py]"]
  node_routing["Provider routing<br/>[routing.py]"]
  node_abuse["Abuse controls<br/>[abuse.py]"]
  node_adapters["Adapter dispatch<br/>[card.py]"]
  node_crypto["Crypto adapter dispatch<br/>[crypto.py]"]
  node_ledger["Payment ledger<br/>[ledger.py]"]
  node_state[("Payment state<br/>[models.py]")]
end

subgraph group_providers["Provider connections"]
  node_stripe["Stripe Connect<br/>[stripe_connect.py]"]
  node_square["Square OAuth<br/>[square_oauth.py]"]
  node_paypal["PayPal partner<br/>[paypal_partner.py]"]
  node_nowpayments["NOWPayments credentials"]
end

subgraph group_operations["Events and operations"]
  node_events["Provider events<br/>[events.py]"]
  node_reconcile["Reconciliation"]
  node_tasks["Background tasks<br/>[tasks.py]"]
  node_delivery["Merchant webhooks"]
end

node_merchant(("Merchant client"))
node_provider(("Payment providers"))

node_merchant -->|"creates intents"| node_api
node_api -.->|"delegates to"| node_service
node_service -->|"selects routes"| node_routing
node_service -->|"checks limits"| node_abuse
node_service -->|"dispatches card"| node_adapters
node_service -->|"dispatches crypto"| node_crypto
node_service -->|"updates ledger"| node_ledger
node_service -->|"reads and writes"| node_state
node_adapters -.->|"calls provider"| node_provider
node_crypto -.->|"calls provider"| node_provider
node_seller -.->|"manages connection"| node_stripe
node_seller -.->|"manages connection"| node_square
node_seller -.->|"manages connection"| node_paypal
node_seller -.->|"manages credentials"| node_nowpayments
node_stripe -.->|"authorizes payments"| node_provider
node_square -.->|"authorizes payments"| node_provider
node_paypal -.->|"authorizes payments"| node_provider
node_nowpayments -.->|"authorizes payments"| node_provider
node_provider -.->|"sends signed events"| node_events
node_events -->|"queues processing"| node_tasks
node_tasks -->|"runs reconciliation"| node_reconcile
node_tasks -->|"runs delivery"| node_delivery
node_delivery -->|"loads event state"| node_state
node_delivery -->|"posts signed webhook"| node_merchant
node_account -->|"uses linked identity"| node_identity

click node_account "https://github.com/vulpfin/foxpay/blob/master/apps/accounts/views.py"
click node_identity "https://github.com/vulpfin/foxpay/blob/master/apps/accounts/identity.py"
click node_seller "https://github.com/vulpfin/foxpay/blob/master/apps/payments/merchant_views.py"
click node_api "https://github.com/vulpfin/foxpay/blob/master/apps/payments/views.py"
click node_service "https://github.com/vulpfin/foxpay/blob/master/apps/payments/services.py"
click node_routing "https://github.com/vulpfin/foxpay/blob/master/apps/payments/routing.py"
click node_abuse "https://github.com/vulpfin/foxpay/blob/master/apps/payments/abuse.py"
click node_adapters "https://github.com/vulpfin/foxpay/blob/master/apps/payments/adapters/card.py"
click node_crypto "https://github.com/vulpfin/foxpay/blob/master/apps/payments/adapters/crypto.py"
click node_ledger "https://github.com/vulpfin/foxpay/blob/master/apps/payments/ledger.py"
click node_state "https://github.com/vulpfin/foxpay/blob/master/apps/payments/models.py"
click node_stripe "https://github.com/vulpfin/foxpay/blob/master/apps/payments/stripe_connect.py"
click node_square "https://github.com/vulpfin/foxpay/blob/master/apps/payments/square_oauth.py"
click node_paypal "https://github.com/vulpfin/foxpay/blob/master/apps/payments/paypal_partner.py"
click node_nowpayments "https://github.com/vulpfin/foxpay/blob/master/apps/payments/nowpayments_connection.py"
click node_events "https://github.com/vulpfin/foxpay/blob/master/apps/payments/events.py"
click node_reconcile "https://github.com/vulpfin/foxpay/blob/master/apps/payments/payment_reconciliation.py"
click node_tasks "https://github.com/vulpfin/foxpay/blob/master/apps/payments/tasks.py"
click node_delivery "https://github.com/vulpfin/foxpay/blob/master/apps/payments/webhook_delivery.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_account,node_identity,node_seller,node_api,node_merchant toneBlue
class node_service,node_routing,node_abuse,node_adapters,node_crypto,node_ledger,node_state toneAmber
class node_stripe,node_square,node_paypal,node_nowpayments toneMint
class node_events,node_reconcile,node_tasks,node_delivery toneRose
class node_provider toneIndigo
```

## Components

### Accounts and API

- [Consumer dashboard](https://github.com/vulpfin/foxpay/blob/master/apps/accounts/views.py): `apps/accounts/views.py`
- [TG11 identity](https://github.com/vulpfin/foxpay/blob/master/apps/accounts/identity.py): `apps/accounts/identity.py`
- [Seller portal](https://github.com/vulpfin/foxpay/blob/master/apps/payments/merchant_views.py): `apps/payments/merchant_views.py`
- [Payment API](https://github.com/vulpfin/foxpay/blob/master/apps/payments/views.py): `apps/payments/views.py`

### Payment orchestration

- [Payment services](https://github.com/vulpfin/foxpay/blob/master/apps/payments/services.py): `apps/payments/services.py`
- [Provider routing](https://github.com/vulpfin/foxpay/blob/master/apps/payments/routing.py): `apps/payments/routing.py`
- [Abuse controls](https://github.com/vulpfin/foxpay/blob/master/apps/payments/abuse.py): `apps/payments/abuse.py`
- [Adapter dispatch](https://github.com/vulpfin/foxpay/blob/master/apps/payments/adapters/card.py): `apps/payments/adapters/card.py`
- [Crypto adapter dispatch](https://github.com/vulpfin/foxpay/blob/master/apps/payments/adapters/crypto.py): `apps/payments/adapters/crypto.py`
- [Payment ledger](https://github.com/vulpfin/foxpay/blob/master/apps/payments/ledger.py): `apps/payments/ledger.py`
- [Payment state](https://github.com/vulpfin/foxpay/blob/master/apps/payments/models.py): `apps/payments/models.py`

### Provider connections

- [Stripe Connect](https://github.com/vulpfin/foxpay/blob/master/apps/payments/stripe_connect.py): `apps/payments/stripe_connect.py`
- [Square OAuth](https://github.com/vulpfin/foxpay/blob/master/apps/payments/square_oauth.py): `apps/payments/square_oauth.py`
- [PayPal partner](https://github.com/vulpfin/foxpay/blob/master/apps/payments/paypal_partner.py): `apps/payments/paypal_partner.py`
- [NOWPayments credentials](https://github.com/vulpfin/foxpay/blob/master/apps/payments/nowpayments_connection.py): `apps/payments/nowpayments_connection.py`

### Events and operations

- [Provider events](https://github.com/vulpfin/foxpay/blob/master/apps/payments/events.py): `apps/payments/events.py`
- [Reconciliation](https://github.com/vulpfin/foxpay/blob/master/apps/payments/payment_reconciliation.py): `apps/payments/payment_reconciliation.py`
- [Background tasks](https://github.com/vulpfin/foxpay/blob/master/apps/payments/tasks.py): `apps/payments/tasks.py`
- [Merchant webhooks](https://github.com/vulpfin/foxpay/blob/master/apps/payments/webhook_delivery.py): `apps/payments/webhook_delivery.py`

### Other components

- **Merchant client**
- **Payment providers**

## Connections

- Merchant client → Payment API: creates intents
- Payment API → Payment services: delegates to
- Payment services → Provider routing: selects routes (evidence: `apps/payments/services.py`)
- Payment services → Abuse controls: checks limits (evidence: `apps/payments/services.py`)
- Payment services → Adapter dispatch: dispatches card (evidence: `apps/payments/services.py`)
- Payment services → Crypto adapter dispatch: dispatches crypto (evidence: `apps/payments/services.py`)
- Payment services → Payment ledger: updates ledger (evidence: `apps/payments/services.py`)
- Payment services → Payment state: reads and writes (evidence: `apps/payments/services.py`)
- Adapter dispatch → Payment providers: calls provider
- Crypto adapter dispatch → Payment providers: calls provider
- Seller portal → Stripe Connect: manages connection
- Seller portal → Square OAuth: manages connection
- Seller portal → PayPal partner: manages connection
- Seller portal → NOWPayments credentials: manages credentials
- Stripe Connect → Payment providers: authorizes payments
- Square OAuth → Payment providers: authorizes payments
- PayPal partner → Payment providers: authorizes payments
- NOWPayments credentials → Payment providers: authorizes payments
- Payment providers → Provider events: sends signed events
- Provider events → Background tasks: queues processing (evidence: `apps/payments/events.py`)
- Background tasks → Reconciliation: runs reconciliation (evidence: `apps/payments/tasks.py`)
- Background tasks → Merchant webhooks: runs delivery (evidence: `apps/payments/tasks.py`)
- Merchant webhooks → Payment state: loads event state (evidence: `apps/payments/webhook_delivery.py`)
- Merchant webhooks → Merchant client: posts signed webhook (evidence: `apps/payments/webhook_delivery.py`)
- Consumer dashboard → TG11 identity: uses linked identity (evidence: `apps/accounts/views.py`)