# insei/gerpo architecture

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

- Interactive diagram: https://gitdiagram.com/insei/gerpo
- Repository: https://github.com/insei/gerpo

## Overview

##### Project type and purpose
- Type: Go library / open-source toolkit for data repository abstraction
- Purpose: Provide a generic, builder-based repository API that generates SQL, executes it via interchangeable adapters, and returns typed entities with optional caching/logging

##### File structure
- Top-level modules:
– builder.go / builder_test.go: entry point for NewBuilder[T]()
– column/: ColumnBuilder and naming/options for mapping struct fields→SQL columns
– query/: User-facing query builders and internal LINQ-style API
– sqlstmt/: SQL statement generator & sub-packages (sqlpart)
– executor/: Core executor, cache layer, adapters (databasesql, pgx4, pgx5, placeholder)
– virtual/: Virtual field (calculated columns) builder
– logger/: Pluggable logging interface
– examples/, tests/: usage examples and integration tests

##### README for architecture insights
- Main components described under “Documentation”:
– repository (wires together sqlstmt, query, executor; handles hooks/callbacks)
– query (user API & linq internals)
– sqlstmt (SQL generator)
– executor (executes SQL & maps rows→entities)
- Features: adapter pattern for DB drivers, optional cache in executor, column & soft-delete builders

##### Main components & their relationships
a. Configuration layer (Builder):
- NewBuilder[T]()
- ColumnBuilder[T], VirtualBuilder[T], SoftDeletionBuilder[T]
- Builds a Repository[T] instance bundling table, columns, hooks, error transformers
b. Query layer:
- Per-request GetFirstHelper, GetListHelper, etc.
- Uses query.Linq API to express WHERE, ORDER, GROUP, JOIN
c. SQL generation layer:
- sqlstmt package: count, select, insert, update, delete generators
- sqlpart sub-package builds individual SQL clauses
d. Execution layer:
- Executor core: receives SQL + args, maps results → T
- Cache middleware: context-based cache bundle
- Adapters:
– databasesql (database/sql)
– pgx4, pgx5 (Postgres)
– placeholder (tests/dry run)
e. External services:
- Relational database (Postgres, MySQL, etc.)
- Optional external cache (e.g., Redis)

1. **Client Code** calls methods on **Repository[T]**
2. Repository hands parameters → **Query Builder** (GetList, GetFirst, Insert, Update, Delete)
3. Query Builder emits logical filters/orders → **sqlstmt** generators → raw SQL + args
4. SQL + args passed into **Executor**
– Executor invokes **Cache** (optional)
– On cache miss, Executor dispatches to chosen **Adapter**
– Adapter uses underlying DB driver to send SQL → **Database**
– Rows returned → Adapter → Executor maps → []T or T
– Executor stores result in Cache (if configured)
5. Mapped entities returned to Client Code

##### Architectural patterns & principles
- Builder Pattern: repository, column, query, virtual, soft-delete builders
- Adapter Pattern: pluggable DB drivers under executor/adapters
- Separation of Concerns:
– Mapping (column, virtual)
– Query construction (query, linq)
– SQL generation (sqlstmt)
– Execution & mapping (executor + adapters)
– Cross-cutting: caching, logging, error transformation
- Generics for type safety: Repository[T], builders, helpers

