# openbankproject/obp-api architecture

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

- Interactive diagram: https://gitdiagram.com/openbankproject/obp-api
- Repository: https://github.com/openbankproject/obp-api

## Overview

This project is the Open Bank Project API – an open‐source banking API that serves as an abstraction layer over several core banking systems. Its purpose is to provide secure, extensible, and versioned web services for banks, empowering account holders and third-party applications to interact with banking data. The API supports multiple authentication protocols (OAuth 1.0a, OAuth2, OpenID Connect, Direct Login), extensive rate limiting, webhooks, sandbox data import, and even integration with asynchronous messaging systems (such as RabbitMQ and possibly Kafka) for bank connector communications.

##### Main components
- API Service Layer (obp-api): This is where most of the business logic resides. It hosts multiple API versions – organized by directories with version numbers (e.g. v1_2, v1_3_0, v2_0_0, v3_0_0, … up to v5_1_0). Each version implements specific REST endpoints for banking functionality.
- Common and Shared Libraries (obp-commons): Contains common models, DTOs, utility functions, helper classes, and shared enumerations used across the API.
- Connector Modules (inside obp-api and obp-commons): They abstract the integration with various core banking systems. There are multiple “bankconnectors” implementations (e.g. local mappers, REST connectors, stored procedure connectors, dynamic connectors, and even actor system based ones using Akka) that encapsulate the communication layer.
- Authentication & Authorization Component: Implements multiple authentication workflows – including OAuth1.0a, OAuth2, OpenID Connect, and Direct Login. It also contains modules for token management, certificate verification, and super admin user configuration.
- Data Persistence and Database Access: The system uses relational databases (PostgreSQL, MS SQL, H2) for storing banking, customer, and transaction data. There are dedicated data access objects and migration scripts (in the “obp-api/src/main/scripts/migrate” and “obp-api/src/main/scripts/sql” directories) that handle schema creation and updates.
- Caching and Rate Limiting Modules: Incorporates in-memory or Redis-based caching (files under obp-api/src/main/scala/code/api/cache) and implements call limits for API consumers.
- Web Portal and Front-End Assets: The project also hosts a web portal (via Lift Web and Jetty, with files in “src/main/webapp”) for API explorers, user interfaces, and static pages (e.g., FAQ, privacy policy).
- Build and Deployment: Managed with Maven and Docker. The top-level files such as Dockerfile, .dockerignore, and GitHub workflows show the project’s CI/CD and containerization practices.
- Testing: There is an extensive test suite that spans unit tests, integration tests, and even specialized tests for “frozen” APIs and connectors. The test directories (obp-api/src/test/scala) clearly map to various system components.

##### Relationships and interactions
- The API Service Layer acts as the gateway that receives REST requests; it routes these requests (often versioned) into business logic that in turn uses the shared OBP commons modules.
- Authentication modules are invoked at the entry point to validate credentials (via OAuth, Direct Login, OIDC) and manage session tokens.
- Once authenticated, requests trigger calls to either the bank connector modules or direct database operations (via data access objects). The connector modules handle the integration with external banking systems and sometimes use asynchronous communication (via Akka or RabbitMQ) for decoupled operation.
- Caching and rate limiting modules intercede to ensure that both security and performance guidelines are met.
- The web portal component directly interacts with end users (or even third-party API explorers) to deliver documentation and sandbox interfaces.
- Testing and build pipelines leverage Maven and Docker to compile, run tests, and deploy the API on Jetty or as a standalone web server.

