# khayaai/forgepaye architecture

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

- Interactive diagram: https://gitdiagram.com/khayaai/forgepaye
- Repository: https://github.com/khayaai/forgepaye

## Overview

FORGE is a multi-rail financial platform layered over a Hyperswitch payment router. Its core flow accepts payment activity through the unified router, normalizes it into the canonical ForgePayEvent ledger, and connects payment rails; the platform console exposes treasury, custody, wallet, and bureau capabilities. The README documents several service-level connections, but most service implementations were not sampled, so those links are documented relationships rather than inspected call paths.

Main entry points: [`forgepay/apps/platform`](https://github.com/khayaai/forgepaye/tree/claude/forgepay-platform-design-gEkgE/forgepay/apps/platform) (Platform console), [`forgepay/services/unified-router`](https://github.com/khayaai/forgepaye/tree/claude/forgepay-platform-design-gEkgE/forgepay/services/unified-router) (Unified router), [`forgepay/services/agent-credit-bureau`](https://github.com/khayaai/forgepaye/tree/claude/forgepay-platform-design-gEkgE/forgepay/services/agent-credit-bureau) (Agent credit bureau), [`forgepay/packages/sdk-js/src/client.ts`](https://github.com/khayaai/forgepaye/blob/claude/forgepay-platform-design-gEkgE/forgepay/packages/sdk-js/src/client.ts) (Payment client SDKs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Platform experience"]
  node_platform["Platform console"]
  node_forge_api["Forge API routes<br/>[route.ts]"]
end

subgraph group_payments["Payments and ledger"]
  node_payment_client["Payment client SDKs<br/>[client.ts]"]
  node_unified_router["Unified router"]
  node_event_ledger[("ForgePayEvent ledger")]
  node_hyperswitch["Card and bank router<br/>[app.rs]"]
  node_stablecoin["Stablecoin gateway"]
  node_crypto["Crypto gateway"]
  node_accounts["Stablecoin accounts"]
end

subgraph group_treasury["Treasury and compliance"]
  node_treasury_rules["Treasury rules<br/>[rules-engine.ts]"]
  node_forecaster["Liquidity forecasts<br/>[engine.py]"]
  node_compliance["Compliance monitoring<br/>[engine.py]"]
end

subgraph group_agent_finance["Agent finance"]
  node_bureau["Agent credit bureau"]
  node_decision["Agent risk decisions"]
  node_negotiation["Agent negotiation"]
end

subgraph group_infrastructure["Custody and identity"]
  node_custody["Institutional custody"]
  node_wallet["DID wallets"]
end

node_merchant(("Merchant or agent"))

node_merchant -->|"initiates payment"| node_payment_client
node_payment_client -->|"submits payment"| node_unified_router
node_unified_router -->|"normalizes events"| node_event_ledger
node_unified_router -->|"routes card and bank"| node_hyperswitch
node_unified_router -->|"routes stablecoins"| node_stablecoin
node_unified_router -->|"routes crypto"| node_crypto
node_merchant -->|"uses console"| node_platform
node_platform -.->|"calls API"| node_forge_api
node_platform -->|"manages custody"| node_custody
node_platform -->|"manages wallets"| node_wallet
node_platform -->|"manages treasury"| node_treasury_rules
node_platform -->|"accesses bureau"| node_bureau
node_accounts -->|"supports stablecoin accounts"| node_stablecoin
node_event_ledger -.->|"screens activity"| node_compliance
node_compliance -->|"fetches payment history"| node_hyperswitch
node_event_ledger -.->|"informs cash forecasts"| node_forecaster
node_forecaster -.->|"informs treasury actions"| node_treasury_rules
node_bureau -.->|"uses risk decisions"| node_decision
node_bureau -.->|"supports agent credit"| node_negotiation

click node_platform "https://github.com/khayaai/forgepaye/tree/claude/forgepay-platform-design-gEkgE/forgepay/apps/platform"
click node_forge_api "https://github.com/khayaai/forgepaye/blob/claude/forgepay-platform-design-gEkgE/forgepay/apps/platform/app/api/forge/%5Bsection%5D/route.ts"
click node_payment_client "https://github.com/khayaai/forgepaye/blob/claude/forgepay-platform-design-gEkgE/forgepay/packages/sdk-js/src/client.ts"
click node_unified_router "https://github.com/khayaai/forgepaye/tree/claude/forgepay-platform-design-gEkgE/forgepay/services/unified-router"
click node_event_ledger "https://github.com/khayaai/forgepaye/tree/claude/forgepay-platform-design-gEkgE/forgepay/services/unified-router"
click node_hyperswitch "https://github.com/khayaai/forgepaye/blob/claude/forgepay-platform-design-gEkgE/crates/router/src/routes/app.rs"
click node_stablecoin "https://github.com/khayaai/forgepaye/tree/claude/forgepay-platform-design-gEkgE/forgepay/services/stablecoin-gateway"
click node_crypto "https://github.com/khayaai/forgepaye/tree/claude/forgepay-platform-design-gEkgE/forgepay/services/crypto-gateway"
click node_accounts "https://github.com/khayaai/forgepaye/tree/claude/forgepay-platform-design-gEkgE/forgepay/services/accounts-service"
click node_treasury_rules "https://github.com/khayaai/forgepaye/blob/claude/forgepay-platform-design-gEkgE/forgepay/services/enterprise-treasury/src/rules-engine.ts"
click node_forecaster "https://github.com/khayaai/forgepaye/blob/claude/forgepay-platform-design-gEkgE/forgepay/services/liquidity-forecaster/src/forecasting/engine.py"
click node_compliance "https://github.com/khayaai/forgepaye/blob/claude/forgepay-platform-design-gEkgE/forgepay/services/compliance-monitor/src/monitoring/engine.py"
click node_bureau "https://github.com/khayaai/forgepaye/tree/claude/forgepay-platform-design-gEkgE/forgepay/services/agent-credit-bureau"
click node_decision "https://github.com/khayaai/forgepaye/tree/claude/forgepay-platform-design-gEkgE/forgepay/services/agent-decision-framework"
click node_negotiation "https://github.com/khayaai/forgepaye/tree/claude/forgepay-platform-design-gEkgE/forgepay/services/agent-negotiation"
click node_custody "https://github.com/khayaai/forgepaye/tree/claude/forgepay-platform-design-gEkgE/forgepay/services/forge-custody"
click node_wallet "https://github.com/khayaai/forgepaye/tree/claude/forgepay-platform-design-gEkgE/forgepay/services/forge-wallet"

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_platform,node_forge_api toneBlue
class node_payment_client,node_unified_router,node_event_ledger,node_hyperswitch,node_stablecoin,node_crypto,node_accounts toneAmber
class node_treasury_rules,node_forecaster,node_compliance toneMint
class node_bureau,node_decision,node_negotiation toneRose
class node_custody,node_wallet,node_merchant toneIndigo
```

## Components

### Platform experience

- [Platform console](https://github.com/khayaai/forgepaye/tree/claude/forgepay-platform-design-gEkgE/forgepay/apps/platform): `forgepay/apps/platform`
- [Forge API routes](https://github.com/khayaai/forgepaye/blob/claude/forgepay-platform-design-gEkgE/forgepay/apps/platform/app/api/forge/%5Bsection%5D/route.ts): `forgepay/apps/platform/app/api/forge/[section]/route.ts`

### Payments and ledger

- [Payment client SDKs](https://github.com/khayaai/forgepaye/blob/claude/forgepay-platform-design-gEkgE/forgepay/packages/sdk-js/src/client.ts): `forgepay/packages/sdk-js/src/client.ts`
- [Unified router](https://github.com/khayaai/forgepaye/tree/claude/forgepay-platform-design-gEkgE/forgepay/services/unified-router): `forgepay/services/unified-router`
- [ForgePayEvent ledger](https://github.com/khayaai/forgepaye/tree/claude/forgepay-platform-design-gEkgE/forgepay/services/unified-router): `forgepay/services/unified-router`
- [Card and bank router](https://github.com/khayaai/forgepaye/blob/claude/forgepay-platform-design-gEkgE/crates/router/src/routes/app.rs): `crates/router/src/routes/app.rs`
- [Stablecoin gateway](https://github.com/khayaai/forgepaye/tree/claude/forgepay-platform-design-gEkgE/forgepay/services/stablecoin-gateway): `forgepay/services/stablecoin-gateway`
- [Crypto gateway](https://github.com/khayaai/forgepaye/tree/claude/forgepay-platform-design-gEkgE/forgepay/services/crypto-gateway): `forgepay/services/crypto-gateway`
- [Stablecoin accounts](https://github.com/khayaai/forgepaye/tree/claude/forgepay-platform-design-gEkgE/forgepay/services/accounts-service): `forgepay/services/accounts-service`

### Treasury and compliance

- [Treasury rules](https://github.com/khayaai/forgepaye/blob/claude/forgepay-platform-design-gEkgE/forgepay/services/enterprise-treasury/src/rules-engine.ts): `forgepay/services/enterprise-treasury/src/rules-engine.ts`
- [Liquidity forecasts](https://github.com/khayaai/forgepaye/blob/claude/forgepay-platform-design-gEkgE/forgepay/services/liquidity-forecaster/src/forecasting/engine.py): `forgepay/services/liquidity-forecaster/src/forecasting/engine.py`
- [Compliance monitoring](https://github.com/khayaai/forgepaye/blob/claude/forgepay-platform-design-gEkgE/forgepay/services/compliance-monitor/src/monitoring/engine.py): `forgepay/services/compliance-monitor/src/monitoring/engine.py`

### Agent finance

- [Agent credit bureau](https://github.com/khayaai/forgepaye/tree/claude/forgepay-platform-design-gEkgE/forgepay/services/agent-credit-bureau): `forgepay/services/agent-credit-bureau`
- [Agent risk decisions](https://github.com/khayaai/forgepaye/tree/claude/forgepay-platform-design-gEkgE/forgepay/services/agent-decision-framework): `forgepay/services/agent-decision-framework`
- [Agent negotiation](https://github.com/khayaai/forgepaye/tree/claude/forgepay-platform-design-gEkgE/forgepay/services/agent-negotiation): `forgepay/services/agent-negotiation`

### Custody and identity

- [Institutional custody](https://github.com/khayaai/forgepaye/tree/claude/forgepay-platform-design-gEkgE/forgepay/services/forge-custody): `forgepay/services/forge-custody`
- [DID wallets](https://github.com/khayaai/forgepaye/tree/claude/forgepay-platform-design-gEkgE/forgepay/services/forge-wallet): `forgepay/services/forge-wallet`

### Other components

- **Merchant or agent**

## Connections

- Merchant or agent → Payment client SDKs: initiates payment
- Payment client SDKs → Unified router: submits payment
- Unified router → ForgePayEvent ledger: normalizes events
- Unified router → Card and bank router: routes card and bank
- Unified router → Stablecoin gateway: routes stablecoins
- Unified router → Crypto gateway: routes crypto
- Merchant or agent → Platform console: uses console
- Platform console → Forge API routes: calls API
- Platform console → Institutional custody: manages custody
- Platform console → DID wallets: manages wallets
- Platform console → Treasury rules: manages treasury
- Platform console → Agent credit bureau: accesses bureau
- Stablecoin accounts → Stablecoin gateway: supports stablecoin accounts
- ForgePayEvent ledger → Compliance monitoring: screens activity
- Compliance monitoring → Card and bank router: fetches payment history (evidence: `forgepay/services/compliance-monitor/src/monitoring/engine.py`)
- ForgePayEvent ledger → Liquidity forecasts: informs cash forecasts
- Liquidity forecasts → Treasury rules: informs treasury actions
- Agent credit bureau → Agent risk decisions: uses risk decisions
- Agent credit bureau → Agent negotiation: supports agent credit
