# viraj012/ledgersync architecture

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

- Interactive diagram: https://gitdiagram.com/viraj012/ledgersync
- Repository: https://github.com/viraj012/ledgersync

## Overview

LedgerSync accepts Stripe payment and refund webhooks, records each event and its order changes idempotently, and creates durable ERP-sync jobs. A background worker claims jobs, calls the ERP over HTTP, and retries failures; reconciliation compares local orders with ERP records and reports mismatches. The API also exposes order/job status, reconciliation reports, statistics, and mock-ERP fault controls. Relationships below follow the excerpts and README; some documented controllers and services were not sampled in full.

Main entry points: [`src/main/java/com/ledgersync/reconciliation/ReconciliationService.java`](https://github.com/viraj012/ledgersync/blob/main/src/main/java/com/ledgersync/reconciliation/ReconciliationService.java) (Reconciliation run), [`src/main/java/com/ledgersync/sync/SyncJobRepository.java`](https://github.com/viraj012/ledgersync/blob/main/src/main/java/com/ledgersync/sync/SyncJobRepository.java) (Sync jobs), [`src/main/java/com/ledgersync/sync/SyncWorker.java`](https://github.com/viraj012/ledgersync/blob/main/src/main/java/com/ledgersync/sync/SyncWorker.java) (Sync worker), [`src/main/java/com/ledgersync/order/OrderRepository.java`](https://github.com/viraj012/ledgersync/blob/main/src/main/java/com/ledgersync/order/OrderRepository.java) (Orders)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Webhook ingestion"]
  node_webhook_controller["Webhook endpoint"]
  node_event_mapper["Event mapper"]
  node_webhook_service["Webhook processing"]
end

subgraph group_sync["ERP synchronization"]
  node_scheduler["Sync scheduler<br/>[SyncScheduler.java]"]
  node_worker["Sync worker<br/>[SyncWorker.java]"]
  node_backoff["Retry backoff<br/>[Backoff.java]"]
  node_erp_client["ERP HTTP client<br/>[ErpClient.java]"]
  node_mock_erp["Mock ERP API"]
  node_erp_faults["ERP fault controls<br/>[MockErpFaults.java]"]
end

subgraph group_recon["Reconciliation"]
  node_recon_schedule["Reconciliation schedule"]
  node_recon_controller["Reconciliation API"]
  node_recon_service["Reconciliation run"]
  node_recon_rules["Mismatch rules"]
  node_recon_repo["Run reports"]
end

subgraph group_data["Ledger data"]
  node_event_repo["Stripe event store"]
  node_orders["Orders"]
  node_jobs["Sync jobs"]
  node_database[("PostgreSQL<br/>[V1__init.sql]")]
  node_erp_records["ERP records"]
end

subgraph group_api["Query and controls"]
  node_order_api["Order lookup API"]
  node_job_api["Job management API"]
  node_stats_api["Statistics API"]
end

node_stripe(("Stripe"))
node_operator(("API caller"))

node_stripe -->|"sends webhook"| node_webhook_controller
node_webhook_controller -->|"maps event"| node_event_mapper
node_webhook_controller -->|"handles action"| node_webhook_service
node_webhook_service -->|"deduplicates event"| node_event_repo
node_webhook_service -->|"updates order"| node_orders
node_webhook_service -->|"queues sync"| node_jobs
node_event_repo -.->|"writes events"| node_database
node_orders -->|"reads and writes"| node_database
node_jobs -->|"claims and updates"| node_database
node_scheduler -->|"schedules work"| node_worker
node_worker -->|"claims and records outcomes"| node_jobs
node_worker -->|"loads order"| node_orders
node_worker -->|"sends sync"| node_erp_client
node_worker -->|"calculates retry delay"| node_backoff
node_erp_client -->|"calls over HTTP"| node_mock_erp
node_mock_erp -->|"stores ERP records"| node_erp_records
node_mock_erp -->|"applies fault settings"| node_erp_faults
node_erp_records -->|"reads and writes"| node_database
node_recon_schedule -->|"starts scheduled run"| node_recon_service
node_recon_controller -->|"runs or reports"| node_recon_service
node_recon_service -->|"loads orders"| node_orders
node_recon_service -->|"loads ERP records"| node_erp_records
node_recon_service -->|"checks open jobs"| node_jobs
node_recon_service -->|"compares records"| node_recon_rules
node_recon_service -->|"saves run and issues"| node_recon_repo
node_operator -->|"queries orders"| node_order_api
node_operator -->|"manages retries"| node_job_api
node_operator -->|"requests report"| node_recon_controller
node_operator -->|"checks counts"| node_stats_api
node_operator -->|"configures faults"| node_mock_erp
node_order_api -->|"reads order"| node_orders
node_order_api -->|"loads order jobs"| node_jobs
node_job_api -->|"lists and retries"| node_jobs

click node_webhook_controller "https://github.com/viraj012/ledgersync/blob/main/src/main/java/com/ledgersync/webhook/StripeWebhookController.java"
click node_event_mapper "https://github.com/viraj012/ledgersync/blob/main/src/main/java/com/ledgersync/webhook/StripeEventMapper.java"
click node_webhook_service "https://github.com/viraj012/ledgersync/blob/main/src/main/java/com/ledgersync/webhook/WebhookService.java"
click node_event_repo "https://github.com/viraj012/ledgersync/blob/main/src/main/java/com/ledgersync/webhook/StripeEventRepository.java"
click node_orders "https://github.com/viraj012/ledgersync/blob/main/src/main/java/com/ledgersync/order/OrderRepository.java"
click node_jobs "https://github.com/viraj012/ledgersync/blob/main/src/main/java/com/ledgersync/sync/SyncJobRepository.java"
click node_database "https://github.com/viraj012/ledgersync/blob/main/src/main/resources/db/migration/V1__init.sql"
click node_scheduler "https://github.com/viraj012/ledgersync/blob/main/src/main/java/com/ledgersync/sync/SyncScheduler.java"
click node_worker "https://github.com/viraj012/ledgersync/blob/main/src/main/java/com/ledgersync/sync/SyncWorker.java"
click node_backoff "https://github.com/viraj012/ledgersync/blob/main/src/main/java/com/ledgersync/sync/Backoff.java"
click node_erp_client "https://github.com/viraj012/ledgersync/blob/main/src/main/java/com/ledgersync/sync/ErpClient.java"
click node_mock_erp "https://github.com/viraj012/ledgersync/blob/main/src/main/java/com/ledgersync/erp/MockErpController.java"
click node_erp_faults "https://github.com/viraj012/ledgersync/blob/main/src/main/java/com/ledgersync/erp/MockErpFaults.java"
click node_erp_records "https://github.com/viraj012/ledgersync/blob/main/src/main/java/com/ledgersync/erp/ErpRecordRepository.java"
click node_recon_schedule "https://github.com/viraj012/ledgersync/blob/main/src/main/java/com/ledgersync/reconciliation/ReconciliationScheduler.java"
click node_recon_controller "https://github.com/viraj012/ledgersync/blob/main/src/main/java/com/ledgersync/reconciliation/ReconciliationController.java"
click node_recon_service "https://github.com/viraj012/ledgersync/blob/main/src/main/java/com/ledgersync/reconciliation/ReconciliationService.java"
click node_recon_rules "https://github.com/viraj012/ledgersync/blob/main/src/main/java/com/ledgersync/reconciliation/ReconciliationRules.java"
click node_recon_repo "https://github.com/viraj012/ledgersync/blob/main/src/main/java/com/ledgersync/reconciliation/ReconciliationRepository.java"
click node_order_api "https://github.com/viraj012/ledgersync/blob/main/src/main/java/com/ledgersync/order/OrderController.java"
click node_job_api "https://github.com/viraj012/ledgersync/blob/main/src/main/java/com/ledgersync/sync/SyncJobController.java"
click node_stats_api "https://github.com/viraj012/ledgersync/blob/main/src/main/java/com/ledgersync/stats/StatsController.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_webhook_controller,node_event_mapper,node_webhook_service toneBlue
class node_scheduler,node_worker,node_backoff,node_erp_client,node_mock_erp,node_erp_faults toneAmber
class node_recon_schedule,node_recon_controller,node_recon_service,node_recon_rules,node_recon_repo,node_operator toneMint
class node_event_repo,node_orders,node_jobs,node_database,node_erp_records toneRose
class node_order_api,node_job_api,node_stats_api,node_stripe toneIndigo
```

## Components

### Webhook ingestion

- [Webhook endpoint](https://github.com/viraj012/ledgersync/blob/main/src/main/java/com/ledgersync/webhook/StripeWebhookController.java): `src/main/java/com/ledgersync/webhook/StripeWebhookController.java`
- [Event mapper](https://github.com/viraj012/ledgersync/blob/main/src/main/java/com/ledgersync/webhook/StripeEventMapper.java): `src/main/java/com/ledgersync/webhook/StripeEventMapper.java`
- [Webhook processing](https://github.com/viraj012/ledgersync/blob/main/src/main/java/com/ledgersync/webhook/WebhookService.java): `src/main/java/com/ledgersync/webhook/WebhookService.java`

### ERP synchronization

- [Sync scheduler](https://github.com/viraj012/ledgersync/blob/main/src/main/java/com/ledgersync/sync/SyncScheduler.java): `src/main/java/com/ledgersync/sync/SyncScheduler.java`
- [Sync worker](https://github.com/viraj012/ledgersync/blob/main/src/main/java/com/ledgersync/sync/SyncWorker.java): `src/main/java/com/ledgersync/sync/SyncWorker.java`
- [Retry backoff](https://github.com/viraj012/ledgersync/blob/main/src/main/java/com/ledgersync/sync/Backoff.java): `src/main/java/com/ledgersync/sync/Backoff.java`
- [ERP HTTP client](https://github.com/viraj012/ledgersync/blob/main/src/main/java/com/ledgersync/sync/ErpClient.java): `src/main/java/com/ledgersync/sync/ErpClient.java`
- [Mock ERP API](https://github.com/viraj012/ledgersync/blob/main/src/main/java/com/ledgersync/erp/MockErpController.java): `src/main/java/com/ledgersync/erp/MockErpController.java`
- [ERP fault controls](https://github.com/viraj012/ledgersync/blob/main/src/main/java/com/ledgersync/erp/MockErpFaults.java): `src/main/java/com/ledgersync/erp/MockErpFaults.java`

### Reconciliation

- [Reconciliation schedule](https://github.com/viraj012/ledgersync/blob/main/src/main/java/com/ledgersync/reconciliation/ReconciliationScheduler.java): `src/main/java/com/ledgersync/reconciliation/ReconciliationScheduler.java`
- [Reconciliation API](https://github.com/viraj012/ledgersync/blob/main/src/main/java/com/ledgersync/reconciliation/ReconciliationController.java): `src/main/java/com/ledgersync/reconciliation/ReconciliationController.java`
- [Reconciliation run](https://github.com/viraj012/ledgersync/blob/main/src/main/java/com/ledgersync/reconciliation/ReconciliationService.java): `src/main/java/com/ledgersync/reconciliation/ReconciliationService.java`
- [Mismatch rules](https://github.com/viraj012/ledgersync/blob/main/src/main/java/com/ledgersync/reconciliation/ReconciliationRules.java): `src/main/java/com/ledgersync/reconciliation/ReconciliationRules.java`
- [Run reports](https://github.com/viraj012/ledgersync/blob/main/src/main/java/com/ledgersync/reconciliation/ReconciliationRepository.java): `src/main/java/com/ledgersync/reconciliation/ReconciliationRepository.java`

### Ledger data

- [Stripe event store](https://github.com/viraj012/ledgersync/blob/main/src/main/java/com/ledgersync/webhook/StripeEventRepository.java): `src/main/java/com/ledgersync/webhook/StripeEventRepository.java`
- [Orders](https://github.com/viraj012/ledgersync/blob/main/src/main/java/com/ledgersync/order/OrderRepository.java): `src/main/java/com/ledgersync/order/OrderRepository.java`
- [Sync jobs](https://github.com/viraj012/ledgersync/blob/main/src/main/java/com/ledgersync/sync/SyncJobRepository.java): `src/main/java/com/ledgersync/sync/SyncJobRepository.java`
- [PostgreSQL](https://github.com/viraj012/ledgersync/blob/main/src/main/resources/db/migration/V1__init.sql): `src/main/resources/db/migration/V1__init.sql`
- [ERP records](https://github.com/viraj012/ledgersync/blob/main/src/main/java/com/ledgersync/erp/ErpRecordRepository.java): `src/main/java/com/ledgersync/erp/ErpRecordRepository.java`

### Query and controls

- [Order lookup API](https://github.com/viraj012/ledgersync/blob/main/src/main/java/com/ledgersync/order/OrderController.java): `src/main/java/com/ledgersync/order/OrderController.java`
- [Job management API](https://github.com/viraj012/ledgersync/blob/main/src/main/java/com/ledgersync/sync/SyncJobController.java): `src/main/java/com/ledgersync/sync/SyncJobController.java`
- [Statistics API](https://github.com/viraj012/ledgersync/blob/main/src/main/java/com/ledgersync/stats/StatsController.java): `src/main/java/com/ledgersync/stats/StatsController.java`

### Other components

- **Stripe**
- **API caller**

## Connections

- Stripe → Webhook endpoint: sends webhook (evidence: `README.md`)
- Webhook endpoint → Event mapper: maps event (evidence: `src/main/java/com/ledgersync/webhook/StripeWebhookController.java`)
- Webhook endpoint → Webhook processing: handles action (evidence: `src/main/java/com/ledgersync/webhook/StripeWebhookController.java`)
- Webhook processing → Stripe event store: deduplicates event (evidence: `src/main/java/com/ledgersync/webhook/WebhookService.java`)
- Webhook processing → Orders: updates order (evidence: `src/main/java/com/ledgersync/webhook/WebhookService.java`)
- Webhook processing → Sync jobs: queues sync (evidence: `src/main/java/com/ledgersync/webhook/WebhookService.java`)
- Stripe event store → PostgreSQL: writes events
- Orders → PostgreSQL: reads and writes (evidence: `src/main/java/com/ledgersync/order/OrderRepository.java`)
- Sync jobs → PostgreSQL: claims and updates (evidence: `src/main/java/com/ledgersync/sync/SyncJobRepository.java`)
- Sync scheduler → Sync worker: schedules work (evidence: `src/main/java/com/ledgersync/sync/SyncScheduler.java`)
- Sync worker → Sync jobs: claims and records outcomes (evidence: `src/main/java/com/ledgersync/sync/SyncWorker.java`)
- Sync worker → Orders: loads order (evidence: `src/main/java/com/ledgersync/sync/SyncWorker.java`)
- Sync worker → ERP HTTP client: sends sync (evidence: `src/main/java/com/ledgersync/sync/SyncWorker.java`)
- Sync worker → Retry backoff: calculates retry delay (evidence: `src/main/java/com/ledgersync/sync/SyncWorker.java`)
- ERP HTTP client → Mock ERP API: calls over HTTP (evidence: `README.md`)
- Mock ERP API → ERP records: stores ERP records (evidence: `src/main/java/com/ledgersync/erp/MockErpController.java`)
- Mock ERP API → ERP fault controls: applies fault settings (evidence: `src/main/java/com/ledgersync/erp/MockErpController.java`)
- ERP records → PostgreSQL: reads and writes (evidence: `src/main/java/com/ledgersync/erp/ErpRecordRepository.java`)
- Reconciliation schedule → Reconciliation run: starts scheduled run (evidence: `src/main/java/com/ledgersync/reconciliation/ReconciliationScheduler.java`)
- Reconciliation API → Reconciliation run: runs or reports (evidence: `src/main/java/com/ledgersync/reconciliation/ReconciliationController.java`)
- Reconciliation run → Orders: loads orders (evidence: `src/main/java/com/ledgersync/reconciliation/ReconciliationService.java`)
- Reconciliation run → ERP records: loads ERP records (evidence: `src/main/java/com/ledgersync/reconciliation/ReconciliationService.java`)
- Reconciliation run → Sync jobs: checks open jobs (evidence: `src/main/java/com/ledgersync/reconciliation/ReconciliationService.java`)
- Reconciliation run → Mismatch rules: compares records (evidence: `src/main/java/com/ledgersync/reconciliation/ReconciliationService.java`)
- Reconciliation run → Run reports: saves run and issues (evidence: `src/main/java/com/ledgersync/reconciliation/ReconciliationService.java`)
- API caller → Order lookup API: queries orders (evidence: `README.md`)
- API caller → Job management API: manages retries (evidence: `README.md`)
- API caller → Reconciliation API: requests report (evidence: `README.md`)
- API caller → Statistics API: checks counts (evidence: `README.md`)
- API caller → Mock ERP API: configures faults (evidence: `README.md`)
- Order lookup API → Orders: reads order (evidence: `src/main/java/com/ledgersync/order/OrderController.java`)
- Order lookup API → Sync jobs: loads order jobs (evidence: `src/main/java/com/ledgersync/order/OrderController.java`)
- Job management API → Sync jobs: lists and retries (evidence: `src/main/java/com/ledgersync/sync/SyncJobController.java`)
