# izadoesdev/clickquery architecture

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

- Interactive diagram: https://gitdiagram.com/izadoesdev/clickquery
- Repository: https://github.com/izadoesdev/clickquery

## Overview

##### Project Type & Purpose
- ClickQuery is an open‑source TypeScript library (minimal ORM/query builder) for ClickHouse.
- It provides a fluent API to define schemas, build type‑safe SQL queries, and execute them via HTTP(S).

##### High‑Level Components
a. Developer Application
- Your application code that imports `@clickquery/core`.
- Defines models, invokes `createClient`, and issues queries/inserts.
b. ClickQuery Library (packages/core)
1. Client Module (`src/client`)
– `createClient` & HTTP transport layer: configures host, credentials, settings.
– Sends built SQL to ClickHouse’s REST API; parses responses.
2. Schema Definition (`src/schema`)
– `defineModel`: declarative table definitions (columns, engines, partitions).
– Types (`types/*`), validation, migrations scaffolding.
3. Fluent Query Builder (`src/index.ts`, part of core)
– Chainable methods: `.select()`, `.where()`, `.insert()`, etc.
– Produces SQL strings + parameter binding.
4. Type Inference (`src/types` + utility types)
– `InferModelType`: maps schema definitions to TypeScript row types.
5. Utilities (`src/utils`)
– Helpers (UUID generation, date formatting).
6. Tests (`src/tests`)
– Unit tests for each component (client, schema, migrations).
c. External Service
- ClickHouse Database
– Receives SQL via HTTP(S), executes queries, returns JSON/CSV.

##### Relationships & Data Flows
- Application → Client: calls `createClient(config)`.
- Application → Schema API: defines models via `defineModel(...)`.
- Application → Query Builder: chains calls (`db.select(...)`, `db.insert(...)`).
- Query Builder → Client: hands off generated SQL + parameters.
- Client → ClickHouse: HTTP request with SQL payload.
- ClickHouse → Client: HTTP response (rows or insertion status).
- Client → Application: returns typed results (`InferModelType<T>`).

##### Architectural Patterns & Principles
- Layered Modular Design: separation between Client, Schema, Query Builder, Type System, Utilities.
- Monorepo Structure: `packages/core` houses the library; allows future packages (e.g., CLI, migrations).
- Type‑First Approach: heavy use of TypeScript’s type inference for end‑to‑end safety.
- Minimal Abstraction: keeps close to ClickHouse concepts (engines, data types).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Developer Application"
        direction TB
        App["Application Code"]:::app
    end

    subgraph "ClickQuery Library (packages/core)"
        direction TB

        subgraph "Client Module"
            direction TB
            Client["Client Module"]:::client
            Ch["HTTP Transport (ch.ts)"]:::client
        end

        subgraph "Schema Definition"
            direction TB
            Define["defineModel"]:::schema
            DBSchema["database.ts"]:::schema
            Migration["migration.ts"]:::schema
            Validation["validation.ts"]:::schema
            Shared["shared/index.ts"]:::schema
            TypesDir["types/"]:::schema
        end

        Query["Query Builder"]:::schema
        Config["config.ts"]:::schema

        subgraph "Type System"
            direction TB
            Infer["infer.ts"]:::types
            ClientTypes["client.ts"]:::types
        end

        subgraph "Utilities"
            direction TB
            ID["id.ts"]:::utils
            DateTime["datetime.ts"]:::utils
            UtilsIndex["index.ts"]:::utils
        end

        subgraph "Tests"
            direction TB
            TestClient["client.test.ts"]:::tests
            TestDB["database.test.ts"]:::tests
            TestMig["migration.test.ts"]:::tests
            TestSchema["schema.test.ts"]:::tests
            TestSetup["setup.ts"]:::tests
        end
    end

    ClickHouse[(ClickHouse DB)]:::db

    App -->|"defineModel()"| Define
    App -->|"createClient()"| Client
    App -->|".select(), .insert()"| Query

    Query -->|"SQL + params"| Client
    Client -->|"HTTP POST"| ClickHouse
    ClickHouse -->|"JSON/CSV"| Client
    Client -->|"typed results"| App

    click Client "https://github.com/izadoesdev/clickquery/tree/master/packages/core/src/client"
    click Ch "https://github.com/izadoesdev/clickquery/blob/master/packages/core/src/client/ch.ts"
    click Define "https://github.com/izadoesdev/clickquery/blob/master/packages/core/src/schema/defineModel.ts"
    click DBSchema "https://github.com/izadoesdev/clickquery/blob/master/packages/core/src/schema/database.ts"
    click Migration "https://github.com/izadoesdev/clickquery/blob/master/packages/core/src/schema/migration.ts"
    click Validation "https://github.com/izadoesdev/clickquery/blob/master/packages/core/src/schema/validation.ts"
    click Shared "https://github.com/izadoesdev/clickquery/blob/master/packages/core/src/schema/shared/index.ts"
    click TypesDir "https://github.com/izadoesdev/clickquery/tree/master/packages/core/src/schema/types"
    click Query "https://github.com/izadoesdev/clickquery/blob/master/packages/core/src/index.ts"
    click Infer "https://github.com/izadoesdev/clickquery/blob/master/packages/core/src/types/infer.ts"
    click ClientTypes "https://github.com/izadoesdev/clickquery/blob/master/packages/core/src/types/client.ts"
    click ID "https://github.com/izadoesdev/clickquery/blob/master/packages/core/src/utils/id.ts"
    click DateTime "https://github.com/izadoesdev/clickquery/blob/master/packages/core/src/utils/datetime.ts"
    click UtilsIndex "https://github.com/izadoesdev/clickquery/blob/master/packages/core/src/utils/index.ts"
    click Config "https://github.com/izadoesdev/clickquery/blob/master/packages/core/src/config.ts"
    click TestClient "https://github.com/izadoesdev/clickquery/blob/master/packages/core/src/tests/client.test.ts"
    click TestDB "https://github.com/izadoesdev/clickquery/blob/master/packages/core/src/tests/database.test.ts"
    click TestMig "https://github.com/izadoesdev/clickquery/blob/master/packages/core/src/tests/migration.test.ts"
    click TestSchema "https://github.com/izadoesdev/clickquery/blob/master/packages/core/src/tests/schema.test.ts"
    click TestSetup "https://github.com/izadoesdev/clickquery/blob/master/packages/core/src/tests/setup.ts"

    classDef app stroke-dasharray: 5,5 fill:#ffffff,stroke:#000000
    classDef client fill:#ADD8E6,stroke:#000000
    classDef schema fill:#90EE90,stroke:#000000
    classDef types fill:#FFFFE0,stroke:#000000
    classDef utils fill:#D3D3D3,stroke:#000000
    classDef db fill:#FFA500,stroke:#000000
    classDef tests fill:#f5f5f5,stroke:#000000
```
