# ishwetraj17/payments-and-ledger-engine architecture

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

- Interactive diagram: https://gitdiagram.com/ishwetraj17/payments-and-ledger-engine
- Repository: https://github.com/ishwetraj17/payments-and-ledger-engine

## Overview

This is a modular fintech billing and payments engine. Its documented financial workflow runs from customer subscription through invoice generation and payment orchestration to double-entry ledger posting, revenue recognition, and reconciliation. Supporting branches include retries, event delivery and replay, risk review, and operational integrity checks. The graph uses README-documented lifecycle links and excerpted source calls; unsampled subsystems are represented at existing directory paths, and their internal wiring is not inferred.

Main entry points: [`src/main/java/com/firstclub/payments/gateway/PaymentGatewayCallService.java`](https://github.com/ishwetraj17/payments-and-ledger-engine/blob/main/src/main/java/com/firstclub/payments/gateway/PaymentGatewayCallService.java) (Payment orchestration), [`src/main/java/com/firstclub/billing/service/InvoiceService.java`](https://github.com/ishwetraj17/payments-and-ledger-engine/blob/main/src/main/java/com/firstclub/billing/service/InvoiceService.java) (Invoice billing), [`src/main/java/com/firstclub/ledger/service/LedgerService.java`](https://github.com/ishwetraj17/payments-and-ledger-engine/blob/main/src/main/java/com/firstclub/ledger/service/LedgerService.java) (Double-entry ledger), [`src/main/java/com/firstclub/subscription/service/SubscriptionV2Service.java`](https://github.com/ishwetraj17/payments-and-ledger-engine/blob/main/src/main/java/com/firstclub/subscription/service/SubscriptionV2Service.java) (Subscription lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_commerce["Subscription and billing"]
  node_customer["Customer"]
  node_catalog["Catalog pricing"]
  node_subscription["Subscription lifecycle"]
  node_billing["Invoice billing"]
  node_tax["Tax calculation"]
end

subgraph group_money["Payments and accounting"]
  node_payments["Payment orchestration"]
  node_dunning["Dunning retries"]
  node_ledger["Double-entry ledger<br/>[LedgerService.java]"]
  node_revenue["Revenue recognition"]
  node_reconciliation["Gateway reconciliation"]
end

subgraph group_async["Events and reliability"]
  node_outbox["Transactional outbox<br/>[OutboxService.java]"]
  node_events["Event log and replay"]
  node_webhooks["Webhook delivery"]
end

subgraph group_oversight["Risk and controls"]
  node_risk["Risk scoring"]
  node_review["Manual review"]
  node_integrity["Integrity checks"]
  node_audit["Financial audit"]
end

subgraph group_operations["Operations and insight"]
  node_admin["Admin search<br/>[SearchService.java]"]
  node_repair["Operations repair"]
end

node_operator(("Merchant or operator"))

node_operator -->|"enrolls"| node_customer
node_customer -->|"subscribes"| node_subscription
node_catalog -->|"provides plan"| node_subscription
node_subscription -->|"generates invoice"| node_billing
node_billing -.->|"calculates tax"| node_tax
node_billing -->|"initiates payment"| node_payments
node_payments -->|"posts entries"| node_ledger
node_ledger -->|"recognizes revenue"| node_revenue
node_payments -->|"reconciles gateway"| node_reconciliation
node_billing -->|"publishes event"| node_outbox
node_outbox -.->|"delivers events"| node_events
node_payments -.->|"retries failures"| node_dunning
node_payments -.->|"receives callbacks"| node_webhooks
node_risk -->|"opens cases"| node_review
node_operator -->|"reviews cases"| node_review
node_operator -.->|"searches records"| node_admin
node_operator -.->|"requests repair"| node_repair
node_ledger -.->|"checks invariants"| node_integrity
node_reconciliation -.->|"checks consistency"| node_integrity
node_payments -.->|"records operations"| node_audit

click node_customer "https://github.com/ishwetraj17/payments-and-ledger-engine/tree/main/src/main/java/com/firstclub/customer"
click node_catalog "https://github.com/ishwetraj17/payments-and-ledger-engine/tree/main/src/main/java/com/firstclub/catalog"
click node_subscription "https://github.com/ishwetraj17/payments-and-ledger-engine/blob/main/src/main/java/com/firstclub/subscription/service/SubscriptionV2Service.java"
click node_billing "https://github.com/ishwetraj17/payments-and-ledger-engine/blob/main/src/main/java/com/firstclub/billing/service/InvoiceService.java"
click node_tax "https://github.com/ishwetraj17/payments-and-ledger-engine/blob/main/src/main/java/com/firstclub/billing/tax/service/TaxCalculationService.java"
click node_payments "https://github.com/ishwetraj17/payments-and-ledger-engine/blob/main/src/main/java/com/firstclub/payments/gateway/PaymentGatewayCallService.java"
click node_dunning "https://github.com/ishwetraj17/payments-and-ledger-engine/blob/main/src/main/java/com/firstclub/dunning/service/DunningService.java"
click node_ledger "https://github.com/ishwetraj17/payments-and-ledger-engine/blob/main/src/main/java/com/firstclub/ledger/service/LedgerService.java"
click node_revenue "https://github.com/ishwetraj17/payments-and-ledger-engine/tree/main/src/main/java/com/firstclub/ledger/revenue"
click node_reconciliation "https://github.com/ishwetraj17/payments-and-ledger-engine/blob/main/src/main/java/com/firstclub/recon/service/ReconciliationService.java"
click node_outbox "https://github.com/ishwetraj17/payments-and-ledger-engine/blob/main/src/main/java/com/firstclub/outbox/service/OutboxService.java"
click node_events "https://github.com/ishwetraj17/payments-and-ledger-engine/blob/main/src/main/java/com/firstclub/events/replay/EventReplayService.java"
click node_webhooks "https://github.com/ishwetraj17/payments-and-ledger-engine/blob/main/src/main/java/com/firstclub/payments/webhooks/WebhookDedupService.java"
click node_risk "https://github.com/ishwetraj17/payments-and-ledger-engine/tree/main/src/main/java/com/firstclub/risk"
click node_review "https://github.com/ishwetraj17/payments-and-ledger-engine/blob/main/src/main/java/com/firstclub/risk/service/ManualReviewService.java"
click node_integrity "https://github.com/ishwetraj17/payments-and-ledger-engine/blob/main/src/main/java/com/firstclub/integrity/IntegrityCheckService.java"
click node_audit "https://github.com/ishwetraj17/payments-and-ledger-engine/blob/main/src/main/java/com/firstclub/audit/service/AuditEntryService.java"
click node_admin "https://github.com/ishwetraj17/payments-and-ledger-engine/blob/main/src/main/java/com/firstclub/admin/search/SearchService.java"
click node_repair "https://github.com/ishwetraj17/payments-and-ledger-engine/blob/main/src/main/java/com/firstclub/ops/repair/ManualRepairService.java"

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_customer,node_catalog,node_subscription,node_billing,node_tax toneBlue
class node_payments,node_dunning,node_ledger,node_revenue,node_reconciliation toneAmber
class node_outbox,node_events,node_webhooks toneMint
class node_risk,node_review,node_integrity,node_audit toneRose
class node_admin,node_repair,node_operator toneIndigo
```

## Components

### Subscription and billing

- [Customer](https://github.com/ishwetraj17/payments-and-ledger-engine/tree/main/src/main/java/com/firstclub/customer): `src/main/java/com/firstclub/customer`
- [Catalog pricing](https://github.com/ishwetraj17/payments-and-ledger-engine/tree/main/src/main/java/com/firstclub/catalog): `src/main/java/com/firstclub/catalog`
- [Subscription lifecycle](https://github.com/ishwetraj17/payments-and-ledger-engine/blob/main/src/main/java/com/firstclub/subscription/service/SubscriptionV2Service.java): `src/main/java/com/firstclub/subscription/service/SubscriptionV2Service.java`
- [Invoice billing](https://github.com/ishwetraj17/payments-and-ledger-engine/blob/main/src/main/java/com/firstclub/billing/service/InvoiceService.java): `src/main/java/com/firstclub/billing/service/InvoiceService.java`
- [Tax calculation](https://github.com/ishwetraj17/payments-and-ledger-engine/blob/main/src/main/java/com/firstclub/billing/tax/service/TaxCalculationService.java): `src/main/java/com/firstclub/billing/tax/service/TaxCalculationService.java`

### Payments and accounting

- [Payment orchestration](https://github.com/ishwetraj17/payments-and-ledger-engine/blob/main/src/main/java/com/firstclub/payments/gateway/PaymentGatewayCallService.java): `src/main/java/com/firstclub/payments/gateway/PaymentGatewayCallService.java`
- [Dunning retries](https://github.com/ishwetraj17/payments-and-ledger-engine/blob/main/src/main/java/com/firstclub/dunning/service/DunningService.java): `src/main/java/com/firstclub/dunning/service/DunningService.java`
- [Double-entry ledger](https://github.com/ishwetraj17/payments-and-ledger-engine/blob/main/src/main/java/com/firstclub/ledger/service/LedgerService.java): `src/main/java/com/firstclub/ledger/service/LedgerService.java`
- [Revenue recognition](https://github.com/ishwetraj17/payments-and-ledger-engine/tree/main/src/main/java/com/firstclub/ledger/revenue): `src/main/java/com/firstclub/ledger/revenue`
- [Gateway reconciliation](https://github.com/ishwetraj17/payments-and-ledger-engine/blob/main/src/main/java/com/firstclub/recon/service/ReconciliationService.java): `src/main/java/com/firstclub/recon/service/ReconciliationService.java`

### Events and reliability

- [Transactional outbox](https://github.com/ishwetraj17/payments-and-ledger-engine/blob/main/src/main/java/com/firstclub/outbox/service/OutboxService.java): `src/main/java/com/firstclub/outbox/service/OutboxService.java`
- [Event log and replay](https://github.com/ishwetraj17/payments-and-ledger-engine/blob/main/src/main/java/com/firstclub/events/replay/EventReplayService.java): `src/main/java/com/firstclub/events/replay/EventReplayService.java`
- [Webhook delivery](https://github.com/ishwetraj17/payments-and-ledger-engine/blob/main/src/main/java/com/firstclub/payments/webhooks/WebhookDedupService.java): `src/main/java/com/firstclub/payments/webhooks/WebhookDedupService.java`

### Risk and controls

- [Risk scoring](https://github.com/ishwetraj17/payments-and-ledger-engine/tree/main/src/main/java/com/firstclub/risk): `src/main/java/com/firstclub/risk`
- [Manual review](https://github.com/ishwetraj17/payments-and-ledger-engine/blob/main/src/main/java/com/firstclub/risk/service/ManualReviewService.java): `src/main/java/com/firstclub/risk/service/ManualReviewService.java`
- [Integrity checks](https://github.com/ishwetraj17/payments-and-ledger-engine/blob/main/src/main/java/com/firstclub/integrity/IntegrityCheckService.java): `src/main/java/com/firstclub/integrity/IntegrityCheckService.java`
- [Financial audit](https://github.com/ishwetraj17/payments-and-ledger-engine/blob/main/src/main/java/com/firstclub/audit/service/AuditEntryService.java): `src/main/java/com/firstclub/audit/service/AuditEntryService.java`

### Operations and insight

- [Admin search](https://github.com/ishwetraj17/payments-and-ledger-engine/blob/main/src/main/java/com/firstclub/admin/search/SearchService.java): `src/main/java/com/firstclub/admin/search/SearchService.java`
- [Operations repair](https://github.com/ishwetraj17/payments-and-ledger-engine/blob/main/src/main/java/com/firstclub/ops/repair/ManualRepairService.java): `src/main/java/com/firstclub/ops/repair/ManualRepairService.java`

### Other components

- **Merchant or operator**

## Connections

- Merchant or operator → Customer: enrolls (evidence: `README.md`)
- Customer → Subscription lifecycle: subscribes (evidence: `README.md`)
- Catalog pricing → Subscription lifecycle: provides plan (evidence: `README.md`)
- Subscription lifecycle → Invoice billing: generates invoice (evidence: `README.md`)
- Invoice billing → Tax calculation: calculates tax (evidence: `README.md`)
- Invoice billing → Payment orchestration: initiates payment (evidence: `README.md`)
- Payment orchestration → Double-entry ledger: posts entries (evidence: `README.md`)
- Double-entry ledger → Revenue recognition: recognizes revenue (evidence: `README.md`)
- Payment orchestration → Gateway reconciliation: reconciles gateway (evidence: `README.md`)
- Invoice billing → Transactional outbox: publishes event (evidence: `src/main/java/com/firstclub/billing/service/InvoiceService.java`)
- Transactional outbox → Event log and replay: delivers events (evidence: `README.md`)
- Payment orchestration → Dunning retries: retries failures (evidence: `README.md`)
- Payment orchestration → Webhook delivery: receives callbacks (evidence: `README.md`)
- Risk scoring → Manual review: opens cases (evidence: `src/main/java/com/firstclub/risk/service/ManualReviewService.java`)
- Merchant or operator → Manual review: reviews cases
- Merchant or operator → Admin search: searches records (evidence: `README.md`)
- Merchant or operator → Operations repair: requests repair (evidence: `README.md`)
- Double-entry ledger → Integrity checks: checks invariants (evidence: `README.md`)
- Gateway reconciliation → Integrity checks: checks consistency (evidence: `README.md`)
- Payment orchestration → Financial audit: records operations (evidence: `README.md`)
