# saimandsxroy/autonomous-distributed-banking-compliance architecture

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

- Interactive diagram: https://gitdiagram.com/saimandsxroy/autonomous-distributed-banking-compliance
- Repository: https://github.com/saimandsxroy/autonomous-distributed-banking-compliance

## Overview

RuneStone is a corporate treasury and AML platform. A client or B2B merchant initiates treasury activity; the documented core path applies distributed idempotency and velocity controls, posts a balanced ledger entry, then relays events for AML analysis, holds, investigation and human review. The product also exposes batch settlement, FX, reconciliation, corporate wires, and SAR export. The README supports the main backend flow; excerpts and the SOURCE INDEX provide additional component evidence, but many controller and integration details were not sampled.

Main entry points: [`server/src/main/java/com/runestone/treasury/service/JournalEntryService.java`](https://github.com/saimandsxroy/autonomous-distributed-banking-compliance/blob/main/server/src/main/java/com/runestone/treasury/service/JournalEntryService.java) (Double-entry ledger), [`server/src/main/java/com/runestone/treasury/service/GeminiAmlDetectiveService.java`](https://github.com/saimandsxroy/autonomous-distributed-banking-compliance/blob/main/server/src/main/java/com/runestone/treasury/service/GeminiAmlDetectiveService.java) (AI investigation), [`client/src/App.jsx`](https://github.com/saimandsxroy/autonomous-distributed-banking-compliance/blob/main/client/src/App.jsx) (React client), [`server/src/main/java/com/runestone/treasury/service/BalanceHoldService.java`](https://github.com/saimandsxroy/autonomous-distributed-banking-compliance/blob/main/server/src/main/java/com/runestone/treasury/service/BalanceHoldService.java) (Balance holds)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Treasury client"]
  node_clientapp["React client<br/>[App.jsx]"]
  node_treasuryapi["Client API<br/>[treasuryApi.js]"]
end

subgraph group_ledger["Ledger and payments"]
  node_gateway["Security gateway"]
  node_idempotency["Idempotency and velocity"]
  node_journal["Double-entry ledger"]
  node_journalentity["Journal entries<br/>[JournalEntry.java]"]
  node_posting["Posting legs<br/>[PostingLeg.java]"]
  node_account["Treasury accounts"]
  node_accountrepo["Account repository"]
  node_mysql[("MySQL ledger store")]
  node_outbox["Outbox relay"]
  node_kafka["Kafka events"]
end

subgraph group_risk["Sentinel AML"]
  node_consumer["Treasury event consumer"]
  node_graphdetect["Graph detection"]
  node_hold["Balance holds"]
  node_holdentity["Hold records<br/>[BalanceHold.java]"]
  node_rag["Policy RAG"]
  node_investigation["AI investigation"]
  node_gemini{{"Gemini AI"}}
  node_hitl["Officer approval"]
  node_sar["SAR PDF export"]
end

subgraph group_operations["Treasury operations"]
  node_batch["Batch settlement"]
  node_fx["FX treasury"]
  node_reconciliation["EOD reconciliation"]
  node_audit["Compliance audit"]
end

node_merchant(("B2B merchant"))
node_compliance(("Compliance officer"))

node_merchant -->|"initiates activity"| node_clientapp
node_clientapp -.->|"requests API"| node_treasuryapi
node_clientapp -.->|"sends requests"| node_gateway
node_gateway -->|"checks requests"| node_idempotency
node_idempotency -->|"permits posting"| node_journal
node_journal -->|"commits ledger"| node_mysql
node_journal -->|"persists entries"| node_journalentity
node_journal -->|"creates legs"| node_posting
node_journal -->|"locks accounts"| node_accountrepo
node_accountrepo -->|"loads accounts"| node_account
node_journal -->|"writes outbox"| node_outbox
node_outbox -->|"relays events"| node_kafka
node_kafka -->|"dispatches events"| node_consumer
node_consumer -->|"checks transactions"| node_graphdetect
node_graphdetect -->|"flags cycles"| node_hold
node_hold -.->|"records quarantine"| node_holdentity
node_hold -->|"triggers review"| node_investigation
node_investigation -->|"retrieves policies"| node_rag
node_investigation -->|"requests analysis"| node_gemini
node_investigation -->|"opens approval"| node_hitl
node_compliance -->|"reviews case"| node_hitl
node_compliance -->|"requests filing"| node_sar
node_batch -->|"posts transfers"| node_journal
node_journal -->|"calculates FX quote"| node_fx
node_reconciliation -->|"compares ledger"| node_mysql
node_reconciliation -->|"records audit"| node_audit

click node_clientapp "https://github.com/saimandsxroy/autonomous-distributed-banking-compliance/blob/main/client/src/App.jsx"
click node_treasuryapi "https://github.com/saimandsxroy/autonomous-distributed-banking-compliance/blob/main/client/src/api/treasuryApi.js"
click node_gateway "https://github.com/saimandsxroy/autonomous-distributed-banking-compliance/blob/main/server/src/main/java/com/runestone/treasury/config/SpringSecurity.java"
click node_idempotency "https://github.com/saimandsxroy/autonomous-distributed-banking-compliance/blob/main/server/src/main/java/com/runestone/treasury/service/IdempotencyService.java"
click node_journal "https://github.com/saimandsxroy/autonomous-distributed-banking-compliance/blob/main/server/src/main/java/com/runestone/treasury/service/JournalEntryService.java"
click node_journalentity "https://github.com/saimandsxroy/autonomous-distributed-banking-compliance/blob/main/server/src/main/java/com/runestone/treasury/entity/JournalEntry.java"
click node_posting "https://github.com/saimandsxroy/autonomous-distributed-banking-compliance/blob/main/server/src/main/java/com/runestone/treasury/entity/PostingLeg.java"
click node_account "https://github.com/saimandsxroy/autonomous-distributed-banking-compliance/blob/main/server/src/main/java/com/runestone/treasury/entity/TreasuryAccount.java"
click node_accountrepo "https://github.com/saimandsxroy/autonomous-distributed-banking-compliance/blob/main/server/src/main/java/com/runestone/treasury/repository/TreasuryAccountRepository.java"
click node_outbox "https://github.com/saimandsxroy/autonomous-distributed-banking-compliance/blob/main/server/src/main/java/com/runestone/treasury/scheduler/OutboxRelayScheduler.java"
click node_consumer "https://github.com/saimandsxroy/autonomous-distributed-banking-compliance/blob/main/server/src/main/java/com/runestone/treasury/service/TreasuryEventConsumerService.java"
click node_graphdetect "https://github.com/saimandsxroy/autonomous-distributed-banking-compliance/blob/main/server/src/main/java/com/runestone/treasury/service/AmlGraphDetectionService.java"
click node_hold "https://github.com/saimandsxroy/autonomous-distributed-banking-compliance/blob/main/server/src/main/java/com/runestone/treasury/service/BalanceHoldService.java"
click node_holdentity "https://github.com/saimandsxroy/autonomous-distributed-banking-compliance/blob/main/server/src/main/java/com/runestone/treasury/entity/BalanceHold.java"
click node_rag "https://github.com/saimandsxroy/autonomous-distributed-banking-compliance/blob/main/server/src/main/java/com/runestone/treasury/service/AmlPolicyRagService.java"
click node_investigation "https://github.com/saimandsxroy/autonomous-distributed-banking-compliance/blob/main/server/src/main/java/com/runestone/treasury/service/GeminiAmlDetectiveService.java"
click node_hitl "https://github.com/saimandsxroy/autonomous-distributed-banking-compliance/blob/main/server/src/main/java/com/runestone/treasury/service/HitlApprovalService.java"
click node_sar "https://github.com/saimandsxroy/autonomous-distributed-banking-compliance/blob/main/server/src/main/java/com/runestone/treasury/service/SarPdfExportService.java"
click node_batch "https://github.com/saimandsxroy/autonomous-distributed-banking-compliance/blob/main/server/src/main/java/com/runestone/treasury/service/SettlementBatchService.java"
click node_fx "https://github.com/saimandsxroy/autonomous-distributed-banking-compliance/blob/main/server/src/main/java/com/runestone/treasury/service/FxTreasuryService.java"
click node_reconciliation "https://github.com/saimandsxroy/autonomous-distributed-banking-compliance/blob/main/server/src/main/java/com/runestone/treasury/service/EodReconciliationService.java"
click node_audit "https://github.com/saimandsxroy/autonomous-distributed-banking-compliance/blob/main/server/src/main/java/com/runestone/treasury/service/ComplianceAuditLogService.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_clientapp,node_treasuryapi toneBlue
class node_gateway,node_idempotency,node_journal,node_journalentity,node_posting,node_account,node_accountrepo,node_mysql,node_outbox,node_kafka toneAmber
class node_consumer,node_graphdetect,node_hold,node_holdentity,node_rag,node_investigation,node_gemini,node_hitl,node_sar toneMint
class node_batch,node_fx,node_reconciliation,node_audit toneRose
class node_merchant,node_compliance toneIndigo
```

## Components

### Treasury client

- [React client](https://github.com/saimandsxroy/autonomous-distributed-banking-compliance/blob/main/client/src/App.jsx): `client/src/App.jsx`
- [Client API](https://github.com/saimandsxroy/autonomous-distributed-banking-compliance/blob/main/client/src/api/treasuryApi.js): `client/src/api/treasuryApi.js`

### Ledger and payments

- [Security gateway](https://github.com/saimandsxroy/autonomous-distributed-banking-compliance/blob/main/server/src/main/java/com/runestone/treasury/config/SpringSecurity.java): `server/src/main/java/com/runestone/treasury/config/SpringSecurity.java`
- [Idempotency and velocity](https://github.com/saimandsxroy/autonomous-distributed-banking-compliance/blob/main/server/src/main/java/com/runestone/treasury/service/IdempotencyService.java): `server/src/main/java/com/runestone/treasury/service/IdempotencyService.java`
- [Double-entry ledger](https://github.com/saimandsxroy/autonomous-distributed-banking-compliance/blob/main/server/src/main/java/com/runestone/treasury/service/JournalEntryService.java): `server/src/main/java/com/runestone/treasury/service/JournalEntryService.java`
- [Journal entries](https://github.com/saimandsxroy/autonomous-distributed-banking-compliance/blob/main/server/src/main/java/com/runestone/treasury/entity/JournalEntry.java): `server/src/main/java/com/runestone/treasury/entity/JournalEntry.java`
- [Posting legs](https://github.com/saimandsxroy/autonomous-distributed-banking-compliance/blob/main/server/src/main/java/com/runestone/treasury/entity/PostingLeg.java): `server/src/main/java/com/runestone/treasury/entity/PostingLeg.java`
- [Treasury accounts](https://github.com/saimandsxroy/autonomous-distributed-banking-compliance/blob/main/server/src/main/java/com/runestone/treasury/entity/TreasuryAccount.java): `server/src/main/java/com/runestone/treasury/entity/TreasuryAccount.java`
- [Account repository](https://github.com/saimandsxroy/autonomous-distributed-banking-compliance/blob/main/server/src/main/java/com/runestone/treasury/repository/TreasuryAccountRepository.java): `server/src/main/java/com/runestone/treasury/repository/TreasuryAccountRepository.java`
- **MySQL ledger store**
- [Outbox relay](https://github.com/saimandsxroy/autonomous-distributed-banking-compliance/blob/main/server/src/main/java/com/runestone/treasury/scheduler/OutboxRelayScheduler.java): `server/src/main/java/com/runestone/treasury/scheduler/OutboxRelayScheduler.java`
- **Kafka events**

### Sentinel AML

- [Treasury event consumer](https://github.com/saimandsxroy/autonomous-distributed-banking-compliance/blob/main/server/src/main/java/com/runestone/treasury/service/TreasuryEventConsumerService.java): `server/src/main/java/com/runestone/treasury/service/TreasuryEventConsumerService.java`
- [Graph detection](https://github.com/saimandsxroy/autonomous-distributed-banking-compliance/blob/main/server/src/main/java/com/runestone/treasury/service/AmlGraphDetectionService.java): `server/src/main/java/com/runestone/treasury/service/AmlGraphDetectionService.java`
- [Balance holds](https://github.com/saimandsxroy/autonomous-distributed-banking-compliance/blob/main/server/src/main/java/com/runestone/treasury/service/BalanceHoldService.java): `server/src/main/java/com/runestone/treasury/service/BalanceHoldService.java`
- [Hold records](https://github.com/saimandsxroy/autonomous-distributed-banking-compliance/blob/main/server/src/main/java/com/runestone/treasury/entity/BalanceHold.java): `server/src/main/java/com/runestone/treasury/entity/BalanceHold.java`
- [Policy RAG](https://github.com/saimandsxroy/autonomous-distributed-banking-compliance/blob/main/server/src/main/java/com/runestone/treasury/service/AmlPolicyRagService.java): `server/src/main/java/com/runestone/treasury/service/AmlPolicyRagService.java`
- [AI investigation](https://github.com/saimandsxroy/autonomous-distributed-banking-compliance/blob/main/server/src/main/java/com/runestone/treasury/service/GeminiAmlDetectiveService.java): `server/src/main/java/com/runestone/treasury/service/GeminiAmlDetectiveService.java`
- **Gemini AI**
- [Officer approval](https://github.com/saimandsxroy/autonomous-distributed-banking-compliance/blob/main/server/src/main/java/com/runestone/treasury/service/HitlApprovalService.java): `server/src/main/java/com/runestone/treasury/service/HitlApprovalService.java`
- [SAR PDF export](https://github.com/saimandsxroy/autonomous-distributed-banking-compliance/blob/main/server/src/main/java/com/runestone/treasury/service/SarPdfExportService.java): `server/src/main/java/com/runestone/treasury/service/SarPdfExportService.java`

### Treasury operations

- [Batch settlement](https://github.com/saimandsxroy/autonomous-distributed-banking-compliance/blob/main/server/src/main/java/com/runestone/treasury/service/SettlementBatchService.java): `server/src/main/java/com/runestone/treasury/service/SettlementBatchService.java`
- [FX treasury](https://github.com/saimandsxroy/autonomous-distributed-banking-compliance/blob/main/server/src/main/java/com/runestone/treasury/service/FxTreasuryService.java): `server/src/main/java/com/runestone/treasury/service/FxTreasuryService.java`
- [EOD reconciliation](https://github.com/saimandsxroy/autonomous-distributed-banking-compliance/blob/main/server/src/main/java/com/runestone/treasury/service/EodReconciliationService.java): `server/src/main/java/com/runestone/treasury/service/EodReconciliationService.java`
- [Compliance audit](https://github.com/saimandsxroy/autonomous-distributed-banking-compliance/blob/main/server/src/main/java/com/runestone/treasury/service/ComplianceAuditLogService.java): `server/src/main/java/com/runestone/treasury/service/ComplianceAuditLogService.java`

### Other components

- **B2B merchant**
- **Compliance officer**

## Connections

- B2B merchant → React client: initiates activity
- React client → Client API: requests API
- React client → Security gateway: sends requests
- Security gateway → Idempotency and velocity: checks requests
- Idempotency and velocity → Double-entry ledger: permits posting
- Double-entry ledger → MySQL ledger store: commits ledger
- Double-entry ledger → Journal entries: persists entries (evidence: `server/src/main/java/com/runestone/treasury/service/JournalEntryService.java`)
- Double-entry ledger → Posting legs: creates legs (evidence: `server/src/main/java/com/runestone/treasury/service/JournalEntryService.java`)
- Double-entry ledger → Account repository: locks accounts (evidence: `server/src/main/java/com/runestone/treasury/service/JournalEntryService.java`)
- Account repository → Treasury accounts: loads accounts (evidence: `server/src/main/java/com/runestone/treasury/repository/TreasuryAccountRepository.java`)
- Double-entry ledger → Outbox relay: writes outbox
- Outbox relay → Kafka events: relays events
- Kafka events → Treasury event consumer: dispatches events
- Treasury event consumer → Graph detection: checks transactions
- Graph detection → Balance holds: flags cycles
- Balance holds → Hold records: records quarantine
- Balance holds → AI investigation: triggers review
- AI investigation → Policy RAG: retrieves policies
- AI investigation → Gemini AI: requests analysis
- AI investigation → Officer approval: opens approval
- Compliance officer → Officer approval: reviews case
- Compliance officer → SAR PDF export: requests filing
- Batch settlement → Double-entry ledger: posts transfers (evidence: `server/src/main/java/com/runestone/treasury/service/SettlementBatchService.java`)
- Double-entry ledger → FX treasury: calculates FX quote (evidence: `server/src/main/java/com/runestone/treasury/service/JournalEntryService.java`)
- EOD reconciliation → MySQL ledger store: compares ledger (evidence: `server/src/main/java/com/runestone/treasury/service/EodReconciliationService.java`)
- EOD reconciliation → Compliance audit: records audit (evidence: `server/src/main/java/com/runestone/treasury/service/EodReconciliationService.java`)