# albertobas/bank-microservices architecture

> Architecture diagram of the GitHub repository albertobas/bank-microservices, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/albertobas/bank-microservices
- Repository: https://github.com/albertobas/bank-microservices

## Overview

##### Project’s Type and Purpose
- The project is a full-scale bank application that uses a microservices architecture.
- Its purpose is to manage banking operations like creating, updating, and deleting accounts, customers, and loans; integrating on-chain data via smart contracts; running predictive analytics on loan defaults; and exposing data via APIs and GraphQL.
- As stated in the README, it leverages multiple technologies (MERN stack for front-end, Express.js and Flask for back-end, Solidity smart contracts, ML pipelines with scikit-learn, and TheGraph for blockchain data querying). This ensures you capture both traditional web service components as well as blockchain and machine learning components.

##### File Structure for Architectural Components
- The top-level directories include:
- packages/: Contains shared npm packages (utilities, logger, ESLint configs, and common TypeScript configurations) used across various microservices.
- services/: Contains the microservices. Several distinct services are evident:
▸ services/accounts: Contains Express API logic (controllers, interactors, repositories), Docker configuration, and Mongo initialization scripts.
▸ services/requests: Defines operations for handling requests.
▸ services/client: Contains the front-end Next.js application, including UI components and feature-specific code.
▸ Other supporting services (like graph-node and loans-model) add components such as a local GraphQL node and Python-powered loan prediction models.
- Each microservice typically follows a hexagonal architecture:
- Controllers (API entry points) forward requests to business logic (interactors/core) which interfaces with data sources (repositories, data-sources) to read or write information.
- Infrastructure components like Docker configuration files (Dockerfile, docker-compose.yaml) and environment templates indicate containerized deployment.

a. Main Components:
- Front-end Application: The Next.js based client found under services/client.
- Back-end Microservices: Separate services for accounts, customers, loans, and requests. Each service has API controllers, core interactors, and repository/data-source layers.
- Shared Packages: Common libraries (bank-utils, logger, custom ESLint configurations, tsconfigs) that are used across services.
- ML & Prediction Component: The loans-model service which includes Python components, Jupyter notebooks, and ML pipelines (integrating scikit-learn and PyTorch).
- Infrastructure & Orchestration: Docker Compose definitions, Dockerfiles for each service, and environment configuration files.
- Data Storage and Query Services: MongoDB (for persistent data storage), and TheGraph/graph-node for querying chain data.

b. Relationships and Interactions:
- The front-end interacts with back-end services via RESTful APIs (and possibly GraphQL for chain querying).
- Each microservice encapsulates its own domain (accounts, customers, loans, requests), with defined interactions:
- API Controllers feed into interactors (hexagonal architecture) which in turn interact with repositories.
- Data sources for MongoDB are invoked at the repository level.
- The loans-model service acts as a backend analytics engine that interfaces with loan data and potentially sends predictions to the user interface.

c. Important Architectural Patterns:
- Microservices Architecture: Each service is containerized and communicates over defined API boundaries.
- Hexagonal Architecture: Separation between the core business logic (interactors) and the infrastructure (controllers, repositories).
- Separation of Concerns: Front-end, back-end, smart contracts, and machine learning components are clearly separated.
- CI/CD Integration: Presence of linting (eslint, prettier), commit hooks (husky), and automated deployment signals a disciplined development pipeline.

d. Relevant Technologies:
- Front-end: Next.js, React, TypeScript.
- Back-end: Express.js (TypeScript), Flask (Python), RESTful APIs.
- Data Storage: MongoDB.
- ML: scikit-learn, PyTorch, Skorch.
- Infrastructure: Docker (Docker Compose), pnpm-managed workspace.

##### Elements