##### Important architectural patterns and design principles
- Modularization and separation of concerns: the code is clearly segmented into modules that handle API endpoints (of different versions), utility functions, connectors, data access, authentication, caching, and web UI.
- Versioned API design: Multiple API versions coexist allowing for backward compatibility and gradual enhancement.
- Use of microservice/multi-module patterns: While it is a monolithic repository, the structure aligns with separating components as if they were microservices (e.g., authentication, banking core integration, API gateway).
- Asynchronous communication: There is evidence of actor systems (via Akka) and messaging (RabbitMQ) to handle concurrency and decoupled integration.
- Extensive testing and “frozen” API metadata usage to preserve stable interfaces.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        A["Client / API Explorer"]:::client
    end

    %% API Gateway & Service Layer
    subgraph "API Gateway & Service Layer"
        B["API Service Layer (obp-api)"]:::api
    end

    %% Security Layer (Authentication, Rate Limiting, Caching)
    subgraph "Security Layer"
        subgraph "Authentication & Authorization"
            C1a["OAuth 1.0a"]:::auth
            C1b["OpenID Connect"]:::auth
            C1c["Direct Login"]:::auth
            C1d["DAuth"]:::auth
        end
        D["Rate Limiting"]:::auth
        E["Caching Module"]:::auth
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        F["OBP Commons (Shared Libraries)"]:::bus
    end

    %% Integration Layer
    subgraph "Integration Layer"
        G["Connector Modules"]:::connector
    end

    %% Data Persistence Layer
    subgraph "Data Persistence Layer"
        H["Data Migration Scripts"]:::data
        I["SQL Scripts"]:::data
    end

    %% Web Portal Layer
    subgraph "Web Portal Layer"
        J["Web Portal & Front-End Assets"]:::ui
    end

    %% Build & Deployment
    subgraph "Build & Deployment"
        K["Build & Deployment Pipeline"]:::build
    end

    %% Testing
    subgraph "Testing"
        L["Test Suite"]:::test
    end

    %% Flow Connections
    A -->|"sends request"| B
    B -->|"triggers"| C1a
    B -->|"triggers"| C1b
    B -->|"triggers"| C1c
    B -->|"triggers"| C1d
    B -->|"applies"| D
    B -->|"applies"| E
    B -->|"routes to"| F
    F -->|"invokes"| G
    F -->|"accesses"| H
    H -->|"uses"| I
    A -->|"accesses UI"| J

    %% Build & Testing link (side processes)
    K -.-> B
    L -.-> B

    %% Click Events
    click B "https://github.com/openbankproject/obp-api/tree/develop/obp-api/src/main/scala/code/api"
    click F "https://github.com/openbankproject/obp-api/tree/develop/obp-commons/src/main/scala/com/openbankproject/commons"
    click G "https://github.com/openbankproject/obp-api/tree/develop/obp-api/src/main/scala/code/bankconnectors"
    click C1a "https://github.com/openbankproject/obp-api/blob/develop/obp-api/src/main/scala/code/api/oauth1.0.scala"
    click C1b "https://github.com/openbankproject/obp-api/blob/develop/obp-api/src/main/scala/code/api/openidconnect.scala"
    click C1c "https://github.com/openbankproject/obp-api/blob/develop/obp-api/src/main/scala/code/api/directlogin.scala"
    click C1d "https://github.com/openbankproject/obp-api/blob/develop/obp-api/src/main/scala/code/api/dauth.scala"
    click H "https://github.com/openbankproject/obp-api/tree/develop/obp-api/src/main/scripts/migrate"
    click I "https://github.com/openbankproject/obp-api/tree/develop/obp-api/src/main/scripts/sql"
    click E "https://github.com/openbankproject/obp-api/tree/develop/obp-api/src/main/scala/code/api/cache"
    click D "https://github.com/openbankproject/obp-api/blob/develop/obp-api/src/main/scala/code/util/RateLimitingUtil.scala"
    click J "https://github.com/openbankproject/obp-api/tree/develop/obp-api/src/main/webapp"
    click K "https://github.com/openbankproject/obp-api/tree/develop/Dockerfile"
    click L "https://github.com/openbankproject/obp-api/tree/develop/obp-api/src/test/scala"

    %% Styles
    classDef client fill:#ffcc00,stroke:#333,stroke-width:2px;
    classDef api fill:#ff9999,stroke:#333,stroke-width:2px;
    classDef auth fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef bus fill:#ccccff,stroke:#333,stroke-width:2px;
    classDef connector fill:#99ccff,stroke:#333,stroke-width:2px;
    classDef data fill:#ffccff,stroke:#333,stroke-width:2px;
    classDef ui fill:#ccffff,stroke:#333,stroke-width:2px;
    classDef build fill:#f0f0f0,stroke:#333,stroke-width:2px;
    classDef test fill:#ffdead,stroke:#333,stroke-width:2px;
```
