# bakhyzh/esep-api architecture

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

- Interactive diagram: https://gitdiagram.com/bakhyzh/esep-api
- Repository: https://github.com/bakhyzh/esep-api

## Overview

Esep API is a wallet and money-transfer platform built around a double-entry ledger, with authentication, account management, transaction history, spending analytics, and transfer notifications. The main workflow is a user signing in, opening an account, and making a transfer or deposit; ledger postings persist the balanced transaction, while an outbox supports Kafka notifications. Analytics also has a separately listed service implementation. The graph uses README workflow and capability statements plus the supplied source excerpts and index; unsampled service wiring is not assumed.

Main entry points: [`services/api-gateway/src/main/java/com/esep/gateway/ApiGatewayApplication.java`](https://github.com/bakhyzh/esep-api/blob/main/services/api-gateway/src/main/java/com/esep/gateway/ApiGatewayApplication.java) (API gateway), [`src/main/java/com/esep/auth/AuthService.java`](https://github.com/bakhyzh/esep-api/blob/main/src/main/java/com/esep/auth/AuthService.java) (Authentication), [`services/ledger-service/src/main/java/com/esep/transaction/TransactionProcessor.java`](https://github.com/bakhyzh/esep-api/blob/main/services/ledger-service/src/main/java/com/esep/transaction/TransactionProcessor.java) (Ledger processing), [`services/analytics-service/src/main/java/com/esep/analytics/AnalyticsService.java`](https://github.com/bakhyzh/esep-api/blob/main/services/analytics-service/src/main/java/com/esep/analytics/AnalyticsService.java) (Spending analytics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Identity and access"]
  node_auth["Authentication<br/>[AuthService.java]"]
  node_tokens["JWT issuance<br/>[TokenService.java]"]
  node_identity[("User identity<br/>[User.java]")]
end

subgraph group_ledger["Ledger operations"]
  node_accounts["Account management"]
  node_transactions["Transaction entry"]
  node_processor["Ledger processing"]
  node_ledgerdb[("Ledger database")]
  node_history["Operation history"]
  node_facts["Ledger facts"]
end

subgraph group_events["Events and notifications"]
  node_outbox[("Transactional outbox")]
  node_kafka["Kafka"]
  node_notifications["Notifications"]
end

subgraph group_insights["Analytics and reporting"]
  node_analytics["Spending analytics"]
  node_analyticstore[("Analytics projection")]
  node_cache[("Report cache")]
end

subgraph group_platform["Service platform"]
  node_gateway["API gateway"]
  node_ledger_svc["Ledger service"]
  node_analytics_svc["Analytics service"]
  node_notification_svc["Notification service"]
end

node_user(("Wallet user"))
node_admin(("Administrator"))

node_user -->|"signs in"| node_auth
node_admin -->|"signs in"| node_auth
node_auth -->|"reads and saves"| node_identity
node_auth -->|"issues token"| node_tokens
node_user -->|"opens account"| node_accounts
node_accounts -->|"checks owner"| node_identity
node_user -->|"requests transfer"| node_transactions
node_admin -->|"requests deposit"| node_transactions
node_transactions -->|"delegates"| node_processor
node_processor -.->|"posts transaction"| node_ledgerdb
node_user -.->|"requests history"| node_history
node_processor -.->|"writes event"| node_outbox
node_outbox -.->|"publishes events"| node_kafka
node_kafka -.->|"delivers events"| node_notifications
node_user -->|"requests report"| node_analytics
node_analytics -.->|"queries projection"| node_analyticstore
node_analytics -->|"uses report cache"| node_cache
node_user -.->|"sends API request"| node_gateway
node_gateway -.->|"routes requests"| node_ledger_svc
node_gateway -.->|"routes requests"| node_analytics_svc
node_gateway -.->|"routes requests"| node_notification_svc

click node_auth "https://github.com/bakhyzh/esep-api/blob/main/src/main/java/com/esep/auth/AuthService.java"
click node_tokens "https://github.com/bakhyzh/esep-api/blob/main/src/main/java/com/esep/security/TokenService.java"
click node_identity "https://github.com/bakhyzh/esep-api/blob/main/src/main/java/com/esep/user/User.java"
click node_accounts "https://github.com/bakhyzh/esep-api/blob/main/src/main/java/com/esep/account/AccountService.java"
click node_transactions "https://github.com/bakhyzh/esep-api/blob/main/services/ledger-service/src/main/java/com/esep/transaction/TransactionService.java"
click node_processor "https://github.com/bakhyzh/esep-api/blob/main/services/ledger-service/src/main/java/com/esep/transaction/TransactionProcessor.java"
click node_ledgerdb "https://github.com/bakhyzh/esep-api/blob/main/src/main/java/com/esep/transaction/LedgerTransactionRepository.java"
click node_history "https://github.com/bakhyzh/esep-api/blob/main/services/ledger-service/src/main/java/com/esep/transaction/OperationHistoryService.java"
click node_facts "https://github.com/bakhyzh/esep-api/blob/main/services/ledger-service/src/main/java/com/esep/facts/LedgerFactWriter.java"
click node_outbox "https://github.com/bakhyzh/esep-api/blob/main/src/main/java/com/esep/outbox/TransferEventWriter.java"
click node_notifications "https://github.com/bakhyzh/esep-api/blob/main/src/main/java/com/esep/notification/NotificationService.java"
click node_analytics "https://github.com/bakhyzh/esep-api/blob/main/services/analytics-service/src/main/java/com/esep/analytics/AnalyticsService.java"
click node_analyticstore "https://github.com/bakhyzh/esep-api/blob/main/services/analytics-service/src/main/java/com/esep/projection/AnalyticsProjection.java"
click node_cache "https://github.com/bakhyzh/esep-api/blob/main/src/main/java/com/esep/analytics/AnalyticsCache.java"
click node_gateway "https://github.com/bakhyzh/esep-api/blob/main/services/api-gateway/src/main/java/com/esep/gateway/ApiGatewayApplication.java"
click node_ledger_svc "https://github.com/bakhyzh/esep-api/blob/main/services/ledger-service/src/main/java/com/esep/LedgerServiceApplication.java"
click node_analytics_svc "https://github.com/bakhyzh/esep-api/blob/main/services/analytics-service/src/main/java/com/esep/AnalyticsServiceApplication.java"
click node_notification_svc "https://github.com/bakhyzh/esep-api/blob/main/services/notification-service/src/main/java/com/esep/NotificationServiceApplication.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_auth,node_tokens,node_identity,node_user toneBlue
class node_accounts,node_transactions,node_processor,node_ledgerdb,node_history,node_facts toneAmber
class node_outbox,node_kafka,node_notifications toneMint
class node_analytics,node_analyticstore,node_cache toneRose
class node_gateway,node_ledger_svc,node_analytics_svc,node_notification_svc,node_admin toneIndigo
```

## Components

### Identity and access

- [Authentication](https://github.com/bakhyzh/esep-api/blob/main/src/main/java/com/esep/auth/AuthService.java): `src/main/java/com/esep/auth/AuthService.java`
- [JWT issuance](https://github.com/bakhyzh/esep-api/blob/main/src/main/java/com/esep/security/TokenService.java): `src/main/java/com/esep/security/TokenService.java`
- [User identity](https://github.com/bakhyzh/esep-api/blob/main/src/main/java/com/esep/user/User.java): `src/main/java/com/esep/user/User.java`

### Ledger operations

- [Account management](https://github.com/bakhyzh/esep-api/blob/main/src/main/java/com/esep/account/AccountService.java): `src/main/java/com/esep/account/AccountService.java`
- [Transaction entry](https://github.com/bakhyzh/esep-api/blob/main/services/ledger-service/src/main/java/com/esep/transaction/TransactionService.java): `services/ledger-service/src/main/java/com/esep/transaction/TransactionService.java`
- [Ledger processing](https://github.com/bakhyzh/esep-api/blob/main/services/ledger-service/src/main/java/com/esep/transaction/TransactionProcessor.java): `services/ledger-service/src/main/java/com/esep/transaction/TransactionProcessor.java`
- [Ledger database](https://github.com/bakhyzh/esep-api/blob/main/src/main/java/com/esep/transaction/LedgerTransactionRepository.java): `src/main/java/com/esep/transaction/LedgerTransactionRepository.java`
- [Operation history](https://github.com/bakhyzh/esep-api/blob/main/services/ledger-service/src/main/java/com/esep/transaction/OperationHistoryService.java): `services/ledger-service/src/main/java/com/esep/transaction/OperationHistoryService.java`
- [Ledger facts](https://github.com/bakhyzh/esep-api/blob/main/services/ledger-service/src/main/java/com/esep/facts/LedgerFactWriter.java): `services/ledger-service/src/main/java/com/esep/facts/LedgerFactWriter.java`

### Events and notifications

- [Transactional outbox](https://github.com/bakhyzh/esep-api/blob/main/src/main/java/com/esep/outbox/TransferEventWriter.java): `src/main/java/com/esep/outbox/TransferEventWriter.java`
- **Kafka**
- [Notifications](https://github.com/bakhyzh/esep-api/blob/main/src/main/java/com/esep/notification/NotificationService.java): `src/main/java/com/esep/notification/NotificationService.java`

### Analytics and reporting

- [Spending analytics](https://github.com/bakhyzh/esep-api/blob/main/services/analytics-service/src/main/java/com/esep/analytics/AnalyticsService.java): `services/analytics-service/src/main/java/com/esep/analytics/AnalyticsService.java`
- [Analytics projection](https://github.com/bakhyzh/esep-api/blob/main/services/analytics-service/src/main/java/com/esep/projection/AnalyticsProjection.java): `services/analytics-service/src/main/java/com/esep/projection/AnalyticsProjection.java`
- [Report cache](https://github.com/bakhyzh/esep-api/blob/main/src/main/java/com/esep/analytics/AnalyticsCache.java): `src/main/java/com/esep/analytics/AnalyticsCache.java`

### Service platform

- [API gateway](https://github.com/bakhyzh/esep-api/blob/main/services/api-gateway/src/main/java/com/esep/gateway/ApiGatewayApplication.java): `services/api-gateway/src/main/java/com/esep/gateway/ApiGatewayApplication.java`
- [Ledger service](https://github.com/bakhyzh/esep-api/blob/main/services/ledger-service/src/main/java/com/esep/LedgerServiceApplication.java): `services/ledger-service/src/main/java/com/esep/LedgerServiceApplication.java`
- [Analytics service](https://github.com/bakhyzh/esep-api/blob/main/services/analytics-service/src/main/java/com/esep/AnalyticsServiceApplication.java): `services/analytics-service/src/main/java/com/esep/AnalyticsServiceApplication.java`
- [Notification service](https://github.com/bakhyzh/esep-api/blob/main/services/notification-service/src/main/java/com/esep/NotificationServiceApplication.java): `services/notification-service/src/main/java/com/esep/NotificationServiceApplication.java`

### Other components

- **Wallet user**
- **Administrator**

## Connections

- Wallet user → Authentication: signs in (evidence: `README.md`)
- Administrator → Authentication: signs in (evidence: `README.md`)
- Authentication → User identity: reads and saves (evidence: `src/main/java/com/esep/auth/AuthService.java`)
- Authentication → JWT issuance: issues token (evidence: `src/main/java/com/esep/auth/AuthService.java`)
- Wallet user → Account management: opens account (evidence: `README.md`)
- Account management → User identity: checks owner (evidence: `src/main/java/com/esep/account/AccountService.java`)
- Wallet user → Transaction entry: requests transfer (evidence: `README.md`)
- Administrator → Transaction entry: requests deposit (evidence: `README.md`)
- Transaction entry → Ledger processing: delegates (evidence: `services/ledger-service/src/main/java/com/esep/transaction/TransactionService.java`)
- Ledger processing → Ledger database: posts transaction
- Wallet user → Operation history: requests history
- Ledger processing → Transactional outbox: writes event
- Transactional outbox → Kafka: publishes events
- Kafka → Notifications: delivers events
- Wallet user → Spending analytics: requests report (evidence: `README.md`)
- Spending analytics → Analytics projection: queries projection
- Spending analytics → Report cache: uses report cache (evidence: `README.md`)
- Wallet user → API gateway: sends API request
- API gateway → Ledger service: routes requests
- API gateway → Analytics service: routes requests
- API gateway → Notification service: routes requests