# ingmarma/fincore architecture

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

- Interactive diagram: https://gitdiagram.com/ingmarma/fincore
- Repository: https://github.com/ingmarma/fincore

## Overview

FinCore is a four-microservice digital wallet and payment backend. Its main request path enters through the API Gateway, reaches payment processing or account operations, and returns a service response; completed payments also emit Kafka events consumed by account and notification services. Account operations separately support event-sourced balances, three read-consistency levels, DEBIN, and compensation. The README documents service routing and infrastructure capabilities; sampled source confirms selected internal calls. Some wiring, including gateway route configuration and unsampled service details, is represented only where documented.

Main entry points: [`api-gateway/src/main/java/com/ingmarma/fincore/gateway/GatewayApplication.java`](https://github.com/ingmarma/fincore/blob/main/api-gateway/src/main/java/com/ingmarma/fincore/gateway/GatewayApplication.java) (API Gateway), [`account-service/src/main/java/com/ingmarma/fincore/account/application/AccountCommandService.java`](https://github.com/ingmarma/fincore/blob/main/account-service/src/main/java/com/ingmarma/fincore/account/application/AccountCommandService.java) (Account commands), [`payment-service/src/main/java/com/ingmarma/fincore/payment/application/PaymentService.java`](https://github.com/ingmarma/fincore/blob/main/payment-service/src/main/java/com/ingmarma/fincore/payment/application/PaymentService.java) (Payment processing), [`account-service/src/main/java/com/ingmarma/fincore/account/application/AccountQueryService.java`](https://github.com/ingmarma/fincore/blob/main/account-service/src/main/java/com/ingmarma/fincore/account/application/AccountQueryService.java) (Balance and history)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["API entry"]
  node_gateway["API Gateway"]
  node_gateway_resilience["Gateway resilience"]
end

subgraph group_payments["Payment processing"]
  node_payment_api["Payment endpoint"]
  node_payment_logic["Payment processing"]
  node_payment_store[("Payment records")]
  node_payment_events["Payment event publisher"]
end

subgraph group_accounts["Account ledger"]
  node_account_api["Account endpoints"]
  node_account_commands["Account commands"]
  node_account_queries["Balance and history"]
  node_account_store[("Account snapshots")]
  node_ledger_events[("Ledger events")]
  node_debin_dedup[("DEBIN deduplication")]
  node_account_consumer["Payment event consumer"]
end

subgraph group_notifications["Events and notifications"]
  node_notification_consumer["Payment event consumer"]
  node_notification_logic["Notification delivery"]
  node_notification_api["Notification API"]
end

subgraph group_platform["Shared infrastructure"]
  node_redis[("Redis")]
  node_kafka["Kafka"]
  node_postgres[("PostgreSQL")]
  node_monitoring["Prometheus and Grafana<br/>[prometheus.yml]"]
end

node_client(("API client"))

node_client -->|"sends requests"| node_gateway
node_gateway -->|"routes requests"| node_payment_api
node_gateway -->|"routes requests"| node_account_api
node_gateway -->|"routes requests"| node_notification_api
node_gateway -->|"falls back"| node_gateway_resilience
node_payment_api -->|"invokes"| node_payment_logic
node_payment_logic -->|"persists payment"| node_payment_store
node_payment_logic -->|"checks idempotency"| node_redis
node_payment_logic -->|"publishes completion"| node_payment_events
node_payment_events -->|"publishes event"| node_kafka
node_account_api -->|"invokes commands"| node_account_commands
node_account_api -->|"invokes queries"| node_account_queries
node_account_commands -->|"locks and updates"| node_account_store
node_account_commands -->|"records events"| node_ledger_events
node_account_commands -->|"checks duplicates"| node_debin_dedup
node_account_commands -->|"updates balance cache"| node_redis
node_account_queries -->|"reads balance cache"| node_redis
node_account_queries -->|"reads snapshots"| node_account_store
node_account_queries -->|"aggregates history"| node_ledger_events
node_kafka -->|"delivers payment events"| node_account_consumer
node_kafka -->|"delivers payment events"| node_notification_consumer
node_account_consumer -->|"updates accounts"| node_account_store
node_account_consumer -->|"records event"| node_ledger_events
node_notification_consumer -->|"requests delivery"| node_notification_logic
node_notification_api -->|"reads notifications"| node_notification_logic
node_postgres -.->|"stores snapshots"| node_account_store
node_postgres -.->|"stores ledger"| node_ledger_events
node_postgres -.->|"stores payments"| node_payment_store
node_monitoring -.->|"observes metrics"| node_gateway

click node_gateway "https://github.com/ingmarma/fincore/blob/main/api-gateway/src/main/java/com/ingmarma/fincore/gateway/GatewayApplication.java"
click node_gateway_resilience "https://github.com/ingmarma/fincore/blob/main/api-gateway/src/main/java/com/ingmarma/fincore/gateway/FallbackController.java"
click node_payment_api "https://github.com/ingmarma/fincore/blob/main/payment-service/src/main/java/com/ingmarma/fincore/payment/infrastructure/PaymentController.java"
click node_payment_logic "https://github.com/ingmarma/fincore/blob/main/payment-service/src/main/java/com/ingmarma/fincore/payment/application/PaymentService.java"
click node_payment_store "https://github.com/ingmarma/fincore/blob/main/payment-service/src/main/java/com/ingmarma/fincore/payment/domain/PaymentRepository.java"
click node_payment_events "https://github.com/ingmarma/fincore/blob/main/payment-service/src/main/java/com/ingmarma/fincore/payment/infrastructure/PaymentEventPublisher.java"
click node_account_api "https://github.com/ingmarma/fincore/blob/main/account-service/src/main/java/com/ingmarma/fincore/account/infrastructure/AccountController.java"
click node_account_commands "https://github.com/ingmarma/fincore/blob/main/account-service/src/main/java/com/ingmarma/fincore/account/application/AccountCommandService.java"
click node_account_queries "https://github.com/ingmarma/fincore/blob/main/account-service/src/main/java/com/ingmarma/fincore/account/application/AccountQueryService.java"
click node_account_store "https://github.com/ingmarma/fincore/blob/main/account-service/src/main/java/com/ingmarma/fincore/account/domain/AccountRepository.java"
click node_ledger_events "https://github.com/ingmarma/fincore/blob/main/account-service/src/main/java/com/ingmarma/fincore/account/domain/AccountEventRepository.java"
click node_account_consumer "https://github.com/ingmarma/fincore/blob/main/account-service/src/main/java/com/ingmarma/fincore/account/infrastructure/PaymentEventConsumer.java"
click node_notification_consumer "https://github.com/ingmarma/fincore/blob/main/notification-service/src/main/java/com/ingmarma/fincore/notification/PaymentEventConsumer.java"
click node_notification_logic "https://github.com/ingmarma/fincore/blob/main/notification-service/src/main/java/com/ingmarma/fincore/notification/NotificationService.java"
click node_notification_api "https://github.com/ingmarma/fincore/blob/main/notification-service/src/main/java/com/ingmarma/fincore/notification/NotificationController.java"
click node_monitoring "https://github.com/ingmarma/fincore/blob/main/infra/prometheus.yml"

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_gateway,node_gateway_resilience,node_client toneBlue
class node_payment_api,node_payment_logic,node_payment_store,node_payment_events toneAmber
class node_account_api,node_account_commands,node_account_queries,node_account_store,node_ledger_events,node_debin_dedup,node_account_consumer toneMint
class node_notification_consumer,node_notification_logic,node_notification_api toneRose
class node_redis,node_kafka,node_postgres,node_monitoring toneIndigo
```

## Components

### API entry

- [API Gateway](https://github.com/ingmarma/fincore/blob/main/api-gateway/src/main/java/com/ingmarma/fincore/gateway/GatewayApplication.java): `api-gateway/src/main/java/com/ingmarma/fincore/gateway/GatewayApplication.java`
- [Gateway resilience](https://github.com/ingmarma/fincore/blob/main/api-gateway/src/main/java/com/ingmarma/fincore/gateway/FallbackController.java): `api-gateway/src/main/java/com/ingmarma/fincore/gateway/FallbackController.java`

### Payment processing

- [Payment endpoint](https://github.com/ingmarma/fincore/blob/main/payment-service/src/main/java/com/ingmarma/fincore/payment/infrastructure/PaymentController.java): `payment-service/src/main/java/com/ingmarma/fincore/payment/infrastructure/PaymentController.java`
- [Payment processing](https://github.com/ingmarma/fincore/blob/main/payment-service/src/main/java/com/ingmarma/fincore/payment/application/PaymentService.java): `payment-service/src/main/java/com/ingmarma/fincore/payment/application/PaymentService.java`
- [Payment records](https://github.com/ingmarma/fincore/blob/main/payment-service/src/main/java/com/ingmarma/fincore/payment/domain/PaymentRepository.java): `payment-service/src/main/java/com/ingmarma/fincore/payment/domain/PaymentRepository.java`
- [Payment event publisher](https://github.com/ingmarma/fincore/blob/main/payment-service/src/main/java/com/ingmarma/fincore/payment/infrastructure/PaymentEventPublisher.java): `payment-service/src/main/java/com/ingmarma/fincore/payment/infrastructure/PaymentEventPublisher.java`

### Account ledger

- [Account endpoints](https://github.com/ingmarma/fincore/blob/main/account-service/src/main/java/com/ingmarma/fincore/account/infrastructure/AccountController.java): `account-service/src/main/java/com/ingmarma/fincore/account/infrastructure/AccountController.java`
- [Account commands](https://github.com/ingmarma/fincore/blob/main/account-service/src/main/java/com/ingmarma/fincore/account/application/AccountCommandService.java): `account-service/src/main/java/com/ingmarma/fincore/account/application/AccountCommandService.java`
- [Balance and history](https://github.com/ingmarma/fincore/blob/main/account-service/src/main/java/com/ingmarma/fincore/account/application/AccountQueryService.java): `account-service/src/main/java/com/ingmarma/fincore/account/application/AccountQueryService.java`
- [Account snapshots](https://github.com/ingmarma/fincore/blob/main/account-service/src/main/java/com/ingmarma/fincore/account/domain/AccountRepository.java): `account-service/src/main/java/com/ingmarma/fincore/account/domain/AccountRepository.java`
- [Ledger events](https://github.com/ingmarma/fincore/blob/main/account-service/src/main/java/com/ingmarma/fincore/account/domain/AccountEventRepository.java): `account-service/src/main/java/com/ingmarma/fincore/account/domain/AccountEventRepository.java`
- **DEBIN deduplication**
- [Payment event consumer](https://github.com/ingmarma/fincore/blob/main/account-service/src/main/java/com/ingmarma/fincore/account/infrastructure/PaymentEventConsumer.java): `account-service/src/main/java/com/ingmarma/fincore/account/infrastructure/PaymentEventConsumer.java`

### Events and notifications

- [Payment event consumer](https://github.com/ingmarma/fincore/blob/main/notification-service/src/main/java/com/ingmarma/fincore/notification/PaymentEventConsumer.java): `notification-service/src/main/java/com/ingmarma/fincore/notification/PaymentEventConsumer.java`
- [Notification delivery](https://github.com/ingmarma/fincore/blob/main/notification-service/src/main/java/com/ingmarma/fincore/notification/NotificationService.java): `notification-service/src/main/java/com/ingmarma/fincore/notification/NotificationService.java`
- [Notification API](https://github.com/ingmarma/fincore/blob/main/notification-service/src/main/java/com/ingmarma/fincore/notification/NotificationController.java): `notification-service/src/main/java/com/ingmarma/fincore/notification/NotificationController.java`

### Shared infrastructure

- **Redis**
- **Kafka**
- **PostgreSQL**
- [Prometheus and Grafana](https://github.com/ingmarma/fincore/blob/main/infra/prometheus.yml): `infra/prometheus.yml`

### Other components

- **API client**

## Connections

- API client → API Gateway: sends requests (evidence: `README.md`)
- API Gateway → Payment endpoint: routes requests (evidence: `README.md`)
- API Gateway → Account endpoints: routes requests (evidence: `README.md`)
- API Gateway → Notification API: routes requests (evidence: `README.md`)
- API Gateway → Gateway resilience: falls back (evidence: `README.md`)
- Payment endpoint → Payment processing: invokes (evidence: `payment-service/src/main/java/com/ingmarma/fincore/payment/infrastructure/PaymentController.java`)
- Payment processing → Payment records: persists payment (evidence: `payment-service/src/main/java/com/ingmarma/fincore/payment/application/PaymentService.java`)
- Payment processing → Redis: checks idempotency (evidence: `payment-service/src/main/java/com/ingmarma/fincore/payment/application/PaymentService.java`)
- Payment processing → Payment event publisher: publishes completion (evidence: `payment-service/src/main/java/com/ingmarma/fincore/payment/application/PaymentService.java`)
- Payment event publisher → Kafka: publishes event (evidence: `README.md`)
- Account endpoints → Account commands: invokes commands (evidence: `account-service/src/main/java/com/ingmarma/fincore/account/infrastructure/AccountController.java`)
- Account endpoints → Balance and history: invokes queries (evidence: `account-service/src/main/java/com/ingmarma/fincore/account/infrastructure/AccountController.java`)
- Account commands → Account snapshots: locks and updates (evidence: `account-service/src/main/java/com/ingmarma/fincore/account/application/AccountCommandService.java`)
- Account commands → Ledger events: records events (evidence: `account-service/src/main/java/com/ingmarma/fincore/account/application/AccountCommandService.java`)
- Account commands → DEBIN deduplication: checks duplicates (evidence: `account-service/src/main/java/com/ingmarma/fincore/account/application/AccountCommandService.java`)
- Account commands → Redis: updates balance cache (evidence: `account-service/src/main/java/com/ingmarma/fincore/account/application/AccountCommandService.java`)
- Balance and history → Redis: reads balance cache (evidence: `account-service/src/main/java/com/ingmarma/fincore/account/application/AccountQueryService.java`)
- Balance and history → Account snapshots: reads snapshots (evidence: `account-service/src/main/java/com/ingmarma/fincore/account/application/AccountQueryService.java`)
- Balance and history → Ledger events: aggregates history (evidence: `account-service/src/main/java/com/ingmarma/fincore/account/application/AccountQueryService.java`)
- Kafka → Payment event consumer: delivers payment events (evidence: `README.md`)
- Kafka → Payment event consumer: delivers payment events (evidence: `README.md`)
- Payment event consumer → Account snapshots: updates accounts (evidence: `account-service/src/main/java/com/ingmarma/fincore/account/infrastructure/PaymentEventConsumer.java`)
- Payment event consumer → Ledger events: records event (evidence: `account-service/src/main/java/com/ingmarma/fincore/account/infrastructure/PaymentEventConsumer.java`)
- Payment event consumer → Notification delivery: requests delivery (evidence: `notification-service/src/main/java/com/ingmarma/fincore/notification/PaymentEventConsumer.java`)
- Notification API → Notification delivery: reads notifications (evidence: `notification-service/src/main/java/com/ingmarma/fincore/notification/NotificationController.java`)
- PostgreSQL → Account snapshots: stores snapshots (evidence: `README.md`)
- PostgreSQL → Ledger events: stores ledger (evidence: `README.md`)
- PostgreSQL → Payment records: stores payments (evidence: `README.md`)
- Prometheus and Grafana → API Gateway: observes metrics (evidence: `README.md`)
