# x-ream/sqli architecture

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

- Interactive diagram: https://gitdiagram.com/x-ream/sqli
- Repository: https://github.com/x-ream/sqli

## Overview

sqli is a Java SQL programming interface: callers build typed or map-oriented queries, repositories execute them, and results are returned as records, maps, pages, or streamed rows. Its main stages are entity mapping, query construction, SQL generation, and repository execution. Separate capabilities include dialect support, temporary/native SQL access, and optional second-level caching. The README documents these features; sampled source confirms selected parser, repository, and temporary-repository relationships, so unverified internal links are omitted or dashed.

Main entry points: [`sqli-core/src/main/java/io/xream/sqli/core/Repository.java`](https://github.com/x-ream/sqli/blob/master/sqli-core/src/main/java/io/xream/sqli/core/Repository.java) (Repository engine), [`sqli-repo/src/main/java/io/xream/sqli/repository/internal/DefaultRepositoryX.java`](https://github.com/x-ream/sqli/blob/master/sqli-repo/src/main/java/io/xream/sqli/repository/internal/DefaultRepositoryX.java) (Repository implementation), [`sqli-builder/src/main/java/io/xream/sqli/parser/Parser.java`](https://github.com/x-ream/sqli/blob/master/sqli-builder/src/main/java/io/xream/sqli/parser/Parser.java) (Entity parser), [`sqli-repo/src/main/java/io/xream/sqli/repository/dao/Dao.java`](https://github.com/x-ream/sqli/blob/master/sqli-repo/src/main/java/io/xream/sqli/repository/dao/Dao.java) (DAO execution)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_query["Query construction"]
  node_query_api["Query model<br/>[Q.java]"]
  node_query_builder["Query builders"]
  node_update_query["Update query<br/>[Qr.java]"]
  node_sql_generation["SQL generation<br/>[SqlScript.java]"]
end

subgraph group_execution["Repository execution"]
  node_base_api["Typed repository API"]
  node_repo_engine["Repository engine<br/>[Repository.java]"]
  node_repo_impl["Repository implementation"]
  node_dao["DAO execution<br/>[Dao.java]"]
end

subgraph group_mapping["Mapping and results"]
  node_entity_parser["Entity parser<br/>[Parser.java]"]
  node_parsed_metadata["Parsed metadata<br/>[Parsed.java]"]
  node_parser_util["Field mapping<br/>[ParserUtil.java]"]
  node_page["Paged results<br/>[Page.java]"]
  node_row_handler["Row streaming<br/>[RowHandler.java]"]
end

subgraph group_extensions["Database extensions"]
  node_dialects["SQL dialects"]
  node_cache["Second-level cache"]
  node_temp_repo["Temporary repository"]
  node_native_repo["Native repository"]
end

node_caller(("Application caller"))
node_jdbc[("Database")]

node_caller -->|"builds query"| node_query_builder
node_query_builder -->|"builds"| node_query_api
node_caller -->|"submits query"| node_base_api
node_base_api -->|"exposes operations"| node_repo_engine
node_repo_impl -->|"implements"| node_repo_engine
node_repo_impl -->|"accepts queries"| node_query_api
node_repo_impl -->|"parses entities"| node_entity_parser
node_entity_parser -->|"extracts mappings"| node_parser_util
node_entity_parser -->|"stores metadata"| node_parsed_metadata
node_repo_engine -.->|"generates SQL"| node_sql_generation
node_repo_engine -.->|"delegates execution"| node_dao
node_dao -.->|"executes SQL"| node_jdbc
node_repo_engine -->|"returns pages"| node_page
node_repo_engine -->|"streams rows"| node_row_handler
node_repo_engine -.->|"supports cached queries"| node_cache
node_repo_engine -.->|"uses SQL dialect"| node_dialects
node_caller -->|"builds updates"| node_update_query
node_caller -->|"uses temporary tables"| node_temp_repo
node_temp_repo -->|"delegates queries"| node_dao
node_caller -->|"uses native SQL"| node_native_repo

click node_query_api "https://github.com/x-ream/sqli/blob/master/sqli-builder/src/main/java/io/xream/sqli/builder/Q.java"
click node_query_builder "https://github.com/x-ream/sqli/tree/master/sqli-builder/src/main/java/io/xream/sqli/builder"
click node_update_query "https://github.com/x-ream/sqli/blob/master/sqli-builder/src/main/java/io/xream/sqli/builder/Qr.java"
click node_sql_generation "https://github.com/x-ream/sqli/blob/master/sqli-builder/src/main/java/io/xream/sqli/builder/internal/SqlScript.java"
click node_entity_parser "https://github.com/x-ream/sqli/blob/master/sqli-builder/src/main/java/io/xream/sqli/parser/Parser.java"
click node_parsed_metadata "https://github.com/x-ream/sqli/blob/master/sqli-builder/src/main/java/io/xream/sqli/parser/Parsed.java"
click node_parser_util "https://github.com/x-ream/sqli/blob/master/sqli-builder/src/main/java/io/xream/sqli/util/ParserUtil.java"
click node_base_api "https://github.com/x-ream/sqli/blob/master/sqli-core/src/main/java/io/xream/sqli/api/BaseRepository.java"
click node_repo_engine "https://github.com/x-ream/sqli/blob/master/sqli-core/src/main/java/io/xream/sqli/core/Repository.java"
click node_repo_impl "https://github.com/x-ream/sqli/blob/master/sqli-repo/src/main/java/io/xream/sqli/repository/internal/DefaultRepositoryX.java"
click node_dao "https://github.com/x-ream/sqli/blob/master/sqli-repo/src/main/java/io/xream/sqli/repository/dao/Dao.java"
click node_page "https://github.com/x-ream/sqli/blob/master/sqli-builder/src/main/java/io/xream/sqli/page/Page.java"
click node_row_handler "https://github.com/x-ream/sqli/blob/master/sqli-core/src/main/java/io/xream/sqli/core/RowHandler.java"
click node_dialects "https://github.com/x-ream/sqli/tree/master/sqli-dialect/src/main/java/io/xream/sqli/dialect"
click node_cache "https://github.com/x-ream/sqli/tree/master/sqli-core/src/main/java/io/xream/sqli/cache"
click node_temp_repo "https://github.com/x-ream/sqli/blob/master/sqli-repo/src/main/java/io/xream/sqli/repository/internal/DefaultTemporaryRepository.java"
click node_native_repo "https://github.com/x-ream/sqli/blob/master/sqli-repo/src/main/java/io/xream/sqli/repository/internal/DefaultNativeRepository.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_query_api,node_query_builder,node_update_query,node_sql_generation toneBlue
class node_base_api,node_repo_engine,node_repo_impl,node_dao,node_jdbc toneAmber
class node_entity_parser,node_parsed_metadata,node_parser_util,node_page,node_row_handler toneMint
class node_dialects,node_cache,node_temp_repo,node_native_repo toneRose
class node_caller toneIndigo
```

## Components

### Query construction

- [Query model](https://github.com/x-ream/sqli/blob/master/sqli-builder/src/main/java/io/xream/sqli/builder/Q.java): `sqli-builder/src/main/java/io/xream/sqli/builder/Q.java`
- [Query builders](https://github.com/x-ream/sqli/tree/master/sqli-builder/src/main/java/io/xream/sqli/builder): `sqli-builder/src/main/java/io/xream/sqli/builder`
- [Update query](https://github.com/x-ream/sqli/blob/master/sqli-builder/src/main/java/io/xream/sqli/builder/Qr.java): `sqli-builder/src/main/java/io/xream/sqli/builder/Qr.java`
- [SQL generation](https://github.com/x-ream/sqli/blob/master/sqli-builder/src/main/java/io/xream/sqli/builder/internal/SqlScript.java): `sqli-builder/src/main/java/io/xream/sqli/builder/internal/SqlScript.java`

### Repository execution

- [Typed repository API](https://github.com/x-ream/sqli/blob/master/sqli-core/src/main/java/io/xream/sqli/api/BaseRepository.java): `sqli-core/src/main/java/io/xream/sqli/api/BaseRepository.java`
- [Repository engine](https://github.com/x-ream/sqli/blob/master/sqli-core/src/main/java/io/xream/sqli/core/Repository.java): `sqli-core/src/main/java/io/xream/sqli/core/Repository.java`
- [Repository implementation](https://github.com/x-ream/sqli/blob/master/sqli-repo/src/main/java/io/xream/sqli/repository/internal/DefaultRepositoryX.java): `sqli-repo/src/main/java/io/xream/sqli/repository/internal/DefaultRepositoryX.java`
- [DAO execution](https://github.com/x-ream/sqli/blob/master/sqli-repo/src/main/java/io/xream/sqli/repository/dao/Dao.java): `sqli-repo/src/main/java/io/xream/sqli/repository/dao/Dao.java`

### Mapping and results

- [Entity parser](https://github.com/x-ream/sqli/blob/master/sqli-builder/src/main/java/io/xream/sqli/parser/Parser.java): `sqli-builder/src/main/java/io/xream/sqli/parser/Parser.java`
- [Parsed metadata](https://github.com/x-ream/sqli/blob/master/sqli-builder/src/main/java/io/xream/sqli/parser/Parsed.java): `sqli-builder/src/main/java/io/xream/sqli/parser/Parsed.java`
- [Field mapping](https://github.com/x-ream/sqli/blob/master/sqli-builder/src/main/java/io/xream/sqli/util/ParserUtil.java): `sqli-builder/src/main/java/io/xream/sqli/util/ParserUtil.java`
- [Paged results](https://github.com/x-ream/sqli/blob/master/sqli-builder/src/main/java/io/xream/sqli/page/Page.java): `sqli-builder/src/main/java/io/xream/sqli/page/Page.java`
- [Row streaming](https://github.com/x-ream/sqli/blob/master/sqli-core/src/main/java/io/xream/sqli/core/RowHandler.java): `sqli-core/src/main/java/io/xream/sqli/core/RowHandler.java`

### Database extensions

- [SQL dialects](https://github.com/x-ream/sqli/tree/master/sqli-dialect/src/main/java/io/xream/sqli/dialect): `sqli-dialect/src/main/java/io/xream/sqli/dialect`
- [Second-level cache](https://github.com/x-ream/sqli/tree/master/sqli-core/src/main/java/io/xream/sqli/cache): `sqli-core/src/main/java/io/xream/sqli/cache`
- [Temporary repository](https://github.com/x-ream/sqli/blob/master/sqli-repo/src/main/java/io/xream/sqli/repository/internal/DefaultTemporaryRepository.java): `sqli-repo/src/main/java/io/xream/sqli/repository/internal/DefaultTemporaryRepository.java`
- [Native repository](https://github.com/x-ream/sqli/blob/master/sqli-repo/src/main/java/io/xream/sqli/repository/internal/DefaultNativeRepository.java): `sqli-repo/src/main/java/io/xream/sqli/repository/internal/DefaultNativeRepository.java`

### Other components

- **Application caller**
- **Database**

## Connections

- Application caller → Query builders: builds query (evidence: `README.md`)
- Query builders → Query model: builds (evidence: `README.md`)
- Application caller → Typed repository API: submits query (evidence: `README.md`)
- Typed repository API → Repository engine: exposes operations (evidence: `sqli-core/src/main/java/io/xream/sqli/api/BaseRepository.java`)
- Repository implementation → Repository engine: implements (evidence: `sqli-repo/src/main/java/io/xream/sqli/repository/internal/DefaultRepositoryX.java`)
- Repository implementation → Query model: accepts queries (evidence: `sqli-repo/src/main/java/io/xream/sqli/repository/internal/DefaultRepositoryX.java`)
- Repository implementation → Entity parser: parses entities (evidence: `sqli-repo/src/main/java/io/xream/sqli/repository/internal/DefaultRepositoryX.java`)
- Entity parser → Field mapping: extracts mappings (evidence: `sqli-builder/src/main/java/io/xream/sqli/parser/Parser.java`)
- Entity parser → Parsed metadata: stores metadata (evidence: `sqli-builder/src/main/java/io/xream/sqli/parser/Parser.java`)
- Repository engine → SQL generation: generates SQL
- Repository engine → DAO execution: delegates execution
- DAO execution → Database: executes SQL
- Repository engine → Paged results: returns pages (evidence: `sqli-core/src/main/java/io/xream/sqli/core/Repository.java`)
- Repository engine → Row streaming: streams rows (evidence: `sqli-core/src/main/java/io/xream/sqli/core/Repository.java`)
- Repository engine → Second-level cache: supports cached queries (evidence: `sqli-core/src/main/java/io/xream/sqli/core/Repository.java`)
- Repository engine → SQL dialects: uses SQL dialect
- Application caller → Update query: builds updates (evidence: `README.md`)
- Application caller → Temporary repository: uses temporary tables (evidence: `README.md`)
- Temporary repository → DAO execution: delegates queries (evidence: `sqli-repo/src/main/java/io/xream/sqli/repository/internal/DefaultTemporaryRepository.java`)
- Application caller → Native repository: uses native SQL (evidence: `README.md`)