- Core modules and their extension points:
– Where to drop in new adapters (executor/adapters)
– How to add custom cache engines (executor/cache)
– Column/virtual builders for mapping fields
- External integration: DB drivers, Redis, logging backends

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Layers
    subgraph "Client Layer" 
        direction TB
        Client["Client Code"]:::external
    end

    subgraph "Configuration Layer" 
        direction TB
        BuilderGO["builder.go"]:::config
        BuilderTest["builder_test.go"]:::config
        SoftDel["soft.go"]:::config
    end

    subgraph "Column Mapping" 
        direction TB
        ColBuilder["column/builder.go"]:::config
        ColColumn["column/column.go"]:::config
        ColNaming["column/naming.go"]:::config
        ColOptions["column/options.go"]:::config
    end

    subgraph "Virtual Fields" 
        direction TB
        VirtBuilder["virtual/builder.go"]:::config
        VirtColumn["virtual/column.go"]:::config
        VirtOptions["virtual/options.go"]:::config
    end

    subgraph "Repository Core"
        direction TB
        RepoCore["repository.go"]:::config
        RepoTest["repository_test.go"]:::config
    end

    subgraph "Query Layer"
        direction TB
        QCount["query/count.go"]:::query
        QFirst["query/first.go"]:::query
        QList["query/list.go"]:::query
        QInsert["query/insert.go"]:::query
        QUpdate["query/update.go"]:::query
        QDelete["query/delete.go"]:::query
        QErrors["query/errors.go"]:::query
        subgraph "LINQ Internals"
            direction TB
            QWhere["query/linq/where.go"]:::query
            QOrder["query/linq/order.go"]:::query
            QJoin["query/linq/join.go"]:::query
            QGroup["query/linq/group.go"]:::query
            QPag["query/linq/pagination.go"]:::query
            QExcl["query/linq/exclude.go"]:::query
        end
    end

    subgraph "SQL Generation Layer"
        direction TB
        SCount["sqlstmt/count.go"]:::sql
        SFirst["sqlstmt/first.go"]:::sql
        SList["sqlstmt/list.go"]:::sql
        SInsert["sqlstmt/insert.go"]:::sql
        SUpdate["sqlstmt/update.go"]:::sql
        SDelete["sqlstmt/delete.go"]:::sql
        SSelect["sqlstmt/select.go"]:::sql
        SValues["sqlstmt/values.go"]:::sql
        subgraph "SQL Parts"
            direction TB
            SPWhere["sqlstmt/sqlpart/where.go"]:::sql
            SPOrder["sqlstmt/sqlpart/order.go"]:::sql
            SPJoin["sqlstmt/sqlpart/join.go"]:::sql
            SPGroup["sqlstmt/sqlpart/group.go"]:::sql
            SPLimit["sqlstmt/sqlpart/limit.go"]:::sql
        end
    end

    subgraph "Execution Layer"
        direction TB
        ExecCore["executor/executor.go"]:::exec
        ExecTypes["executor/types.go"]:::exec
        ExecOpts["executor/options.go"]:::exec
        subgraph "Cache Middleware"
            direction TB
            CacheCore["executor/cache.go"]:::exec
            CacheBundle["executor/cache/bundle.go"]:::exec
            CacheCtx["executor/cache/ctx/middleware.go"]:::exec
        end
        subgraph "Adapters"
            direction TB
            ADSQL["executor/adapters/databasesql/db.go"]:::exec
            ADPGX4["executor/adapters/pgx4/pool.go"]:::exec
            ADPGX5["executor/adapters/pgx5/pool.go"]:::exec
            ADPlace["executor/adapters/placeholder/placeholders.go"]:::exec
        end
    end

    subgraph "External Services"
        direction TB
        DB["Relational Database"]:::external
        CacheExt["External Cache (Redis)"]:::external
        LoggerExt["Logging Backends"]:::external
    end

    %% Connections
    Client -->|calls Repository| RepoCore
    RepoCore -->|uses Builder| BuilderGO
    RepoCore -->|uses Column Mapping| ColBuilder
    RepoCore -->|uses Virtual Fields| VirtBuilder
    RepoCore -->|uses Soft Deletion| SoftDel

    RepoCore -->|initiates Query| QCount
    QCount -->|linq| QWhere
    QCount -->|to SQL| SCount
    QList -->|to SQL| SList
    QInsert -->|to SQL| SInsert
    QUpdate -->|to SQL| SUpdate
    QDelete -->|to SQL| SDelete
    SCount -->|SQL+args| ExecCore
    SList -->|SQL+args| ExecCore
    SInsert -->|SQL+args| ExecCore
    SUpdate -->|SQL+args| ExecCore
    SDelete -->|SQL+args| ExecCore

    ExecCore -->|check cache| CacheCore
    CacheCore -->|miss| ADSQL
    CacheCore -->|miss| ADPGX4
    CacheCore -->|miss| ADPGX5
    CacheCore -->|miss| ADPlace

    ADSQL -->|exec SQL| DB
    ADPGX4 -->|exec SQL| DB
    ADPGX5 -->|exec SQL| DB
    ADPlace -->|dry run| DB

    ExecCore -->|rows→entities| Client
    ExecCore -->|store result| CacheCore

    ExecCore -->|logs| LoggerExt

    %% Click Events
    click BuilderGO "https://github.com/insei/gerpo/blob/main/builder.go"
    click BuilderTest "https://github.com/insei/gerpo/blob/main/builder_test.go"
    click ColBuilder "https://github.com/insei/gerpo/blob/main/column/builder.go"
    click ColColumn "https://github.com/insei/gerpo/blob/main/column/column.go"
    click ColNaming "https://github.com/insei/gerpo/blob/main/column/naming.go"
    click ColOptions "https://github.com/insei/gerpo/blob/main/column/options.go"
    click VirtBuilder "https://github.com/insei/gerpo/blob/main/virtual/builder.go"
    click VirtColumn "https://github.com/insei/gerpo/blob/main/virtual/column.go"
    click VirtOptions "https://github.com/insei/gerpo/blob/main/virtual/options.go"
    click SoftDel "https://github.com/insei/gerpo/blob/main/soft.go"
    click RepoCore "https://github.com/insei/gerpo/blob/main/repository.go"
    click RepoTest "https://github.com/insei/gerpo/blob/main/repository_test.go"
    click QCount "https://github.com/insei/gerpo/blob/main/query/count.go"
    click QFirst "https://github.com/insei/gerpo/blob/main/query/first.go"
    click QList "https://github.com/insei/gerpo/blob/main/query/list.go"
    click QInsert "https://github.com/insei/gerpo/blob/main/query/insert.go"
    click QUpdate "https://github.com/insei/gerpo/blob/main/query/update.go"
    click QDelete "https://github.com/insei/gerpo/blob/main/query/delete.go"
    click QErrors "https://github.com/insei/gerpo/blob/main/query/errors.go"
    click QWhere "https://github.com/insei/gerpo/blob/main/query/linq/where.go"
    click QOrder "https://github.com/insei/gerpo/blob/main/query/linq/order.go"
    click QJoin "https://github.com/insei/gerpo/blob/main/query/linq/join.go"
    click QGroup "https://github.com/insei/gerpo/blob/main/query/linq/group.go"
    click QPag "https://github.com/insei/gerpo/blob/main/query/linq/pagination.go"
    click QExcl "https://github.com/insei/gerpo/blob/main/query/linq/exclude.go"
    click SCount "https://github.com/insei/gerpo/blob/main/sqlstmt/count.go"
    click SFirst "https://github.com/insei/gerpo/blob/main/sqlstmt/first.go"
    click SList "https://github.com/insei/gerpo/blob/main/sqlstmt/list.go"
    click SInsert "https://github.com/insei/gerpo/blob/main/sqlstmt/insert.go"
    click SUpdate "https://github.com/insei/gerpo/blob/main/sqlstmt/update.go"
    click SDelete "https://github.com/insei/gerpo/blob/main/sqlstmt/delete.go"
    click SSelect "https://github.com/insei/gerpo/blob/main/sqlstmt/select.go"
    click SValues "https://github.com/insei/gerpo/blob/main/sqlstmt/values.go"
    click SPWhere "https://github.com/insei/gerpo/blob/main/sqlstmt/sqlpart/where.go"
    click SPOrder "https://github.com/insei/gerpo/blob/main/sqlstmt/sqlpart/order.go"
    click SPJoin "https://github.com/insei/gerpo/blob/main/sqlstmt/sqlpart/join.go"
    click SPGroup "https://github.com/insei/gerpo/blob/main/sqlstmt/sqlpart/group.go"
    click SPLimit "https://github.com/insei/gerpo/blob/main/sqlstmt/sqlpart/limit.go"
    click ExecCore "https://github.com/insei/gerpo/blob/main/executor/executor.go"
    click ExecTypes "https://github.com/insei/gerpo/blob/main/executor/types.go"
    click ExecOpts "https://github.com/insei/gerpo/blob/main/executor/options.go"
    click CacheCore "https://github.com/insei/gerpo/blob/main/executor/cache.go"
    click CacheBundle "https://github.com/insei/gerpo/blob/main/executor/cache/bundle.go"
    click CacheCtx "https://github.com/insei/gerpo/blob/main/executor/cache/ctx/middleware.go"
    click ADSQL "https://github.com/insei/gerpo/blob/main/executor/adapters/databasesql/db.go"
    click ADPGX4 "https://github.com/insei/gerpo/blob/main/executor/adapters/pgx4/pool.go"
    click ADPGX5 "https://github.com/insei/gerpo/blob/main/executor/adapters/pgx5/pool.go"
    click ADPlace "https://github.com/insei/gerpo/blob/main/executor/adapters/placeholder/placeholders.go"

    %% Styles
    classDef config fill:#D6EAF8,stroke:#3498DB,color:#1B4F72
    classDef query fill:#D5F5E3,stroke:#27AE60,color:#145A32
    classDef sql fill:#FCF3CF,stroke:#F1C40F,color:#7D6608
    classDef exec fill:#FDEBD0,stroke:#E67E22,color:#87431D
    classDef external fill:#E5E8E8,stroke:#7F8C8D,color:#2C3E50
```
