# cap-js/cds-dbs architecture

> Architecture diagram of the GitHub repository cap-js/cds-dbs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cap-js/cds-dbs
- Repository: https://github.com/cap-js/cds-dbs

## Overview

##### Main Components Structure
a. Base Layer: db-service (core implementation)
b. Database Implementations Layer:
- SQLite implementation
- PostgreSQL implementation
- HANA implementation
c. Common Services Layer (shared functionality)
d. Test Layer (comprehensive test suite)

##### Component Relationships
a. Base Service Layer:
- DatabaseService class as the core abstract interface
- SQLService class as the base SQL implementation
- CQN (Common Query Notation) processing components

b. Database-Specific Implementations:
- Database service (SQLiteService, PostgresService, HANAService) to the base service
- Database-specific adapters and drivers
- Specific CQL function implementations

##### Key Technical Elements
- CQN to SQL conversion pipeline
- Query processing components
- Connection pooling mechanism
- Session context handling
- Database-specific optimizations

##### Specific Implementation Details
- Relationship between:
- CQN processing (cqn2sql.js, cqn4sql.js)
- Database connection handling
- Query execution pipeline
- Result processing

##### Integration Points
- CAP runtime integration
- OData service integration
- Custom handler integration
- Plugin system connection points

##### The extensibility points for custom implementations

- Component types and their relationships
- Flow direction conventions
- Special symbols or notations used

Keep the abstraction level focused on the architectural components while showing enough detail to understand the data flow and component interactions. This will help developers understand how to implement new database adapters or modify existing ones.

Remember to highlight the modular nature of the system, showing how each database implementation can be used independently while sharing the common core functionality.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Core["Base Layer"]
        DBS["DatabaseService<br/>(Abstract Interface)"]:::core
        SQLS["SQLService<br/>(Base SQL Implementation)"]:::core
        CQN["CQN Processing"]:::core
        CQL["CQL Functions"]:::core
    end

    subgraph DBImpl["Database Implementations"]
        SQLITE["SQLite Service"]:::db
        PSQL["PostgreSQL Service"]:::db
        HANA["HANA Service"]:::db
    end

    subgraph Common["Common Services"]
        POOL["Connection Pool"]:::util
        SESSION["Session Context"]:::util
        QUERY["Query Processing"]:::util
    end

    subgraph Processing["CQN Processing Pipeline"]
        CQN2SQL["CQN to SQL<br/>Converter"]:::process
        CQN4SQL["CQN for SQL<br/>Processor"]:::process
        DEEP["Deep Query<br/>Handler"]:::process
        SEARCH["Search<br/>Handler"]:::process
    end

    DBS --> SQLS
    SQLS --> |extends| SQLITE
    SQLS --> |extends| PSQL
    SQLS --> |extends| HANA
    
    CQN --> CQN2SQL
    CQN --> CQN4SQL
    
    QUERY --> DEEP
    QUERY --> SEARCH
    
    SQLITE --> |uses| POOL
    PSQL --> |uses| POOL
    HANA --> |uses| POOL
    
    SQLITE --> |uses| SESSION
    PSQL --> |uses| SESSION
    HANA --> |uses| SESSION
    
    CQL --> |implements| SQLITE
    CQL --> |implements| PSQL
    CQL --> |implements| HANA

    classDef core fill:#2374ab,stroke:#000,stroke-width:2px,color:#fff
    classDef db fill:#57a773,stroke:#000,stroke-width:2px,color:#fff
    classDef util fill:#ffc857,stroke:#000,stroke-width:2px,color:#000
    classDef process fill:#ef476f,stroke:#000,stroke-width:2px,color:#fff

    click DBS "https://github.com/cap-js/cds-dbs/blob/main/db-service/lib/common/DatabaseService.js"
    click SQLS "https://github.com/cap-js/cds-dbs/blob/main/db-service/lib/SQLService.js"
    click CQN2SQL "https://github.com/cap-js/cds-dbs/blob/main/db-service/lib/cqn2sql.js"
    click CQN4SQL "https://github.com/cap-js/cds-dbs/blob/main/db-service/lib/cqn4sql.js"
    click SQLITE "https://github.com/cap-js/cds-dbs/blob/main/sqlite/lib/SQLiteService.js"
    click PSQL "https://github.com/cap-js/cds-dbs/blob/main/postgres/lib/PostgresService.js"
    click HANA "https://github.com/cap-js/cds-dbs/blob/main/hana/lib/HANAService.js"
    click POOL "https://github.com/cap-js/cds-dbs/blob/main/db-service/lib/common/generic-pool.js"
    click SESSION "https://github.com/cap-js/cds-dbs/blob/main/db-service/lib/common/session-context.js"
    click DEEP "https://github.com/cap-js/cds-dbs/blob/main/db-service/lib/deep-queries.js"
    click SEARCH "https://github.com/cap-js/cds-dbs/blob/main/db-service/lib/search.js"
    click CQL "https://github.com/cap-js/cds-dbs/blob/main/db-service/lib/cql-functions.js"
```
