act1lazi0n/atc_project

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.