# l1xnan/duckling architecture

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

- Interactive diagram: https://gitdiagram.com/l1xnan/duckling
- Repository: https://github.com/l1xnan/duckling

## Overview

##### Project type and purpose
- Duckling is a desktop “full-stack” application built with Tauri.
- Its goal is to let users quickly browse Parquet/CSV files and query several databases (DuckDB, SQLite, PostgreSQL, MySQL, ClickHouse, Doris/StarRocks).

##### High-level architecture overview
a. User Interface (UI) Layer
b. IPC / Tauri Command Layer
c. Backend Library Layer
d. Data Sources Layer

##### Main components
a. UI Layer (src/ + public + index.html)
- Built with Vite, React, TypeScript.
- Pages (`src/pages`), Components (`src/components`), Hooks (`src/hooks`), State Stores (`src/stores`).
- Assets (`src/assets`, `assets/`) and global styles.

b. IPC / Tauri Command Layer (src-tauri)
- `src-tauri/src/main.rs`: Tauri setup & WebView host.
- `src-tauri/src/cmd.rs`: defines commands exposed to the UI (e.g., open file, run query).
- `tauri.conf.json`, build scripts.

c. Backend Library Layer (connector crate)
- `connector/src/lib.rs`: public API the Tauri commands call.
- Dialect modules (`connector/src/dialect/*`): ClickHouse, DuckDB, MySQL, PostgreSQL, SQLite, File, Folder.
- Common utilities (`types.rs`, `utils.rs`, `api.rs`).

d. Data Sources Layer
- Local file system: Parquet/CSV (handled by File and Folder dialects).
- Embedded DB: DuckDB, SQLite.
- External DBs: PostgreSQL, MySQL (including Doris/StarRocks compatibility), ClickHouse (native port).

##### Relationships & data flows
- UI triggers user actions (open folder, run SQL).
- UI → sends `invoke` call over Tauri IPC → Tauri Command Layer.
- Command Layer → calls functions in the `connector` library.
- Connector routes to appropriate dialect module → interacts with the data source.
- Results (tables/JSON) return up the stack → UI renders via React components.

##### Architectural patterns & principles
- Clear separation of concerns:
- Presentation (React) vs. business logic (connector) vs. host environment (Tauri).
- Asynchronous, request-response model over a secure IPC channel.

