# remiges-tech/sqld architecture

> Architecture diagram of the GitHub repository remiges-tech/sqld, 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/remiges-tech/sqld
- Repository: https://github.com/remiges-tech/sqld

## Overview

##### Main Components

a) Core Library Components (Central Layer):
- Model Metadata System
- Query Builder System
- Executor System
- Safe Raw Query System

b) External Dependencies:
- squirrel (for query building)
- PostgreSQL Parser (for SQL validation)
- scany (for result mapping)
- sql.DB/pgx.Conn interfaces

c) Client Application Integration Points

##### Model Metadata System
- Model Registration
- Field Mapping
- Type Validation

##### Query Builder
- Structured Query Building
- Parameter Binding
- Pagination Handler
- Order By Handler

##### Executor
- Query Execution
- Result Mapping
- Pagination Processing

##### Safe Raw Query System
- Parameter Validation
- SQL Syntax Validation
- Type Checking

BOTTOM LAYER - Database Integration:
- Database Connectors (sql.DB/pgx.Conn)
- Database Systems (PostgreSQL)

##### Flow Representation

- Client request → Query Building → Execution → Database
- Database → Result Mapping → Client response

- Model registration → Metadata validation
- Query parameters → Type validation
- Raw SQL → Syntax validation

##### Component Details

For each component, include:
- Input/Output formats
- Key responsibilities
- Integration points

**┌─────────────────────────┐**
- Query Builder      │
- ┤
- Build SELECT/WHERE    │
- Handle pagination     │
- Process ordering      │
- Validate fields       │
- ┘

##### Notes

Annotations for:
- Type safety guarantees
- Validation checkpoints
- Performance considerations
- Extension points

- The clear separation between structured and raw query systems
- The type-safety mechanisms throughout the pipeline
- The validation layers at different stages
- The flexibility in database connectivity

Keep the abstraction level focused on the architectural components while including enough detail to show the sophisticated type-safety and validation mechanisms that make this library unique.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Style definitions
    classDef core fill:#a8d1f0,stroke:#2980b9,stroke-width:2px
    classDef external fill:#e0e0e0,stroke:#666666,stroke-width:1px
    classDef database fill:#d5b8e6,stroke:#8e44ad,stroke-width:2px
    classDef client fill:#a8e6cf,stroke:#2ecc71,stroke-width:2px
    classDef validation fill:#ffd3b6,stroke:#e67e22,stroke-width:2px
    
    %% Client Layer
    subgraph ClientLayer
        Client["Client Application"]:::client
        Examples["Implementation Examples"]:::client
    end
    
    %% Core Layer
    subgraph CoreLayer
        %% Model Metadata System
        ModelMetadata["Model Metadata System"]:::core
        Registry["Model Registration"]:::core
        FieldMapping["Field Mapping"]:::core
        TypeValidation["Type Validation"]:::core
        
        %% Query Builder System
        QueryBuilder["Query Builder System"]:::core
        StructuredQuery["Structured Query Building"]:::core
        ParamBinding["Parameter Binding"]:::core
        PaginationHandler["Pagination Handler"]:::core
        OrderHandler["Order By Handler"]:::core
        
        %% Executor System
        Executor["Executor System"]:::core
        ResultMapping["Result Mapping"]:::core
        PaginationProc["Pagination Processing"]:::core
        
        %% Safe Raw Query System
        SafeRaw["Safe Raw Query System"]:::core
        ParamValidation["Parameter Validation"]:::validation
        SQLValidation["SQL Syntax Validation"]:::validation
        TypeCheck["Type Checking"]:::validation
    end
    
    %% External Dependencies
    subgraph Dependencies
        Squirrel["squirrel"]:::external
        PGParser["PostgreSQL Parser"]:::external
        Scany["scany"]:::external
    end
    
    %% Database Layer
    subgraph DatabaseLayer
        DBConnectors["Database Connectors"]:::database
        PostgreSQL["PostgreSQL"]:::database
    end
    
    %% Relationships
    Client --> ModelMetadata
    Client --> QueryBuilder
    Client --> SafeRaw
    Examples --> QueryBuilder
    
    ModelMetadata --> Registry
    Registry --> FieldMapping
    FieldMapping --> TypeValidation
    
    QueryBuilder --> StructuredQuery
    StructuredQuery --> ParamBinding
    StructuredQuery --> PaginationHandler
    StructuredQuery --> OrderHandler
    
    SafeRaw --> ParamValidation
    SafeRaw --> SQLValidation
    SafeRaw --> TypeCheck
    
    QueryBuilder --> Executor
    SafeRaw --> Executor
    Executor --> ResultMapping
    Executor --> PaginationProc
    
    Executor --> DBConnectors
    DBConnectors --> PostgreSQL
    
    %% External Dependencies Connections
    QueryBuilder --> Squirrel
    SafeRaw --> PGParser
    Executor --> Scany
    
    %% Click Events
    click QueryBuilder "https://github.com/remiges-tech/sqld/blob/main/builder.go"
    click Executor "https://github.com/remiges-tech/sqld/blob/main/executor.go"
    click SafeRaw "https://github.com/remiges-tech/sqld/blob/main/safequery.go"
    click ModelMetadata "https://github.com/remiges-tech/sqld/blob/main/registry.go"
    click PaginationHandler "https://github.com/remiges-tech/sqld/blob/main/pagination.go"
    click TypeValidation "https://github.com/remiges-tech/sqld/blob/main/validator.go"
    click TypeCheck "https://github.com/remiges-tech/sqld/blob/main/types.go"
    click Examples "https://github.com/remiges-tech/sqld/blob/main/examples/main.go"
    click DBConnectors "https://github.com/remiges-tech/sqld/tree/main/examples/db/migrations/"
    click PostgreSQL "https://github.com/remiges-tech/sqld/blob/main/examples/db/sqlc-gen/models.go"
    
    %% Legend
    subgraph Legend
        L1["Core Components"]:::core
        L2["External Dependencies"]:::external
        L3["Database Layer"]:::database
        L4["Client Layer"]:::client
        L5["Validation Components"]:::validation
    end
```
