# lcsalvess/banking-system architecture

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

- Interactive diagram: https://gitdiagram.com/lcsalvess/banking-system
- Repository: https://github.com/lcsalvess/banking-system

## Overview

This is a Spring Boot banking REST backend. Users authenticate and receive JWT-based access; authorized staff then manage clients and accounts or perform and query financial transactions. Those operations persist to PostgreSQL, while scheduled yield, reconciliation, and idempotency maintenance support the transaction lifecycle. Separate capabilities include address-provider lookup and an auditor-facing, snapshot-paged audit trail. The map emphasizes these domain stages and security; source excerpts are partial, so unsampled implementation links are documented by the README or left unasserted.

Main entry points: [`src/main/java/com/lcsalvess/bankingsystem/controller/auth/AuthenticationController.java`](https://github.com/lcsalvess/banking-system/blob/master/src/main/java/com/lcsalvess/bankingsystem/controller/auth/AuthenticationController.java) (REST endpoints), [`src/main/java/com/lcsalvess/bankingsystem/service/transaction/TransactionService.java`](https://github.com/lcsalvess/banking-system/blob/master/src/main/java/com/lcsalvess/bankingsystem/service/transaction/TransactionService.java) (Financial operations), [`src/main/java/com/lcsalvess/bankingsystem/service/security/AuthenticationService.java`](https://github.com/lcsalvess/banking-system/blob/master/src/main/java/com/lcsalvess/bankingsystem/service/security/AuthenticationService.java) (Authentication), [`src/main/java/com/lcsalvess/bankingsystem/integration/address/AddressLookupService.java`](https://github.com/lcsalvess/banking-system/blob/master/src/main/java/com/lcsalvess/bankingsystem/integration/address/AddressLookupService.java) (Postal providers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access and identity"]
  node_api["REST endpoints"]
  node_authentication["Authentication"]
  node_ratelimit["Login protection"]
  node_jwt["JWT security<br/>[JwtService.java]"]
  node_user["User management<br/>[UserService.java]"]
  node_currentuser["Current user"]
end

subgraph group_customer["Customer banking"]
  node_client["Client management<br/>[ClientService.java]"]
  node_address["Address resolution"]
  node_addressproviders["Postal providers"]
  node_account["Account management"]
end

subgraph group_money["Transactions and operations"]
  node_transactions["Financial operations"]
  node_transactionquery["Transaction queries"]
  node_idempotency["Idempotency"]
  node_yield["Daily yield"]
  node_reconciliation["Balance reconciliation"]
end

subgraph group_audit["Audit trail"]
  node_auditrecord["Audit recording<br/>[AuditService.java]"]
  node_auditquery["Audit queries"]
  node_auditsnapshot["Query snapshots"]
end

subgraph group_platform["Persistence and integrations"]
  node_postgres[("PostgreSQL")]
  node_via["ViaCEP"]
  node_brasil["BrasilAPI"]
end

node_staff(("API user"))

node_staff -->|"sends requests"| node_api
node_api -->|"handles login"| node_authentication
node_authentication -->|"checks attempts"| node_ratelimit
node_authentication -->|"issues tokens"| node_jwt
node_api -->|"manages users"| node_user
node_api -->|"manages clients"| node_client
node_client -->|"resolves postal codes"| node_address
node_address -.->|"looks up addresses"| node_addressproviders
node_addressproviders -.->|"uses provider"| node_via
node_addressproviders -.->|"fallback provider"| node_brasil
node_api -->|"manages accounts"| node_account
node_api -->|"initiates operations"| node_transactions
node_transactions -->|"gets actor"| node_currentuser
node_api -->|"queries history"| node_transactionquery
node_transactionquery -->|"checks account"| node_account
node_transactionquery -->|"reads transactions"| node_postgres
node_transactions -.->|"guards retries"| node_idempotency
node_yield -->|"records yield"| node_postgres
node_reconciliation -->|"checks balances"| node_postgres
node_api -->|"queries audit trail"| node_auditquery
node_auditquery -->|"pages snapshots"| node_auditsnapshot
node_auditsnapshot -->|"stores snapshot data"| node_postgres
node_auditrecord -->|"records events"| node_postgres
node_transactions -->|"persists operations"| node_postgres

click node_api "https://github.com/lcsalvess/banking-system/blob/master/src/main/java/com/lcsalvess/bankingsystem/controller/auth/AuthenticationController.java"
click node_authentication "https://github.com/lcsalvess/banking-system/blob/master/src/main/java/com/lcsalvess/bankingsystem/service/security/AuthenticationService.java"
click node_ratelimit "https://github.com/lcsalvess/banking-system/blob/master/src/main/java/com/lcsalvess/bankingsystem/service/security/ratelimit/RateLimitProtectionService.java"
click node_jwt "https://github.com/lcsalvess/banking-system/blob/master/src/main/java/com/lcsalvess/bankingsystem/service/security/JwtService.java"
click node_user "https://github.com/lcsalvess/banking-system/blob/master/src/main/java/com/lcsalvess/bankingsystem/service/user/UserService.java"
click node_currentuser "https://github.com/lcsalvess/banking-system/blob/master/src/main/java/com/lcsalvess/bankingsystem/service/security/CurrentUserService.java"
click node_client "https://github.com/lcsalvess/banking-system/blob/master/src/main/java/com/lcsalvess/bankingsystem/service/client/ClientService.java"
click node_address "https://github.com/lcsalvess/banking-system/blob/master/src/main/java/com/lcsalvess/bankingsystem/service/address/AddressService.java"
click node_addressproviders "https://github.com/lcsalvess/banking-system/blob/master/src/main/java/com/lcsalvess/bankingsystem/integration/address/AddressLookupService.java"
click node_account "https://github.com/lcsalvess/banking-system/blob/master/src/main/java/com/lcsalvess/bankingsystem/service/account/AccountService.java"
click node_transactions "https://github.com/lcsalvess/banking-system/blob/master/src/main/java/com/lcsalvess/bankingsystem/service/transaction/TransactionService.java"
click node_transactionquery "https://github.com/lcsalvess/banking-system/blob/master/src/main/java/com/lcsalvess/bankingsystem/service/transaction/query/TransactionQueryService.java"
click node_idempotency "https://github.com/lcsalvess/banking-system/blob/master/src/main/java/com/lcsalvess/bankingsystem/service/transaction/idempotency/TransactionIdempotencyService.java"
click node_yield "https://github.com/lcsalvess/banking-system/blob/master/src/main/java/com/lcsalvess/bankingsystem/service/transaction/yield/DailyYieldService.java"
click node_reconciliation "https://github.com/lcsalvess/banking-system/blob/master/src/main/java/com/lcsalvess/bankingsystem/service/transaction/balancereconciliation/BalanceReconciliationJob.java"
click node_auditrecord "https://github.com/lcsalvess/banking-system/blob/master/src/main/java/com/lcsalvess/bankingsystem/service/audit/recording/AuditService.java"
click node_auditquery "https://github.com/lcsalvess/banking-system/blob/master/src/main/java/com/lcsalvess/bankingsystem/service/audit/query/AuditEventQueryService.java"
click node_auditsnapshot "https://github.com/lcsalvess/banking-system/blob/master/src/main/java/com/lcsalvess/bankingsystem/service/audit/query/snapshot/AuditEventQuerySnapshotService.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_api,node_authentication,node_ratelimit,node_jwt,node_user,node_currentuser,node_staff toneBlue
class node_client,node_address,node_addressproviders,node_account toneAmber
class node_transactions,node_transactionquery,node_idempotency,node_yield,node_reconciliation toneMint
class node_auditrecord,node_auditquery,node_auditsnapshot toneRose
class node_postgres,node_via,node_brasil toneIndigo
```

## Components

### Access and identity

- [REST endpoints](https://github.com/lcsalvess/banking-system/blob/master/src/main/java/com/lcsalvess/bankingsystem/controller/auth/AuthenticationController.java): `src/main/java/com/lcsalvess/bankingsystem/controller/auth/AuthenticationController.java`
- [Authentication](https://github.com/lcsalvess/banking-system/blob/master/src/main/java/com/lcsalvess/bankingsystem/service/security/AuthenticationService.java): `src/main/java/com/lcsalvess/bankingsystem/service/security/AuthenticationService.java`
- [Login protection](https://github.com/lcsalvess/banking-system/blob/master/src/main/java/com/lcsalvess/bankingsystem/service/security/ratelimit/RateLimitProtectionService.java): `src/main/java/com/lcsalvess/bankingsystem/service/security/ratelimit/RateLimitProtectionService.java`
- [JWT security](https://github.com/lcsalvess/banking-system/blob/master/src/main/java/com/lcsalvess/bankingsystem/service/security/JwtService.java): `src/main/java/com/lcsalvess/bankingsystem/service/security/JwtService.java`
- [User management](https://github.com/lcsalvess/banking-system/blob/master/src/main/java/com/lcsalvess/bankingsystem/service/user/UserService.java): `src/main/java/com/lcsalvess/bankingsystem/service/user/UserService.java`
- [Current user](https://github.com/lcsalvess/banking-system/blob/master/src/main/java/com/lcsalvess/bankingsystem/service/security/CurrentUserService.java): `src/main/java/com/lcsalvess/bankingsystem/service/security/CurrentUserService.java`

### Customer banking

- [Client management](https://github.com/lcsalvess/banking-system/blob/master/src/main/java/com/lcsalvess/bankingsystem/service/client/ClientService.java): `src/main/java/com/lcsalvess/bankingsystem/service/client/ClientService.java`
- [Address resolution](https://github.com/lcsalvess/banking-system/blob/master/src/main/java/com/lcsalvess/bankingsystem/service/address/AddressService.java): `src/main/java/com/lcsalvess/bankingsystem/service/address/AddressService.java`
- [Postal providers](https://github.com/lcsalvess/banking-system/blob/master/src/main/java/com/lcsalvess/bankingsystem/integration/address/AddressLookupService.java): `src/main/java/com/lcsalvess/bankingsystem/integration/address/AddressLookupService.java`
- [Account management](https://github.com/lcsalvess/banking-system/blob/master/src/main/java/com/lcsalvess/bankingsystem/service/account/AccountService.java): `src/main/java/com/lcsalvess/bankingsystem/service/account/AccountService.java`

### Transactions and operations

- [Financial operations](https://github.com/lcsalvess/banking-system/blob/master/src/main/java/com/lcsalvess/bankingsystem/service/transaction/TransactionService.java): `src/main/java/com/lcsalvess/bankingsystem/service/transaction/TransactionService.java`
- [Transaction queries](https://github.com/lcsalvess/banking-system/blob/master/src/main/java/com/lcsalvess/bankingsystem/service/transaction/query/TransactionQueryService.java): `src/main/java/com/lcsalvess/bankingsystem/service/transaction/query/TransactionQueryService.java`
- [Idempotency](https://github.com/lcsalvess/banking-system/blob/master/src/main/java/com/lcsalvess/bankingsystem/service/transaction/idempotency/TransactionIdempotencyService.java): `src/main/java/com/lcsalvess/bankingsystem/service/transaction/idempotency/TransactionIdempotencyService.java`
- [Daily yield](https://github.com/lcsalvess/banking-system/blob/master/src/main/java/com/lcsalvess/bankingsystem/service/transaction/yield/DailyYieldService.java): `src/main/java/com/lcsalvess/bankingsystem/service/transaction/yield/DailyYieldService.java`
- [Balance reconciliation](https://github.com/lcsalvess/banking-system/blob/master/src/main/java/com/lcsalvess/bankingsystem/service/transaction/balancereconciliation/BalanceReconciliationJob.java): `src/main/java/com/lcsalvess/bankingsystem/service/transaction/balancereconciliation/BalanceReconciliationJob.java`

### Audit trail

- [Audit recording](https://github.com/lcsalvess/banking-system/blob/master/src/main/java/com/lcsalvess/bankingsystem/service/audit/recording/AuditService.java): `src/main/java/com/lcsalvess/bankingsystem/service/audit/recording/AuditService.java`
- [Audit queries](https://github.com/lcsalvess/banking-system/blob/master/src/main/java/com/lcsalvess/bankingsystem/service/audit/query/AuditEventQueryService.java): `src/main/java/com/lcsalvess/bankingsystem/service/audit/query/AuditEventQueryService.java`
- [Query snapshots](https://github.com/lcsalvess/banking-system/blob/master/src/main/java/com/lcsalvess/bankingsystem/service/audit/query/snapshot/AuditEventQuerySnapshotService.java): `src/main/java/com/lcsalvess/bankingsystem/service/audit/query/snapshot/AuditEventQuerySnapshotService.java`

### Persistence and integrations

- **PostgreSQL**
- **ViaCEP**
- **BrasilAPI**

### Other components

- **API user**

## Connections

- API user → REST endpoints: sends requests
- REST endpoints → Authentication: handles login
- Authentication → Login protection: checks attempts (evidence: `src/main/java/com/lcsalvess/bankingsystem/service/security/AuthenticationService.java`)
- Authentication → JWT security: issues tokens (evidence: `src/main/java/com/lcsalvess/bankingsystem/service/security/AuthenticationService.java`)
- REST endpoints → User management: manages users
- REST endpoints → Client management: manages clients
- Client management → Address resolution: resolves postal codes (evidence: `src/main/java/com/lcsalvess/bankingsystem/service/client/ClientService.java`)
- Address resolution → Postal providers: looks up addresses (evidence: `src/main/java/com/lcsalvess/bankingsystem/service/address/AddressService.java`)
- Postal providers → ViaCEP: uses provider
- Postal providers → BrasilAPI: fallback provider
- REST endpoints → Account management: manages accounts
- REST endpoints → Financial operations: initiates operations
- Financial operations → Current user: gets actor (evidence: `src/main/java/com/lcsalvess/bankingsystem/service/transaction/TransactionService.java`)
- REST endpoints → Transaction queries: queries history
- Transaction queries → Account management: checks account (evidence: `src/main/java/com/lcsalvess/bankingsystem/service/transaction/query/TransactionQueryService.java`)
- Transaction queries → PostgreSQL: reads transactions (evidence: `src/main/java/com/lcsalvess/bankingsystem/service/transaction/query/TransactionQueryService.java`)
- Financial operations → Idempotency: guards retries (evidence: `src/main/java/com/lcsalvess/bankingsystem/service/transaction/idempotency/TransactionIdempotencyService.java`)
- Daily yield → PostgreSQL: records yield
- Balance reconciliation → PostgreSQL: checks balances
- REST endpoints → Audit queries: queries audit trail
- Audit queries → Query snapshots: pages snapshots (evidence: `src/main/java/com/lcsalvess/bankingsystem/service/audit/query/AuditEventQueryService.java`)
- Query snapshots → PostgreSQL: stores snapshot data (evidence: `src/main/java/com/lcsalvess/bankingsystem/service/audit/query/snapshot/AuditEventQuerySnapshotService.java`)
- Audit recording → PostgreSQL: records events
- Financial operations → PostgreSQL: persists operations