# jeukshi/kosem architecture

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

- Interactive diagram: https://gitdiagram.com/jeukshi/kosem
- Repository: https://github.com/jeukshi/kosem

## Overview

##### Main Components

a) Core Layer (kosem-core):
- Record management components
- Core interfaces and types

b) PostgreSQL Layer (kosem-postgresql):
- This as a middle layer
- Following sub-components:
- SQL Parser & Typechecker
- Schema Management
- Connection Handling
- Field Conversion (To/From)
- PostgreSQL Type System

c) User Application Layer:
- This at the top
- How it interfaces with the library

##### Component Relationships

- Internal connections between PostgreSQL Layer components:
- Parser → Typechecker
- Schema Management → SQL Generation
- Connection Handler → Field Conversion

##### Specific Component Details

PostgreSQL Layer:

- PostgreSQL Layer     |

- SQL Parser          |
- Typechecker         |
- Schema Management   |
- Connection Handler  |
- Field Conversion    |
- Type System         |

Core Layer:

- Core Layer        |

- Record Management   |
- Type Definitions    |
- Core Interfaces     |

##### Important Elements to Highlight

- Type-safety mechanisms
- SQL query flow from raw string to executed query
- Record mapping process
- Schema validation and generation
- Error handling and diagnostics flow

##### Technical Details

- Template Haskell usage points
- Type system integration
- PostgreSQL type categories
- Parser and typechecker pipeline

**[User Application]**
- ↓
**[Query Parsing & Validation]**
- ↓
**[Type Checking & Schema Validation]**
- ↓
**[Connection Management]**
- ↓
**[Field Conversion]**
- ↓
**[PostgreSQL Database]**

##### The compile-time safety mechanisms

This design should reflect both the current implementation (as seen in the file structure) and the library's core purpose of providing type-safe SQL operations in Haskell.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Styles
    classDef core fill:#b3d1ff,stroke:#333
    classDef postgresql fill:#90EE90,stroke:#333
    classDef user fill:#FFE5B4,stroke:#333
    classDef database fill:#D3D3D3,stroke:#333
    classDef error fill:#FFB6C1,stroke:#333

    %% User Application Layer
    subgraph UserLayer
        UA[User Application]:::user
    end

    %% PostgreSQL Layer
    subgraph PostgreSQLLayer
        Parser["SQL Parser"]:::postgresql
        TypeChecker["SQL Typechecker"]:::postgresql
        SchemaManager["Schema Management"]:::postgresql
        ConnHandler["Connection Handler"]:::postgresql
        FieldConv["Field Conversion"]:::postgresql
        PgTypeSystem["PostgreSQL Type System"]:::postgresql
        THIntegration["Template Haskell Integration"]:::postgresql
        Diagnostics["Diagnostics System"]:::postgresql
        
        %% Internal PostgreSQL Layer connections
        Parser --> TypeChecker
        TypeChecker --> SchemaManager
        SchemaManager --> ConnHandler
        ConnHandler --> FieldConv
        PgTypeSystem --> TypeChecker
        THIntegration --> Parser
        THIntegration --> SchemaManager
    end

    %% Core Layer
    subgraph CoreLayer
        RecordMgmt["Record Management"]:::core
        TypeDefs["Type Definitions"]:::core
        CoreInterfaces["Core Interfaces"]:::core
    end

    %% External Database
    DB[(PostgreSQL Database)]:::database

    %% Cross-layer connections
    UA --> Parser
    FieldConv --> RecordMgmt
    ConnHandler --> DB
    DB --> ConnHandler
    
    %% Error handling paths
    Diagnostics --> UA
    TypeChecker --> Diagnostics
    SchemaManager --> Diagnostics

    %% Click events for component mapping
    click RecordMgmt "https://github.com/jeukshi/kosem/blob/main/kosem-core/src/Database/Kosem/Record.hs"
    click Parser "https://github.com/jeukshi/kosem/blob/main/kosem-postgresql/src/Database/Kosem/PostgreSQL/Internal/Sql/Parser.hs"
    click TypeChecker "https://github.com/jeukshi/kosem/blob/main/kosem-postgresql/src/Database/Kosem/PostgreSQL/Internal/Sql/Typechecker.hs"
    click SchemaManager "https://github.com/jeukshi/kosem/tree/main/kosem-postgresql/src/Database/Kosem/PostgreSQL/Schema/Internal"
    click ConnHandler "https://github.com/jeukshi/kosem/blob/main/kosem-postgresql/src/Database/Kosem/PostgreSQL/Internal/Connection.hs"
    click FieldConv "https://github.com/jeukshi/kosem/blob/main/kosem-postgresql/src/Database/Kosem/PostgreSQL/Internal/FromField.hs"
    click PgTypeSystem "https://github.com/jeukshi/kosem/blob/main/kosem-postgresql/src/Database/Kosem/PostgreSQL/Internal/PgType.hs"
    click THIntegration "https://github.com/jeukshi/kosem/blob/main/kosem-postgresql/src/Database/Kosem/PostgreSQL/Internal/Sql/TH.hs"
    click Diagnostics "https://github.com/jeukshi/kosem/tree/main/kosem-postgresql/src/Database/Kosem/PostgreSQL/Internal/Diagnostics"
```
