# soufianeamm/smartbank-app architecture

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

- Interactive diagram: https://gitdiagram.com/soufianeamm/smartbank-app
- Repository: https://github.com/soufianeamm/smartbank-app

## Overview

SmartBank is a pedagogical microservices banking demo, with an Angular client, Spring services, and shared Kafka events. The main workflow enters through the gateway and fans into customer, account, transfer, loan, transaction/statement, and notification capabilities; the README documents the broader service contracts, while excerpts provide implementation detail chiefly for customer management, frontend auth/routing, and notification consumption. Infrastructure and several domain services are represented at their exact tree directories where their internals were not sampled.

Main entry points: [`frontend/src/app/app.ts`](https://github.com/soufianeamm/smartbank-app/blob/main/frontend/src/app/app.ts) (Angular app), [`services/customer-service/src/main/java/com/smartbank/customer/service/CustomerService.java`](https://github.com/soufianeamm/smartbank-app/blob/main/services/customer-service/src/main/java/com/smartbank/customer/service/CustomerService.java) (Customer management), [`services/customer-service/src/main/java/com/smartbank/customer/web/CustomerController.java`](https://github.com/soufianeamm/smartbank-app/blob/main/services/customer-service/src/main/java/com/smartbank/customer/web/CustomerController.java) (Customer endpoints), [`infrastructure/api-gateway/src/main/java/com/smartbank/gateway`](https://github.com/soufianeamm/smartbank-app/tree/main/infrastructure/api-gateway/src/main/java/com/smartbank/gateway) (API gateway)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_angular["Angular app<br/>[app.ts]"]
  node_routing["Role routing<br/>[app.routes.ts]"]
  node_auth["Auth service<br/>[auth.service.ts]"]
  node_customer_api["Customer API client"]
end

subgraph group_edge["API and identity"]
  node_gateway["API gateway"]
  node_keycloak["Keycloak"]
end

subgraph group_domain["Banking services"]
  node_customer_controller["Customer endpoints"]
  node_customer_service["Customer management"]
  node_customer_db[("Customer repository")]
  node_account["Account service"]
  node_transfer["Transfer service"]
  node_loan["Loan service"]
  node_transaction["Transaction history"]
  node_statements["Monthly statements"]
end

subgraph group_messaging["Events and notifications"]
  node_event_contracts["Event contracts<br/>[Topics.java]"]
  node_kafka["Kafka"]
  node_notification["Notification listener"]
end

subgraph group_platform["Platform services"]
  node_discovery["Eureka discovery"]
  node_config["Config server"]
  node_postgres[("PostgreSQL")]
  node_mailpit["Mailpit SMTP"]
end

node_user(("Bank user"))

node_user -->|"uses"| node_angular
node_angular -->|"reads identity"| node_auth
node_angular -->|"renders routes"| node_routing
node_routing -->|"guards access"| node_auth
node_user -->|"authenticates"| node_keycloak
node_angular -->|"uses PKCE"| node_keycloak
node_customer_api -->|"calls API"| node_gateway
node_gateway -->|"routes requests"| node_customer_controller
node_customer_controller -->|"delegates to"| node_customer_service
node_customer_service -->|"reads and writes"| node_customer_db
node_customer_service -->|"publishes created"| node_kafka
node_customer_service -->|"uses topic"| node_event_contracts
node_account -->|"looks up customer"| node_customer_controller
node_transfer -->|"debits and credits"| node_account
node_transfer -->|"publishes outcomes"| node_kafka
node_loan -->|"publishes decisions"| node_kafka
node_transaction -->|"consumes completed"| node_kafka
node_transaction -->|"generates monthly"| node_statements
node_kafka -->|"delivers events"| node_notification
node_kafka -->|"delivers completed"| node_transaction
node_notification -->|"sends email"| node_mailpit
node_gateway -->|"discovers services"| node_discovery
node_customer_controller -->|"persists data"| node_postgres

click node_angular "https://github.com/soufianeamm/smartbank-app/blob/main/frontend/src/app/app.ts"
click node_routing "https://github.com/soufianeamm/smartbank-app/blob/main/frontend/src/app/app.routes.ts"
click node_auth "https://github.com/soufianeamm/smartbank-app/blob/main/frontend/src/app/core/auth/auth.service.ts"
click node_customer_api "https://github.com/soufianeamm/smartbank-app/blob/main/frontend/src/app/core/api/customer-api.service.ts"
click node_gateway "https://github.com/soufianeamm/smartbank-app/tree/main/infrastructure/api-gateway/src/main/java/com/smartbank/gateway"
click node_customer_controller "https://github.com/soufianeamm/smartbank-app/blob/main/services/customer-service/src/main/java/com/smartbank/customer/web/CustomerController.java"
click node_customer_service "https://github.com/soufianeamm/smartbank-app/blob/main/services/customer-service/src/main/java/com/smartbank/customer/service/CustomerService.java"
click node_customer_db "https://github.com/soufianeamm/smartbank-app/blob/main/services/customer-service/src/main/java/com/smartbank/customer/domain/CustomerRepository.java"
click node_account "https://github.com/soufianeamm/smartbank-app/tree/main/services/account-service"
click node_transfer "https://github.com/soufianeamm/smartbank-app/tree/main/services/transfer-service"
click node_loan "https://github.com/soufianeamm/smartbank-app/tree/main/services/loan-service"
click node_transaction "https://github.com/soufianeamm/smartbank-app/tree/main/services/transaction-service"
click node_statements "https://github.com/soufianeamm/smartbank-app/tree/main/services/transaction-service"
click node_event_contracts "https://github.com/soufianeamm/smartbank-app/blob/main/common/smartbank-common/src/main/java/com/smartbank/common/events/Topics.java"
click node_notification "https://github.com/soufianeamm/smartbank-app/blob/main/services/notification-service/src/main/java/com/smartbank/notification/listener/BankingEventsListener.java"
click node_discovery "https://github.com/soufianeamm/smartbank-app/blob/main/infrastructure/discovery-server/src/main/java/com/smartbank/discovery/DiscoveryServerApplication.java"
click node_config "https://github.com/soufianeamm/smartbank-app/blob/main/infrastructure/config-server/src/main/java/com/smartbank/configserver/ConfigServerApplication.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_angular,node_routing,node_auth,node_customer_api,node_user toneBlue
class node_gateway,node_keycloak toneAmber
class node_customer_controller,node_customer_service,node_customer_db,node_account,node_transfer,node_loan,node_transaction,node_statements toneMint
class node_event_contracts,node_kafka,node_notification toneRose
class node_discovery,node_config,node_postgres,node_mailpit toneIndigo
```

## Components

### Web client

- [Angular app](https://github.com/soufianeamm/smartbank-app/blob/main/frontend/src/app/app.ts): `frontend/src/app/app.ts`
- [Role routing](https://github.com/soufianeamm/smartbank-app/blob/main/frontend/src/app/app.routes.ts): `frontend/src/app/app.routes.ts`
- [Auth service](https://github.com/soufianeamm/smartbank-app/blob/main/frontend/src/app/core/auth/auth.service.ts): `frontend/src/app/core/auth/auth.service.ts`
- [Customer API client](https://github.com/soufianeamm/smartbank-app/blob/main/frontend/src/app/core/api/customer-api.service.ts): `frontend/src/app/core/api/customer-api.service.ts`

### API and identity

- [API gateway](https://github.com/soufianeamm/smartbank-app/tree/main/infrastructure/api-gateway/src/main/java/com/smartbank/gateway): `infrastructure/api-gateway/src/main/java/com/smartbank/gateway`
- **Keycloak**

### Banking services

- [Customer endpoints](https://github.com/soufianeamm/smartbank-app/blob/main/services/customer-service/src/main/java/com/smartbank/customer/web/CustomerController.java): `services/customer-service/src/main/java/com/smartbank/customer/web/CustomerController.java`
- [Customer management](https://github.com/soufianeamm/smartbank-app/blob/main/services/customer-service/src/main/java/com/smartbank/customer/service/CustomerService.java): `services/customer-service/src/main/java/com/smartbank/customer/service/CustomerService.java`
- [Customer repository](https://github.com/soufianeamm/smartbank-app/blob/main/services/customer-service/src/main/java/com/smartbank/customer/domain/CustomerRepository.java): `services/customer-service/src/main/java/com/smartbank/customer/domain/CustomerRepository.java`
- [Account service](https://github.com/soufianeamm/smartbank-app/tree/main/services/account-service): `services/account-service`
- [Transfer service](https://github.com/soufianeamm/smartbank-app/tree/main/services/transfer-service): `services/transfer-service`
- [Loan service](https://github.com/soufianeamm/smartbank-app/tree/main/services/loan-service): `services/loan-service`
- [Transaction history](https://github.com/soufianeamm/smartbank-app/tree/main/services/transaction-service): `services/transaction-service`
- [Monthly statements](https://github.com/soufianeamm/smartbank-app/tree/main/services/transaction-service): `services/transaction-service`

### Events and notifications

- [Event contracts](https://github.com/soufianeamm/smartbank-app/blob/main/common/smartbank-common/src/main/java/com/smartbank/common/events/Topics.java): `common/smartbank-common/src/main/java/com/smartbank/common/events/Topics.java`
- **Kafka**
- [Notification listener](https://github.com/soufianeamm/smartbank-app/blob/main/services/notification-service/src/main/java/com/smartbank/notification/listener/BankingEventsListener.java): `services/notification-service/src/main/java/com/smartbank/notification/listener/BankingEventsListener.java`

### Platform services

- [Eureka discovery](https://github.com/soufianeamm/smartbank-app/blob/main/infrastructure/discovery-server/src/main/java/com/smartbank/discovery/DiscoveryServerApplication.java): `infrastructure/discovery-server/src/main/java/com/smartbank/discovery/DiscoveryServerApplication.java`
- [Config server](https://github.com/soufianeamm/smartbank-app/blob/main/infrastructure/config-server/src/main/java/com/smartbank/configserver/ConfigServerApplication.java): `infrastructure/config-server/src/main/java/com/smartbank/configserver/ConfigServerApplication.java`
- **PostgreSQL**
- **Mailpit SMTP**

### Other components

- **Bank user**

## Connections

- Bank user → Angular app: uses
- Angular app → Auth service: reads identity (evidence: `frontend/src/app/app.ts`)
- Angular app → Role routing: renders routes (evidence: `frontend/src/app/app.routes.ts`)
- Role routing → Auth service: guards access (evidence: `frontend/src/app/app.routes.ts`)
- Bank user → Keycloak: authenticates
- Angular app → Keycloak: uses PKCE
- Customer API client → API gateway: calls API
- API gateway → Customer endpoints: routes requests
- Customer endpoints → Customer management: delegates to (evidence: `services/customer-service/src/main/java/com/smartbank/customer/web/CustomerController.java`)
- Customer management → Customer repository: reads and writes (evidence: `services/customer-service/src/main/java/com/smartbank/customer/service/CustomerService.java`)
- Customer management → Kafka: publishes created (evidence: `services/customer-service/src/main/java/com/smartbank/customer/service/CustomerService.java`)
- Customer management → Event contracts: uses topic (evidence: `services/customer-service/src/main/java/com/smartbank/customer/service/CustomerService.java`)
- Account service → Customer endpoints: looks up customer (evidence: `services/account-service/src/main/java/com/smartbank/account/client/CustomerLookupService.java`)
- Transfer service → Account service: debits and credits
- Transfer service → Kafka: publishes outcomes
- Loan service → Kafka: publishes decisions
- Transaction history → Kafka: consumes completed
- Transaction history → Monthly statements: generates monthly
- Kafka → Notification listener: delivers events
- Kafka → Transaction history: delivers completed
- Notification listener → Mailpit SMTP: sends email
- API gateway → Eureka discovery: discovers services
- Customer endpoints → PostgreSQL: persists data