# 9tigerio/db2rest architecture

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

- Interactive diagram: https://gitdiagram.com/9tigerio/db2rest
- Repository: https://github.com/9tigerio/db2rest

## Overview

##### Project Type and Purpose
- DB2Rest is a Java-based, multi-module Maven project that provides an auto-generated, low-code REST API layer on top of any supported relational database. It’s primarily a backend service (Spring Boot), not a two-sided UI/DB app, with plugin-style support for different SQL dialects and pluggable authentication providers.

##### High-Level Modules / Components
a. api-rest (Spring Boot application)
b. auth (authentication filter + auth-provider plugins: API-key, Basic, JWT, UnKey)
c. rest-common & db2rest-common (shared DTOs, exception handlers, common config)
d. rdbms-common & rdbms-support (core JDBC routing, service layer for CRUD/RPC operations, RSQL parsing)
e. dialects/*-dialect (plugin modules supplying SQL templates and Dialect implementations per database)
f. external systems: supported relational databases (Postgres, MySQL, Oracle, MSSQL, MariaDB, …), Docker/Testcontainers for integration tests

##### Request Flow and Component Interactions
1. Client → HTTP(S)
2. api-rest: incoming request enters Spring’s DispatcherServlet
3. AuthFilter (from auth module) intercepts → chooses AuthProvider plugin → validates credentials → on failure throws AuthenticationFailedException
4. DatabaseContextRequestInterceptor sets the current database context (multi-DB routing)
5. Controller layer (jdbc/rest/…) matches the REST verb/URL → invokes corresponding Controller (e.g., ReadController, CreateController)
6. Controllers delegate to RdbmsRestApi (generic entry point) → hands off to JdbcOperationService (rdbms-support)
7. JdbcOperationService uses RSQLParser + QueryRequest → builds SQL via Jinjava templates (in api-rest/src/main/resources/sql-templates)
8. RoutingDataSource (multi-DB support) picks the right DataSource bean based on context
9. JDBC driver + Dialect plugin generate SQL and execute on the target database
10. Results mapped to DTOs (db2rest-common) and returned as JSON

##### Architectural Patterns and Design Principles
- Layered Architecture:
- Presentation/API layer (Spring controllers, filters)
- Service/Business layer (JdbcOperationService, core CRUD/RPC services)
- Data/Infrastructure layer (RoutingDataSource, Dialect implementations, JDBC manager)
- Plugin/Extension Model: Dialect modules and Auth providers packaged as separate Maven sub-modules
- Convention over Configuration: Jinjava templates for SQL generation, standard REST paths
- Multi-tenancy/Multi-DB: DatabaseContextHolder + RoutingDataSource
- Use of TestContainers: integration tests spun up per-database via docker-compose/testcontainers

##### Final Checklist
[ ] Distinct layer boundaries (API, Auth, Common, Business, Data, External)
[ ] All main Maven modules shown as components

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client
    Client["Client"]:::external

    %% API Layer
    subgraph "API Layer" 
        direction TB
        Dispatcher["DispatcherServlet"]:::api
        AuthFilter["AuthFilter"]:::api
        DBInterceptor["DatabaseContextRequestInterceptor"]:::api
        Controllers["Controllers\n(Read/Create/etc)"]:::api
    end

    %% Shared/Common Layer
    subgraph "Shared/Common" 
        direction TB
        RestCommon["rest-common\n(DTOs, Exceptions)"]:::common
        DB2RestCommon["db2rest-common\n(DTOs, Exceptions)"]:::common
    end

    %% Service/Business Layer
    subgraph "Service/Business Layer"
        direction TB
        JdbcService["JdbcOperationService"]:::service
        RSQLParser["RSQLParserBuilder"]:::service
        JinjavaExec["JinJavaTemplateExecutorService"]:::service
    end

    %% Data/Infrastructure Layer
    subgraph "Data/Infrastructure Layer"
        direction TB
        RoutingDS["RoutingDataSource"]:::infrastructure
        DialectIface["Dialect Interface"]:::infrastructure
        ModelDefs["Core Model Definitions"]:::infrastructure
        SQLTemplates["SQL Templates"]:::infrastructure
    end

    %% Plugins
    subgraph "Plugins/Extensions"
        direction TB
        subgraph "Auth Providers"
            direction TB
            ApiKeyProv["ApiKeyAuthProvider"]:::plugin
            BasicProv["BasicAuthProvider"]:::plugin
            JwtProv["JwtAuthProvider"]:::plugin
            UnKeyProv["UnKeyAuthProvider"]:::plugin
        end
        subgraph "Dialect Plugins"
            direction TB
            MariaDBDia["MariaDBDialect"]:::plugin
            MySQLDia["MySQLDialect"]:::plugin
            PostgresDia["PostGreSQLDialect"]:::plugin
            OracleDia["OracleDialect"]:::plugin
            Oracle9iDia["Oracle9iDialect"]:::plugin
            MSSQLDia["MsSQLServerDialect"]:::plugin
        end
    end

    %% External Systems
    subgraph "External Databases"
        direction TB
        PostgresDB[(PostgreSQL)]:::database
        MySQLDB[(MySQL)]:::database
        OracleDB[(Oracle)]:::database
        MSSQLDB[(MSSQL)]:::database
        MariaDBDB[(MariaDB)]:::database
    end

    %% Flow Arrows
    Client -->|"HTTP(S) Request"| Dispatcher
    Dispatcher -->|"intercept"| AuthFilter
    AuthFilter -->|"validate()"| ApiKeyProv
    AuthFilter -->|"validate()"| BasicProv
    AuthFilter -->|"validate()"| JwtProv
    AuthFilter -->|"validate()"| UnKeyProv
    AuthFilter -->|"on success"| DBInterceptor
    DBInterceptor -->|"set context"| Controllers
    Controllers -->|"invoke"| JdbcService
    JdbcService -->|"build via RSQL"| RSQLParser
    JdbcService -->|"render SQL"| JinjavaExec
    JinjavaExec --> SQLTemplates
    JdbcService -->|"get DataSource"| RoutingDS
    RoutingDS -.->|"routes"| MariaDBDia
    RoutingDS -.->|"routes"| MySQLDia
    RoutingDS -.->|"routes"| PostgresDia
    RoutingDS -.->|"routes"| OracleDia
    RoutingDS -.->|"routes"| Oracle9iDia
    RoutingDS -.->|"routes"| MSSQLDia
    RoutingDS -->|"executeQuery()"| PostgresDB
    RoutingDS -->|"executeQuery()"| MySQLDB
    RoutingDS -->|"executeQuery()"| OracleDB
    RoutingDS -->|"executeQuery()"| MSSQLDB
    RoutingDS -->|"executeQuery()"| MariaDBDB
    PostgresDB -->|"ResultSet"| JdbcService
    MySQLDB -->|"ResultSet"| JdbcService
    OracleDB -->|"ResultSet"| JdbcService
    MSSQLDB -->|"ResultSet"| JdbcService
    MariaDBDB -->|"ResultSet"| JdbcService
    JdbcService -->|"map to DTO"| DB2RestCommon
    DB2RestCommon -->|"serialize JSON"| Controllers
    Controllers -->|"HTTP Response"| Client

    %% Click Events
    click Dispatcher "https://github.com/9tigerio/db2rest/tree/master/api-rest/src/main/java/com/homihq/db2rest"
    click Controllers "https://github.com/9tigerio/db2rest/tree/master/api-rest/src/main/java/com/homihq/db2rest/jdbc/rest"
    click SQLTemplates "https://github.com/9tigerio/db2rest/tree/master/api-rest/src/main/resources/sql-templates"
    click DBInterceptor "https://github.com/9tigerio/db2rest/blob/master/api-rest/src/main/java/com/homihq/db2rest/interceptor/DatabaseContextRequestInterceptor.java"
    click JdbcService "https://github.com/9tigerio/db2rest/blob/master/rdbms-support/src/main/java/com/homihq/db2rest/jdbc/JdbcOperationService.java"
    click ApiKeyProv "https://github.com/9tigerio/db2rest/blob/master/auth/src/main/java/com/homihq/db2rest/auth/apikey/ApiKeyAuthProvider.java"
    click BasicProv "https://github.com/9tigerio/db2rest/blob/master/auth/src/main/java/com/homihq/db2rest/auth/basic/BasicAuthProvider.java"
    click JwtProv "https://github.com/9tigerio/db2rest/blob/master/auth/src/main/java/com/homihq/db2rest/auth/jwt/JwtAuthProvider.java"
    click UnKeyProv "https://github.com/9tigerio/db2rest/blob/master/auth/src/main/java/com/homihq/db2rest/auth/unkey/UnKeyAuthFilter.java"
    click RestCommon "https://github.com/9tigerio/db2rest/tree/master/rest-common/src/main/java/com/homihq/db2rest/config"
    click DB2RestCommon "https://github.com/9tigerio/db2rest/tree/master/db2rest-common/src/main/java/com/homihq/db2rest/core/dto"
    click DialectIface "https://github.com/9tigerio/db2rest/blob/master/rdbms-common/src/main/java/com/homihq/db2rest/jdbc/config/dialect/Dialect.java"
    click ModelDefs "https://github.com/9tigerio/db2rest/tree/master/rdbms-common/src/main/java/com/homihq/db2rest/jdbc/config/model"
    click RSQLParser "https://github.com/9tigerio/db2rest/blob/master/rdbms-support/src/main/java/com/homihq/db2rest/jdbc/rsql/parser/RSQLParserBuilder.java"
    click SQLTemplates "https://github.com/9tigerio/db2rest/tree/master/api-rest/src/main/resources/sql-templates"
    click RoutingDS "https://github.com/9tigerio/db2rest/blob/master/rdbms-support/src/main/java/com/homihq/db2rest/jdbc/multidb/RoutingDataSource.java"
    click JinjavaExec "https://github.com/9tigerio/db2rest/blob/master/rdbms-support/src/main/java/com/homihq/db2rest/jdbc/core/service/JinJavaTemplateExecutorService.java"
    click MariaDBDia "https://github.com/9tigerio/db2rest/blob/master/dialects/mariadb-dialect/src/main/java/com/homihq/db2rest/jdbc/config/dialect/MariaDBDialect.java"
    click MySQLDia "https://github.com/9tigerio/db2rest/blob/master/dialects/mysql-dialect/src/main/java/com/homihq/db2rest/jdbc/config/dialect/MySQLDialect.java"
    click PostgresDia "https://github.com/9tigerio/db2rest/blob/master/dialects/pg-dialect/src/main/java/com/homihq/db2rest/jdbc/config/dialect/PostGreSQLDialect.java"
    click OracleDia "https://github.com/9tigerio/db2rest/blob/master/dialects/oracle-dialect/src/main/java/com/homihq/db2rest/jdbc/config/dialect/OracleDialect.java"
    click Oracle9iDia "https://github.com/9tigerio/db2rest/blob/master/dialects/oracle9i-dialect/src/main/java/com/homihq/db2rest/jdbc/config/dialect/OracleDialect.java"
    click MSSQLDia "https://github.com/9tigerio/db2rest/blob/master/dialects/mssql-dialect/src/main/java/com/homihq/db2rest/jdbc/config/dialect/MsSQLServerDialect.java"

    %% Styles
    classDef api fill:#cce5ff,stroke:#66b0ff,color:#000
    classDef service fill:#d4edda,stroke:#8fd19e,color:#000
    classDef infrastructure fill:#fff3cd,stroke:#ffecb5,color:#000
    classDef common fill:#e2e3e5,stroke:#c6c8ca,color:#000
    classDef plugin fill:#e2d5f3,stroke:#c3a6e0,color:#000
    classDef external fill:#f8d7da,stroke:#f5c2c7,color:#000
    classDef database fill:#d1ecf1,stroke:#a3dbe8,color:#000
```