##### Relevant technologies & libraries
- Frontend: React, Vite, TypeScript, Zustand (or similar) for state, Monaco editor integration, Tailwind or CSS modules.
- Backend: Tauri (Rust), Tokio (async), crates for each database (e.g., `duckdb-rs`, `rusqlite`, `tokio-postgres`, `mysql_async`, `clickhouse-rs`), Parquet reader.
- Build & config: Cargo, pnpm, ESLint, Prettier, GitHub Actions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "User Interface Layer"
        direction TB
        MainTSX["main.tsx"]:::ui
        AppTSX["App.tsx"]:::ui
        Pages["src/pages/"]:::ui
        Components["src/components/"]:::ui
        Hooks["src/hooks/"]:::ui
        Stores["src/stores/"]:::ui
        Assets["src/assets/"]:::ui
        PublicDir["public/"]:::ui
        IndexHTML["index.html"]:::ui
    end

    %% IPC / Tauri Command Layer
    subgraph "IPC / Tauri Command Layer"
        direction TB
        MainRS["main.rs"]:::ipc
        CmdRS["cmd.rs"]:::ipc
        TauriConf["tauri.conf.json"]:::ipc
        BuildRS["build.rs"]:::ipc
        CargoTauri["Cargo.toml"]:::ipc
    end

    %% Connector Library Layer
    subgraph "Connector Library Layer"
        direction TB
        LibRS["lib.rs"]:::connector
        API["api.rs"]:::connector
        Utils["utils.rs"]:::connector
        Types["types.rs"]:::connector
        DialectMod["mod.rs"]:::connector
    end

    %% Dialect Modules
    subgraph "Dialect Modules"
        direction TB
        CH["clickhouse/mod.rs"]:::dialect
        DB["duckdb/mod.rs"]:::dialect
        FileDM["file/mod.rs"]:::dialect
        FolderDM["folder/mod.rs"]:::dialect
        MySQL["mysql/mod.rs"]:::dialect
        Postgres["postgres/mod.rs"]:::dialect
        SQLiteDM["sqlite/mod.rs"]:::dialect
        AST["ast.rs"]:::dialect
    end

    %% Data Sources Layer
    subgraph "Data Sources Layer"
        direction TB
        FileDS["Parquet/CSV (File)"]:::datasource
        FolderDS["Folder Browse"]:::datasource
        DuckDBDS["DuckDB"]:::datasource
        SQLiteDS["SQLite"]:::datasource
        PostgresDS["PostgreSQL"]:::datasource
        MySQLDS["MySQL / Doris/StarRocks"]:::datasource
        CHDS["ClickHouse"]:::datasource
    end

    %% Connections
    MainTSX -->|"invoke(cmd)"| MainRS
    AppTSX --> MainRS
    Pages --> MainRS
    Components --> MainRS
    Hooks --> MainRS
    Stores --> MainRS
    MainRS -->|"runCommand()"| LibRS
    CmdRS --> LibRS
    LibRS --> DialectMod
    API --> DialectMod
    Utils --> DialectMod
    Types --> DialectMod
    DialectMod --> CH
    DialectMod --> DB
    DialectMod --> FileDM
    DialectMod --> FolderDM
    DialectMod --> MySQL
    DialectMod --> Postgres
    DialectMod --> SQLiteDM
    DialectMod --> AST

    CH --> CHDS
    DB --> DuckDBDS
    FileDM --> FileDS
    FolderDM --> FolderDS
    MySQL --> MySQLDS
    Postgres --> PostgresDS
    SQLiteDM --> SQLiteDS
    AST --> FileDM

    %% Return flow
    CHDS -->|"result"| LibRS
    DuckDBDS --> LibRS
    FileDS --> LibRS
    FolderDS --> LibRS
    MySQLDS --> LibRS
    PostgresDS --> LibRS
    SQLiteDS --> LibRS
    LibRS --> MainRS
    MainRS --> MainTSX

    %% Click Events
    click MainTSX "https://github.com/l1xnan/duckling/blob/main/src/main.tsx"
    click AppTSX "https://github.com/l1xnan/duckling/blob/main/src/App.tsx"
    click Pages "https://github.com/l1xnan/duckling/tree/main/src/pages/"
    click Components "https://github.com/l1xnan/duckling/tree/main/src/components/"
    click Hooks "https://github.com/l1xnan/duckling/tree/main/src/hooks/"
    click Stores "https://github.com/l1xnan/duckling/tree/main/src/stores/"
    click Assets "https://github.com/l1xnan/duckling/tree/main/src/assets/"
    click PublicDir "https://github.com/l1xnan/duckling/tree/main/public/"
    click IndexHTML "https://github.com/l1xnan/duckling/blob/main/index.html"
    click MainRS "https://github.com/l1xnan/duckling/blob/main/src-tauri/src/main.rs"
    click CmdRS "https://github.com/l1xnan/duckling/blob/main/src-tauri/src/cmd.rs"
    click TauriConf "https://github.com/l1xnan/duckling/blob/main/src-tauri/tauri.conf.json"
    click BuildRS "https://github.com/l1xnan/duckling/blob/main/src-tauri/build.rs"
    click CargoTauri "https://github.com/l1xnan/duckling/blob/main/src-tauri/Cargo.toml"
    click LibRS "https://github.com/l1xnan/duckling/blob/main/connector/src/lib.rs"
    click API "https://github.com/l1xnan/duckling/blob/main/connector/src/api.rs"
    click Utils "https://github.com/l1xnan/duckling/blob/main/connector/src/utils.rs"
    click Types "https://github.com/l1xnan/duckling/blob/main/connector/src/types.rs"
    click DialectMod "https://github.com/l1xnan/duckling/blob/main/connector/src/dialect/mod.rs"
    click CH "https://github.com/l1xnan/duckling/blob/main/connector/src/dialect/clickhouse/mod.rs"
    click DB "https://github.com/l1xnan/duckling/blob/main/connector/src/dialect/duckdb/mod.rs"
    click FileDM "https://github.com/l1xnan/duckling/blob/main/connector/src/dialect/file/mod.rs"
    click FolderDM "https://github.com/l1xnan/duckling/blob/main/connector/src/dialect/folder/mod.rs"
    click MySQL "https://github.com/l1xnan/duckling/blob/main/connector/src/dialect/mysql/mod.rs"
    click Postgres "https://github.com/l1xnan/duckling/blob/main/connector/src/dialect/postgres/mod.rs"
    click SQLiteDM "https://github.com/l1xnan/duckling/blob/main/connector/src/dialect/sqlite/mod.rs"
    click AST "https://github.com/l1xnan/duckling/blob/main/connector/src/dialect/ast.rs"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#2a7fdb,stroke-width:2px
    classDef ipc fill:#d4edda,stroke:#28a745,stroke-width:2px
    classDef connector fill:#fff3cd,stroke:#ffca2c,stroke-width:2px
    classDef dialect fill:#f8d7da,stroke:#db3545,stroke-width:2px
    classDef datasource fill:#e2e3e5,stroke:#6c757d,stroke-width:2px
```
