# comethrusws/nexara-backend architecture

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

## Overview

Nexara is a NestJS payment-orchestration API for merchants and operations staff. The merchant workflow covers OTP-based access and onboarding, KYC, wallet funding and activity, beneficiary management, and payouts; payouts route through organization-configured bank adapters while Fineract is the live ledger. Operations configure organizations, features, banks, and fees, and manage merchant KYC and wallets. The README documents additional bill payments, reconciliation, dashboard, audit, notifications, and webhooks. Several service implementations were not sampled, so uncertain internal wiring is omitted.

Main entry points: [`src/modules/portal/portal.controller.ts`](https://github.com/comethrusws/nexara-backend/blob/main/src/modules/portal/portal.controller.ts) (Merchant portal API), [`src/modules/merchants/merchants.service.ts`](https://github.com/comethrusws/nexara-backend/blob/main/src/modules/merchants/merchants.service.ts) (Merchant management), [`src/modules/payouts/payouts.service.ts`](https://github.com/comethrusws/nexara-backend/blob/main/src/modules/payouts/payouts.service.ts) (Payout orchestration), [`src/modules/fee-engine/fee-engine.service.ts`](https://github.com/comethrusws/nexara-backend/blob/main/src/modules/fee-engine/fee-engine.service.ts) (Fees and commissions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Identity and onboarding"]
  node_auth["Authentication<br/>[auth.service.ts]"]
  node_onboarding["Onboarding portal"]
end

subgraph group_merchant["Merchant payments"]
  node_portal["Merchant portal API"]
  node_wallet["Wallet and activity<br/>[wallet.service.ts]"]
  node_payouts["Payout orchestration<br/>[payouts.service.ts]"]
  node_beneficiaries["Beneficiaries"]
  node_bbps["Bill payments<br/>[bbps.service.ts]"]
  node_webhooks["Merchant webhooks"]
end

subgraph group_operations["Operations and governance"]
  node_merchant_management["Merchant management"]
  node_organizations["Organization and bank config"]
  node_fee_engine["Fees and commissions"]
  node_reconciliation["Reconciliation"]
  node_dashboard["Operations dashboard"]
  node_audit["Audit log<br/>[audit.service.ts]"]
  node_notifications["Notifications"]
end

subgraph group_providers["Provider integrations"]
  node_fineract["Fineract ledger"]
  node_bank_routing["Bank adapter registry<br/>[bank.registry.ts]"]
  node_kyc_provider["KYC provider<br/>[kyc.module.ts]"]
  node_object_storage["Document storage<br/>[storage.module.ts]"]
end

subgraph group_platform["Platform state"]
  node_postgres[("PostgreSQL")]
end

node_merchant_actor(("Merchant"))
node_ops_actor(("Operations staff"))
node_bank_service["Payout bank"]

node_merchant_actor -->|"requests access"| node_auth
node_auth -->|"reads and writes"| node_postgres
node_merchant_actor -->|"submits onboarding"| node_onboarding
node_onboarding -->|"checks OTP"| node_auth
node_ops_actor -->|"manages merchants"| node_merchant_management
node_merchant_management -.->|"verifies identity"| node_kyc_provider
node_merchant_management -->|"stores documents"| node_object_storage
node_merchant_actor -->|"uses API"| node_portal
node_portal -->|"handles wallet requests"| node_wallet
node_portal -->|"handles payouts"| node_payouts
node_portal -->|"manages payees"| node_beneficiaries
node_portal -->|"requests bill payments"| node_bbps
node_portal -->|"manages webhooks"| node_webhooks
node_payouts -->|"selects bank adapter"| node_bank_routing
node_bank_routing -->|"dispatches payout"| node_bank_service
node_wallet -->|"posts ledger activity"| node_fineract
node_ops_actor -->|"configures hierarchy"| node_organizations
node_organizations -->|"stores routing and features"| node_postgres
node_ops_actor -->|"updates fee config"| node_fee_engine
node_fee_engine -->|"records changes"| node_audit
node_fee_engine -->|"reads and writes"| node_postgres
node_ops_actor -->|"runs reconciliation"| node_reconciliation
node_ops_actor -->|"views operations"| node_dashboard
node_ops_actor -->|"manages notifications"| node_notifications
node_merchant_management -->|"stores merchant records"| node_postgres
node_payouts -->|"stores payout state"| node_postgres
node_beneficiaries -->|"stores payees"| node_postgres
node_webhooks -->|"stores endpoints and deliveries"| node_postgres

click node_auth "https://github.com/comethrusws/nexara-backend/blob/main/src/modules/auth/auth.service.ts"
click node_onboarding "https://github.com/comethrusws/nexara-backend/blob/main/src/modules/portal/onboarding.controller.ts"
click node_merchant_management "https://github.com/comethrusws/nexara-backend/blob/main/src/modules/merchants/merchants.service.ts"
click node_portal "https://github.com/comethrusws/nexara-backend/blob/main/src/modules/portal/portal.controller.ts"
click node_wallet "https://github.com/comethrusws/nexara-backend/blob/main/src/modules/wallet/wallet.service.ts"
click node_payouts "https://github.com/comethrusws/nexara-backend/blob/main/src/modules/payouts/payouts.service.ts"
click node_beneficiaries "https://github.com/comethrusws/nexara-backend/blob/main/src/modules/beneficiaries/beneficiaries.service.ts"
click node_bbps "https://github.com/comethrusws/nexara-backend/blob/main/src/modules/bbps/bbps.service.ts"
click node_organizations "https://github.com/comethrusws/nexara-backend/blob/main/src/modules/organizations/organizations.service.ts"
click node_fee_engine "https://github.com/comethrusws/nexara-backend/blob/main/src/modules/fee-engine/fee-engine.service.ts"
click node_reconciliation "https://github.com/comethrusws/nexara-backend/blob/main/src/modules/reconciliation/reconciliation.service.ts"
click node_dashboard "https://github.com/comethrusws/nexara-backend/blob/main/src/modules/dashboard/dashboard.service.ts"
click node_audit "https://github.com/comethrusws/nexara-backend/blob/main/src/modules/audit/audit.service.ts"
click node_notifications "https://github.com/comethrusws/nexara-backend/blob/main/src/modules/notifications/notifications.service.ts"
click node_webhooks "https://github.com/comethrusws/nexara-backend/blob/main/src/modules/webhooks/webhooks.service.ts"
click node_fineract "https://github.com/comethrusws/nexara-backend/blob/main/src/integrations/fineract/fineract.adapter.ts"
click node_bank_routing "https://github.com/comethrusws/nexara-backend/blob/main/src/integrations/banks/bank.registry.ts"
click node_kyc_provider "https://github.com/comethrusws/nexara-backend/blob/main/src/integrations/kyc/kyc.module.ts"
click node_object_storage "https://github.com/comethrusws/nexara-backend/blob/main/src/integrations/storage/storage.module.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_auth,node_onboarding toneBlue
class node_portal,node_wallet,node_payouts,node_beneficiaries,node_bbps,node_webhooks toneAmber
class node_merchant_management,node_organizations,node_fee_engine,node_reconciliation,node_dashboard,node_audit,node_notifications toneMint
class node_fineract,node_bank_routing,node_kyc_provider,node_object_storage toneRose
class node_postgres,node_merchant_actor,node_ops_actor,node_bank_service toneIndigo
```

## Components

### Identity and onboarding

- [Authentication](https://github.com/comethrusws/nexara-backend/blob/main/src/modules/auth/auth.service.ts): `src/modules/auth/auth.service.ts`
- [Onboarding portal](https://github.com/comethrusws/nexara-backend/blob/main/src/modules/portal/onboarding.controller.ts): `src/modules/portal/onboarding.controller.ts`

### Merchant payments

- [Merchant portal API](https://github.com/comethrusws/nexara-backend/blob/main/src/modules/portal/portal.controller.ts): `src/modules/portal/portal.controller.ts`
- [Wallet and activity](https://github.com/comethrusws/nexara-backend/blob/main/src/modules/wallet/wallet.service.ts): `src/modules/wallet/wallet.service.ts`
- [Payout orchestration](https://github.com/comethrusws/nexara-backend/blob/main/src/modules/payouts/payouts.service.ts): `src/modules/payouts/payouts.service.ts`
- [Beneficiaries](https://github.com/comethrusws/nexara-backend/blob/main/src/modules/beneficiaries/beneficiaries.service.ts): `src/modules/beneficiaries/beneficiaries.service.ts`
- [Bill payments](https://github.com/comethrusws/nexara-backend/blob/main/src/modules/bbps/bbps.service.ts): `src/modules/bbps/bbps.service.ts`
- [Merchant webhooks](https://github.com/comethrusws/nexara-backend/blob/main/src/modules/webhooks/webhooks.service.ts): `src/modules/webhooks/webhooks.service.ts`

### Operations and governance

- [Merchant management](https://github.com/comethrusws/nexara-backend/blob/main/src/modules/merchants/merchants.service.ts): `src/modules/merchants/merchants.service.ts`
- [Organization and bank config](https://github.com/comethrusws/nexara-backend/blob/main/src/modules/organizations/organizations.service.ts): `src/modules/organizations/organizations.service.ts`
- [Fees and commissions](https://github.com/comethrusws/nexara-backend/blob/main/src/modules/fee-engine/fee-engine.service.ts): `src/modules/fee-engine/fee-engine.service.ts`
- [Reconciliation](https://github.com/comethrusws/nexara-backend/blob/main/src/modules/reconciliation/reconciliation.service.ts): `src/modules/reconciliation/reconciliation.service.ts`
- [Operations dashboard](https://github.com/comethrusws/nexara-backend/blob/main/src/modules/dashboard/dashboard.service.ts): `src/modules/dashboard/dashboard.service.ts`
- [Audit log](https://github.com/comethrusws/nexara-backend/blob/main/src/modules/audit/audit.service.ts): `src/modules/audit/audit.service.ts`
- [Notifications](https://github.com/comethrusws/nexara-backend/blob/main/src/modules/notifications/notifications.service.ts): `src/modules/notifications/notifications.service.ts`

### Provider integrations

- [Fineract ledger](https://github.com/comethrusws/nexara-backend/blob/main/src/integrations/fineract/fineract.adapter.ts): `src/integrations/fineract/fineract.adapter.ts`
- [Bank adapter registry](https://github.com/comethrusws/nexara-backend/blob/main/src/integrations/banks/bank.registry.ts): `src/integrations/banks/bank.registry.ts`
- [KYC provider](https://github.com/comethrusws/nexara-backend/blob/main/src/integrations/kyc/kyc.module.ts): `src/integrations/kyc/kyc.module.ts`
- [Document storage](https://github.com/comethrusws/nexara-backend/blob/main/src/integrations/storage/storage.module.ts): `src/integrations/storage/storage.module.ts`

### Platform state

- **PostgreSQL**

### Other components

- **Merchant**
- **Operations staff**
- **Payout bank**

## Connections

- Merchant → Authentication: requests access
- Authentication → PostgreSQL: reads and writes
- Merchant → Onboarding portal: submits onboarding
- Onboarding portal → Authentication: checks OTP
- Operations staff → Merchant management: manages merchants
- Merchant management → KYC provider: verifies identity
- Merchant management → Document storage: stores documents
- Merchant → Merchant portal API: uses API
- Merchant portal API → Wallet and activity: handles wallet requests
- Merchant portal API → Payout orchestration: handles payouts
- Merchant portal API → Beneficiaries: manages payees
- Merchant portal API → Bill payments: requests bill payments
- Merchant portal API → Merchant webhooks: manages webhooks
- Payout orchestration → Bank adapter registry: selects bank adapter
- Bank adapter registry → Payout bank: dispatches payout
- Wallet and activity → Fineract ledger: posts ledger activity
- Operations staff → Organization and bank config: configures hierarchy
- Organization and bank config → PostgreSQL: stores routing and features
- Operations staff → Fees and commissions: updates fee config
- Fees and commissions → Audit log: records changes
- Fees and commissions → PostgreSQL: reads and writes
- Operations staff → Reconciliation: runs reconciliation
- Operations staff → Operations dashboard: views operations
- Operations staff → Notifications: manages notifications
- Merchant management → PostgreSQL: stores merchant records
- Payout orchestration → PostgreSQL: stores payout state
- Beneficiaries → PostgreSQL: stores payees
- Merchant webhooks → PostgreSQL: stores endpoints and deliveries