# act1lazi0n/atc_project architecture

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

- Interactive diagram: https://gitdiagram.com/act1lazi0n/atc_project
- Repository: https://github.com/act1lazi0n/atc_project

## Overview

#### Purpose and Runtime
Aries Transaction Core is a Java 21/Spring Boot financial transaction service. It owns accounts, internal money movement, ledger truth, settlement accounting, and reconciliation records; reporting is external/read-only. Boot entry point: `src/main/java/com/actilazion/aries_transaction/AriesTransactionApplication.java`. HTTP entry points are domain controllers, notably auth, transfer, settlement, and reconciliation APIs.

#### Layering and Persistence Boundary
Each business domain follows API → application service → domain model → JPA repository. Controllers expose DTOs; application services coordinate transactional workflows; domain entities encode states/types; repositories persist to PostgreSQL. The canonical schema evolves through Flyway migrations in `src/main/resources/db/migration/V1__init_schema.sql` through later feature migrations such as `V27__add_login_protection.sql`.

#### Identity and Request Security
Authentication registers/logs in users and issues JWT access credentials, with refresh-session persistence. Spring Security enforces stateless request authentication and authorization through:
- `src/main/java/com/actilazion/aries_transaction/identity/api/AuthController.java`
- `src/main/java/com/actilazion/aries_transaction/identity/application/AuthServiceImpl.java`
- `src/main/java/com/actilazion/aries_transaction/config/SecurityConfig.java`
- `src/main/java/com/actilazion/aries_transaction/config/JwtAuthFilter.java`

Identity audit logging is separate from financial audit records. Privileged service-layer operations include settlement and reconciliation.

#### Accounts, Transfers, and Financial Invariants
Account lifecycle/ownership is managed by `account`; transfer, reversal, and refund commands are the core synchronous workflow in:
- `src/main/java/com/actilazion/aries_transaction/transaction/api/TransferController.java`
- `src/main/java/com/actilazion/aries_transaction/transaction/application/TransferServiceImpl.java`
- `src/main/java/com/actilazion/aries_transaction/transaction/domain/TransactionStateGuard.java`

A transfer coordinates pessimistically locked accounts, active-status/ownership/currency/balance validation, account balance updates, transaction lifecycle state, audit events, ledger postings, outbox persistence, and idempotency completion in one database transaction. Scoped idempotency records prevent replay/conflict across transfer operations.

#### Ledger and Audit Recordkeeping
The ledger is append-only double-entry accounting: each monetary action emits balanced debit/credit entries rather than editing historical records. Reversal, refund, or compensating entries repair movement. Core persistence and services are:
- `src/main/java/com/actilazion/aries_transaction/ledger/application/LedgerServiceImpl.java`
- `src/main/java/com/actilazion/aries_transaction/ledger/domain/LedgerEntry.java`
- `src/main/java/com/actilazion/aries_transaction/audit/application/AuditLogService.java`

#### Outbox and Asynchronous Boundary
Business transactions write outbox events atomically with source-of-truth state. A worker claims/publishes pending events after commit, isolating downstream delivery from the transaction path:
- `src/main/java/com/actilazion/aries_transaction/outbox/application/OutboxEventService.java`
- `src/main/java/com/actilazion/aries_transaction/outbox/infrastructure/worker/OutboxWorker.java`
- `src/main/java/com/actilazion/aries_transaction/outbox/infrastructure/worker/OutboxEventPublisher.java`

The configured publisher is currently capable of being a no-op; downstream reporting/fraud integrations are not owned here.

#### Settlement and Reconciliation
Settlement creates idempotent batches/items/payout attempts and records gross, fee, net, and adjustment accounting:
- `src/main/java/com/actilazion/aries_transaction/settlement/application/SettlementServiceImpl.java`
- `src/main/java/com/actilazion/aries_transaction/settlement/domain/SettlementBatch.java`

Reconciliation compares core transactions against reporting snapshots for a completed-at time window, persists runs/exceptions, and does not mutate transaction truth:
- `src/main/java/com/actilazion/aries_transaction/reconciliation/application/ReconciliationServiceImpl.java`
- `src/main/java/com/actilazion/aries_transaction/reconciliation/infrastructure/HttpReportingTransactionSnapshotClient.java`
- `src/main/java/com/actilazion/aries_transaction/reconciliation/domain/ReconciliationRun.java`