- Drill down into each microservice if needed, showing internal separations (API controllers, interactors, repositories).
- Infrastructure elements such as Docker Compose orchestration and shared configuration under packages.
- Major components from the file tree and mentioned in the README are represented and their interactions depicted.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        Client["Client (Next.js)"]:::frontend
    end

    %% Microservices Layer
    subgraph "Microservices Layer"
        %% Accounts Service Subgraph
        subgraph "Accounts Service"
            A_Controller["API Controller"]:::microservice
            A_Interactor["Business Logic"]:::microservice
            A_Repository["Repository/Data Source"]:::microservice
            A_Controller -->|"calls"| A_Interactor
            A_Interactor -->|"accesses"| A_Repository
        end
        
        %% Customers Service Subgraph
        subgraph "Customers Service"
            C_Controller["API Controller"]:::microservice
            C_Interactor["Business Logic"]:::microservice
            C_Repository["Repository/Data Source"]:::microservice
            C_Controller -->|"calls"| C_Interactor
            C_Interactor -->|"accesses"| C_Repository
            C_Contracts["Smart Contracts"]:::blockchain
            C_Subgraph["Subgraph Service"]:::blockchain
            C_Repository -->|"triggers"| C_Contracts
            C_Contracts -->|"emits"| C_Subgraph
        end
        
        %% Loans Service Subgraph
        subgraph "Loans Service"
            L_Controller["API Controller"]:::microservice
            L_Interactor["Business Logic"]:::microservice
            L_Repository["Repository/Data Source"]:::microservice
            L_Controller -->|"calls"| L_Interactor
            L_Interactor -->|"accesses"| L_Repository
            L_Contracts["Smart Contracts"]:::blockchain
            L_Subgraph["Subgraph Service"]:::blockchain
            L_Repository -->|"triggers"| L_Contracts
            L_Contracts -->|"emits"| L_Subgraph
        end
        
        %% Requests Service Subgraph
        subgraph "Requests Service"
            R_Controller["API Operations"]:::microservice
        end
    end

    %% Client interactions with Microservices
    Client -->|"REST API calls"| A_Controller
    Client -->|"REST API calls"| C_Controller
    Client -->|"REST API calls"| L_Controller
    Client -->|"REST API calls"| R_Controller

    %% ML Service Layer
    subgraph "ML Service Layer"
        ML["ML Service (Loans Model)"]:::ml
    end

    %% External Data & Query Services
    subgraph "Data & Query Services"
        DB["MongoDB"]:::database
        GN["Graph Node (TheGraph)"]:::external
    end

    %% Shared Packages
    subgraph "Shared Packages"
        SP1["Utilities (bank-utils)"]:::package
        SP2["Logger"]:::package
        SP3["ESLint Config"]:::package
        SP4["TS Configurations"]:::package
    end

    %% Infrastructure & Orchestration
    subgraph "Infrastructure"
        DC["Docker Compose"]:::infra
        DF1["Dockerfile (Accounts)"]:::infra
        DF2["Dockerfile (Customers)"]:::infra
        DF3["Dockerfile (Loans)"]:::infra
        DF4["Dockerfile (Requests)"]:::infra
        DF5["Dockerfile (Client)"]:::infra
        DF6["Dockerfile (Loans-Model)"]:::infra
    end

    %% Shared Blockchain Contracts from Shared Packages
    BC_Shared["Shared Blockchain Contracts"]:::blockchain

    %% Connections between Microservices and External Systems
    A_Repository -- "stores/reads"--> DB
    C_Repository -- "stores/reads"--> DB
    L_Repository -- "stores/reads"--> DB
    R_Controller -- "stores/reads"--> DB

    C_Subgraph -- "updates"--> GN
    L_Subgraph -- "updates"--> GN

    %% ML Service gets data from Loans Repository
    L_Repository -- "data_for_prediction"--> ML

    %% Shared Packages support Microservices
    SP1 --- A_Controller
    SP1 --- C_Controller
    SP1 --- L_Controller
    SP2 --- A_Controller
    SP2 --- C_Controller
    SP2 --- L_Controller
    SP3 --- A_Controller
    SP3 --- C_Controller
    SP3 --- L_Controller
    SP4 --- A_Controller
    SP4 --- C_Controller
    SP4 --- L_Controller

    %% Infrastructure orchestrates services and client
    DC --- Client
    DC --- A_Controller
    DC --- C_Controller
    DC --- L_Controller
    DC --- R_Controller
    DC --- ML

    %% Integration of Blockchain components within microservices
    C_Contracts --- BC_Shared
    L_Contracts --- BC_Shared

    %% Click Events for Component Mapping
    click Client "https://github.com/albertobas/bank-microservices/tree/main/services/client"
    click A_Controller "https://github.com/albertobas/bank-microservices/tree/main/services/accounts"
    click C_Controller "https://github.com/albertobas/bank-microservices/tree/main/services/customers"
    click L_Controller "https://github.com/albertobas/bank-microservices/tree/main/services/loans"
    click R_Controller "https://github.com/albertobas/bank-microservices/tree/main/services/requests"
    click ML "https://github.com/albertobas/bank-microservices/tree/main/services/loans-model"
    click SP1 "https://github.com/albertobas/bank-microservices/tree/main/packages/bank-utils"
    click SP2 "https://github.com/albertobas/bank-microservices/tree/main/packages/logger"
    click SP3 "https://github.com/albertobas/bank-microservices/tree/main/packages/eslint-config-custom*"
    click SP4 "https://github.com/albertobas/bank-microservices/tree/main/packages/tsconfig"
    click BC_Shared "https://github.com/albertobas/bank-microservices/tree/main/packages/bank-utils/contracts"
    click C_Contracts "https://github.com/albertobas/bank-microservices/tree/main/services/customers/contracts"
    click C_Subgraph "https://github.com/albertobas/bank-microservices/tree/main/services/customers/subgraph"
    click L_Contracts "https://github.com/albertobas/bank-microservices/tree/main/services/loans/contracts"
    click L_Subgraph "https://github.com/albertobas/bank-microservices/tree/main/services/loans/subgraph"
    click DC "https://github.com/albertobas/bank-microservices/blob/main/docker-compose.yaml"
    click DF1 "https://github.com/albertobas/bank-microservices/tree/main/services/accounts/Dockerfile"
    click DF2 "https://github.com/albertobas/bank-microservices/tree/main/services/customers/Dockerfile"
    click DF3 "https://github.com/albertobas/bank-microservices/tree/main/services/loans/Dockerfile"
    click DF4 "https://github.com/albertobas/bank-microservices/tree/main/services/requests/Dockerfile"
    click DF5 "https://github.com/albertobas/bank-microservices/tree/main/services/client/Dockerfile"
    click DF6 "https://github.com/albertobas/bank-microservices/tree/main/services/loans-model/Dockerfile"
    click DB "https://github.com/albertobas/bank-microservices/tree/main/services/accounts/mongo"
    click GN "https://github.com/albertobas/bank-microservices/tree/main/services/graph-node"

    %% Styles
    classDef frontend fill:#FFCC00,stroke:#333,stroke-width:2px;
    classDef microservice fill:#AED6F1,stroke:#333,stroke-width:2px;
    classDef blockchain fill:#F5B7B1,stroke:#333,stroke-width:2px;
    classDef ml fill:#A3E4D7,stroke:#333,stroke-width:2px;
    classDef package fill:#F9E79F,stroke:#333,stroke-width:2px;
    classDef infra fill:#82E0AA,stroke:#333,stroke-width:2px;
    classDef database fill:#FAD7A0,stroke:#333,stroke-width:2px;
    classDef external fill:#D7DBDD,stroke:#333,stroke-width:2px;
```