#### Infrastructure
PostgreSQL 16 is authoritative for financial and identity state; Flyway owns schema migration. Redis is only ephemeral/advisory: auth rate limits and login counters fail closed if unavailable, while short-lived duplicate suppression may bypass on failure. Redis adapters live under `src/main/java/com/actilazion/aries_transaction/common/redis` and `identity/infrastructure/redis`. `docker-compose.yml` runs app, PostgreSQL, and Redis; configuration profiles are in `src/main/resources/application.yml` and Docker/dev variants.

Main entry points: [`src/main/java/com/actilazion/aries_transaction/transaction/application/TransferServiceImpl.java`](https://github.com/act1lazi0n/atc_project/blob/main/src/main/java/com/actilazion/aries_transaction/transaction/application/TransferServiceImpl.java) (Transfer workflow), [`src/main/java/com/actilazion/aries_transaction/config/SecurityConfig.java`](https://github.com/act1lazi0n/atc_project/blob/main/src/main/java/com/actilazion/aries_transaction/config/SecurityConfig.java) (Security chain), [`src/main/java/com/actilazion/aries_transaction/identity/application/AuthServiceImpl.java`](https://github.com/act1lazi0n/atc_project/blob/main/src/main/java/com/actilazion/aries_transaction/identity/application/AuthServiceImpl.java) (Identity service), [`src/main/java/com/actilazion/aries_transaction/ledger/application/LedgerServiceImpl.java`](https://github.com/act1lazi0n/atc_project/blob/main/src/main/java/com/actilazion/aries_transaction/ledger/application/LedgerServiceImpl.java) (Ledger service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_edge["HTTP & Security"]
  node_boot["Spring Boot app<br/>runtime entry"]
  node_security["Security chain<br/>Spring Security"]
  node_jwt_filter["JWT filter<br/>request filter<br/>[JwtAuthFilter.java]"]
  node_auth_api["Auth API<br/>controller"]
  node_auth_service["Identity service<br/>application service"]
end

subgraph group_core["Core Financial Workflows"]
  node_transfer_api["Transfer API<br/>controller"]
  node_transfer_service["Transfer workflow<br/>application service"]
  node_state_guard["Transaction state guard<br/>domain policy"]
  node_account_state[("Accounts &amp; transactions<br/>JPA domain state")]
  node_idempotency["Scoped idempotency<br/>persistent workflow state"]
  node_settlement["Settlement workflow<br/>application service"]
  node_settlement_batch["Settlement batch<br/>domain model"]
  node_reconciliation["Reconciliation workflow<br/>application service"]
  node_reconciliation_run["Reconciliation run<br/>domain model"]
end

subgraph group_records["Financial Records"]
  node_ledger_service["Ledger service<br/>application service"]
  node_ledger_entries["Ledger entries<br/>append-only domain record<br/>[LedgerEntry.java]"]
  node_audit["Audit log service<br/>application service"]
end

subgraph group_async["Async Delivery"]
  node_outbox_service["Outbox service<br/>transactional outbox"]
  node_outbox_worker["Outbox worker<br/>background worker<br/>[OutboxWorker.java]"]
  node_outbox_publisher["Outbox publisher<br/>publisher adapter"]
end

subgraph group_external["Infrastructure &amp; External Reads"]
  node_reporting_client["Reporting snapshot client<br/>HTTP client"]
  node_postgres[("PostgreSQL 16<br/>authoritative database")]
  node_flyway["Flyway schema<br/>migration history"]
  node_redis[("Redis<br/>ephemeral store")]
end

node_boot -->|"configures"| node_security
node_security -->|"runs"| node_jwt_filter
node_security -->|"protects"| node_auth_api
node_auth_api -->|"delegates"| node_auth_service
node_auth_service -->|"persists identity/session state"| node_postgres
node_auth_service -->|"uses for login protection"| node_redis
node_transfer_api -->|"delegates"| node_transfer_service
node_transfer_service -->|"validates lifecycle"| node_state_guard
node_transfer_service -->|"locks and updates"| node_account_state
node_transfer_service -->|"completes"| node_idempotency
node_transfer_service -->|"emits postings"| node_ledger_service
node_ledger_service -->|"writes"| node_ledger_entries
node_transfer_service -->|"records event"| node_audit
node_transfer_service -->|"writes atomically"| node_outbox_service
node_account_state -->|"persists"| node_postgres
node_idempotency -->|"persists"| node_postgres
node_ledger_entries -->|"persists"| node_postgres
node_audit -->|"persists"| node_postgres
node_settlement -->|"creates"| node_settlement_batch
node_settlement -->|"records accounting"| node_ledger_service
node_settlement_batch -->|"persists"| node_postgres
node_reconciliation -->|"reads snapshots"| node_reporting_client
node_reconciliation -->|"persists runs/exceptions"| node_reconciliation_run
node_reconciliation_run -->|"persists"| node_postgres
node_outbox_service -->|"persists events"| node_postgres
node_outbox_worker -->|"claims pending"| node_outbox_service
node_outbox_worker -->|"publishes"| node_outbox_publisher
node_flyway -->|"migrates schema"| node_postgres

click node_boot "https://github.com/act1lazi0n/atc_project/blob/main/src/main/java/com/actilazion/aries_transaction/AriesTransactionApplication.java"
click node_security "https://github.com/act1lazi0n/atc_project/blob/main/src/main/java/com/actilazion/aries_transaction/config/SecurityConfig.java"
click node_jwt_filter "https://github.com/act1lazi0n/atc_project/blob/main/src/main/java/com/actilazion/aries_transaction/config/JwtAuthFilter.java"
click node_auth_api "https://github.com/act1lazi0n/atc_project/blob/main/src/main/java/com/actilazion/aries_transaction/identity/api/AuthController.java"
click node_auth_service "https://github.com/act1lazi0n/atc_project/blob/main/src/main/java/com/actilazion/aries_transaction/identity/application/AuthServiceImpl.java"
click node_transfer_api "https://github.com/act1lazi0n/atc_project/blob/main/src/main/java/com/actilazion/aries_transaction/transaction/api/TransferController.java"
click node_transfer_service "https://github.com/act1lazi0n/atc_project/blob/main/src/main/java/com/actilazion/aries_transaction/transaction/application/TransferServiceImpl.java"
click node_state_guard "https://github.com/act1lazi0n/atc_project/blob/main/src/main/java/com/actilazion/aries_transaction/transaction/domain/TransactionStateGuard.java"
click node_ledger_service "https://github.com/act1lazi0n/atc_project/blob/main/src/main/java/com/actilazion/aries_transaction/ledger/application/LedgerServiceImpl.java"
click node_ledger_entries "https://github.com/act1lazi0n/atc_project/blob/main/src/main/java/com/actilazion/aries_transaction/ledger/domain/LedgerEntry.java"
click node_audit "https://github.com/act1lazi0n/atc_project/blob/main/src/main/java/com/actilazion/aries_transaction/audit/application/AuditLogService.java"
click node_settlement "https://github.com/act1lazi0n/atc_project/blob/main/src/main/java/com/actilazion/aries_transaction/settlement/application/SettlementServiceImpl.java"
click node_settlement_batch "https://github.com/act1lazi0n/atc_project/blob/main/src/main/java/com/actilazion/aries_transaction/settlement/domain/SettlementBatch.java"
click node_reconciliation "https://github.com/act1lazi0n/atc_project/blob/main/src/main/java/com/actilazion/aries_transaction/reconciliation/application/ReconciliationServiceImpl.java"
click node_reconciliation_run "https://github.com/act1lazi0n/atc_project/blob/main/src/main/java/com/actilazion/aries_transaction/reconciliation/domain/ReconciliationRun.java"
click node_reporting_client "https://github.com/act1lazi0n/atc_project/blob/main/src/main/java/com/actilazion/aries_transaction/reconciliation/infrastructure/HttpReportingTransactionSnapshotClient.java"
click node_outbox_service "https://github.com/act1lazi0n/atc_project/blob/main/src/main/java/com/actilazion/aries_transaction/outbox/application/OutboxEventService.java"
click node_outbox_worker "https://github.com/act1lazi0n/atc_project/blob/main/src/main/java/com/actilazion/aries_transaction/outbox/infrastructure/worker/OutboxWorker.java"
click node_outbox_publisher "https://github.com/act1lazi0n/atc_project/blob/main/src/main/java/com/actilazion/aries_transaction/outbox/infrastructure/worker/OutboxEventPublisher.java"
click node_flyway "https://github.com/act1lazi0n/atc_project/blob/main/src/main/resources/db/migration/V1__init_schema.sql"
click node_redis "https://github.com/act1lazi0n/atc_project/tree/main/src/main/java/com/actilazion/aries_transaction/common/redis"

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_boot,node_security,node_jwt_filter,node_auth_api,node_auth_service toneBlue
class node_transfer_api,node_transfer_service,node_state_guard,node_account_state,node_idempotency,node_settlement,node_settlement_batch,node_reconciliation,node_reconciliation_run toneAmber
class node_ledger_service,node_ledger_entries,node_audit toneMint
class node_outbox_service,node_outbox_worker,node_outbox_publisher toneRose
class node_reporting_client,node_postgres,node_flyway,node_redis toneIndigo
```

## Components

### HTTP & Security

- [Spring Boot app](https://github.com/act1lazi0n/atc_project/blob/main/src/main/java/com/actilazion/aries_transaction/AriesTransactionApplication.java): runtime entry · Java 21 service runtime. · `src/main/java/com/actilazion/aries_transaction/AriesTransactionApplication.java`
- [Security chain](https://github.com/act1lazi0n/atc_project/blob/main/src/main/java/com/actilazion/aries_transaction/config/SecurityConfig.java): Spring Security · Stateless JWT authentication and authorization. · `src/main/java/com/actilazion/aries_transaction/config/SecurityConfig.java`
- [JWT filter](https://github.com/act1lazi0n/atc_project/blob/main/src/main/java/com/actilazion/aries_transaction/config/JwtAuthFilter.java): request filter · `src/main/java/com/actilazion/aries_transaction/config/JwtAuthFilter.java`
- [Auth API](https://github.com/act1lazi0n/atc_project/blob/main/src/main/java/com/actilazion/aries_transaction/identity/api/AuthController.java): controller · `src/main/java/com/actilazion/aries_transaction/identity/api/AuthController.java`
- [Identity service](https://github.com/act1lazi0n/atc_project/blob/main/src/main/java/com/actilazion/aries_transaction/identity/application/AuthServiceImpl.java): application service · Registers/logs in users and persists refresh sessions. · `src/main/java/com/actilazion/aries_transaction/identity/application/AuthServiceImpl.java`

### Core Financial Workflows

- [Transfer API](https://github.com/act1lazi0n/atc_project/blob/main/src/main/java/com/actilazion/aries_transaction/transaction/api/TransferController.java): controller · `src/main/java/com/actilazion/aries_transaction/transaction/api/TransferController.java`
- [Transfer workflow](https://github.com/act1lazi0n/atc_project/blob/main/src/main/java/com/actilazion/aries_transaction/transaction/application/TransferServiceImpl.java): application service · Executes transfer, reversal, and refund atomically. · `src/main/java/com/actilazion/aries_transaction/transaction/application/TransferServiceImpl.java`
- [Transaction state guard](https://github.com/act1lazi0n/atc_project/blob/main/src/main/java/com/actilazion/aries_transaction/transaction/domain/TransactionStateGuard.java): domain policy · `src/main/java/com/actilazion/aries_transaction/transaction/domain/TransactionStateGuard.java`
- **Accounts & transactions**: JPA domain state · Locked accounts enforce ownership, status, currency, and balance checks.
- **Scoped idempotency**: persistent workflow state · Prevents replay and operation conflicts.
- [Settlement workflow](https://github.com/act1lazi0n/atc_project/blob/main/src/main/java/com/actilazion/aries_transaction/settlement/application/SettlementServiceImpl.java): application service · Creates idempotent batches, items, payout attempts, and settlement accounting. · `src/main/java/com/actilazion/aries_transaction/settlement/application/SettlementServiceImpl.java`
- [Settlement batch](https://github.com/act1lazi0n/atc_project/blob/main/src/main/java/com/actilazion/aries_transaction/settlement/domain/SettlementBatch.java): domain model · `src/main/java/com/actilazion/aries_transaction/settlement/domain/SettlementBatch.java`
- [Reconciliation workflow](https://github.com/act1lazi0n/atc_project/blob/main/src/main/java/com/actilazion/aries_transaction/reconciliation/application/ReconciliationServiceImpl.java): application service · Persists read-only comparison runs and exceptions. · `src/main/java/com/actilazion/aries_transaction/reconciliation/application/ReconciliationServiceImpl.java`
- [Reconciliation run](https://github.com/act1lazi0n/atc_project/blob/main/src/main/java/com/actilazion/aries_transaction/reconciliation/domain/ReconciliationRun.java): domain model · `src/main/java/com/actilazion/aries_transaction/reconciliation/domain/ReconciliationRun.java`

### Financial Records

- [Ledger service](https://github.com/act1lazi0n/atc_project/blob/main/src/main/java/com/actilazion/aries_transaction/ledger/application/LedgerServiceImpl.java): application service · Writes balanced double-entry postings. · `src/main/java/com/actilazion/aries_transaction/ledger/application/LedgerServiceImpl.java`
- [Ledger entries](https://github.com/act1lazi0n/atc_project/blob/main/src/main/java/com/actilazion/aries_transaction/ledger/domain/LedgerEntry.java): append-only domain record · Compensating entries handle reversals and refunds. · `src/main/java/com/actilazion/aries_transaction/ledger/domain/LedgerEntry.java`
- [Audit log service](https://github.com/act1lazi0n/atc_project/blob/main/src/main/java/com/actilazion/aries_transaction/audit/application/AuditLogService.java): application service · Financial audit recordkeeping is separate from identity audit. · `src/main/java/com/actilazion/aries_transaction/audit/application/AuditLogService.java`

### Async Delivery

- [Outbox service](https://github.com/act1lazi0n/atc_project/blob/main/src/main/java/com/actilazion/aries_transaction/outbox/application/OutboxEventService.java): transactional outbox · Persists events with source-of-truth changes. · `src/main/java/com/actilazion/aries_transaction/outbox/application/OutboxEventService.java`
- [Outbox worker](https://github.com/act1lazi0n/atc_project/blob/main/src/main/java/com/actilazion/aries_transaction/outbox/infrastructure/worker/OutboxWorker.java): background worker · Claims pending events after commit. · `src/main/java/com/actilazion/aries_transaction/outbox/infrastructure/worker/OutboxWorker.java`
- [Outbox publisher](https://github.com/act1lazi0n/atc_project/blob/main/src/main/java/com/actilazion/aries_transaction/outbox/infrastructure/worker/OutboxEventPublisher.java): publisher adapter · Configured delivery may be a no-op. · `src/main/java/com/actilazion/aries_transaction/outbox/infrastructure/worker/OutboxEventPublisher.java`

### Infrastructure & External Reads

- [Reporting snapshot client](https://github.com/act1lazi0n/atc_project/blob/main/src/main/java/com/actilazion/aries_transaction/reconciliation/infrastructure/HttpReportingTransactionSnapshotClient.java): HTTP client · Reads completed-window transaction snapshots from external reporting. · `src/main/java/com/actilazion/aries_transaction/reconciliation/infrastructure/HttpReportingTransactionSnapshotClient.java`
- **PostgreSQL 16**: authoritative database · Financial, identity, outbox, and reconciliation persistence.
- [Flyway schema](https://github.com/act1lazi0n/atc_project/blob/main/src/main/resources/db/migration/V1__init_schema.sql): migration history · Canonical schema evolves from V1 through later migrations. · `src/main/resources/db/migration/V1__init_schema.sql`
- [Redis](https://github.com/act1lazi0n/atc_project/tree/main/src/main/java/com/actilazion/aries_transaction/common/redis): ephemeral store · Rate limits/login counters fail closed; duplicate suppression may bypass on failure. · `src/main/java/com/actilazion/aries_transaction/common/redis`

## Connections

- Spring Boot app → Security chain: configures
- Security chain → JWT filter: runs
- Security chain → Auth API: protects
- Auth API → Identity service: delegates
- Identity service → PostgreSQL 16: persists identity/session state
- Identity service → Redis: uses for login protection
- Transfer API → Transfer workflow: delegates
- Transfer workflow → Transaction state guard: validates lifecycle
- Transfer workflow → Accounts & transactions: locks and updates
- Transfer workflow → Scoped idempotency: completes
- Transfer workflow → Ledger service: emits postings
- Ledger service → Ledger entries: writes
- Transfer workflow → Audit log service: records event
- Transfer workflow → Outbox service: writes atomically
- Accounts & transactions → PostgreSQL 16: persists
- Scoped idempotency → PostgreSQL 16: persists
- Ledger entries → PostgreSQL 16: persists
- Audit log service → PostgreSQL 16: persists
- Settlement workflow → Settlement batch: creates
- Settlement workflow → Ledger service: records accounting
- Settlement batch → PostgreSQL 16: persists
- Reconciliation workflow → Reporting snapshot client: reads snapshots
- Reconciliation workflow → Reconciliation run: persists runs/exceptions
- Reconciliation run → PostgreSQL 16: persists
- Outbox service → PostgreSQL 16: persists events
- Outbox worker → Outbox service: claims pending
- Outbox worker → Outbox publisher: publishes
- Flyway schema → PostgreSQL 16: migrates schema