# abelcha/buckdb architecture

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

- Interactive diagram: https://gitdiagram.com/abelcha/buckdb
- Repository: https://github.com/abelcha/buckdb

## Overview

##### Project Type & Purpose
- BuckDB is a TypeScript/JavaScript library (NPM package) that provides a fluent API for building SQL queries.
- It ships two runtime back-ends:
– Node.js adapter via @duckdb/node-api
– WASM adapter via @duckdb/duckdb-wasm
- It also includes a standalone demo application (web UI built with Vite) and CLI scripts (demo.ts, demo_showcase.ts) that showcase the library.

##### Top-Level Components (from file tree)
- Core Library (src/)
– Parser & AST (jsep.ts, parser.ts)
– Query Builder & Fluent API (build.ts, copy.ts, serializers, interface-generator.ts)
– Type System & Sync (type-system, sync-types.ts)
– Utility modules (readers.ts, utils.ts)
- Entry Points
– buckdb.ts (Node.js adapter entry)
– buckdb.wasm.ts (WASM adapter entry)
- Demo Application (demo/)
– Frontend (HTML, CSS, Vite config)
– Features modules (intellisense, debugger, editor, terminal, etc.)
– Web Workers (crossOriginWorker.ts, extHostWorker.ts, fakeWorker.ts)
- CLI Scripts (demo.ts, demo_showcase.ts)
- Config & Build files (tsconfig.json, package.json, bun.lockb, dprint.json)

##### Key Architectural Patterns & Principles
- Adapter Pattern – isolates the DuckDB back-end (Node vs WASM) behind a common API.
- Layered Modular Design –
– Layer 1: Public API (from(), copy())
– Layer 2: Core engine (parser → builder → serializer)
– Layer 3: Runtime backend (DuckDB node-api or WASM)
– Layer 4: I/O sinks (filesystem, HTTP(S), S3, in-memory)
- Separation of Concerns – demo UI is fully decoupled from core library code.
- Plugin-style extension for DuckDB functions (D.* in where()/select()).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Consumers
    subgraph "Consumers"
        CLI["CLI Scripts"]:::demo
        DemoUI["Demo Web App"]:::demo
    end

    %% Entry Points
    NodeEntry["Node.js Adapter Entry\n(buckdb.ts)"]:::adapter
    WASMEntry["WASM Adapter Entry\n(buckdb.wasm.ts)"]:::adapter

    %% Public API Layer
    subgraph "Public API Layer"
        API["from()/copy()"]:::core
    end

    %% Core Engine Layer
    subgraph "Core Engine Layer"
        subgraph "Parser & AST"
            JSEP["jsep.ts"]:::core
            PARSER["parser.ts"]:::core
        end
        subgraph "Query Builder & Fluent API"
            BUILD["build.ts"]:::core
            COPYMOD["copy.ts"]:::core
            SERIALIZER["serializer.ts"]:::core
            INTGEN["interface-generator.ts"]:::core
        end
        subgraph "Type System & Sync"
            SYNC["sync-types.ts"]:::core
            TYPEDEF["typedef.ts"]:::core
        end
        subgraph "Utility Modules"
            READERS["readers.ts"]:::core
            UTILS["utils.ts"]:::core
        end
    end

    %% Adapter Layer
    NodeAdapter["DuckDB Node Adapter\n(@duckdb/node-api)"]:::adapter
    WASMAdapter["DuckDB WASM Adapter\n(@duckdb/duckdb-wasm)"]:::adapter

    %% External Systems & Data Sources
    subgraph "External Systems"
        DuckDBEngine["DuckDB Engine"]:::external
        DataSources["Data Sources\n(CSV/Parquet/JSON, S3, HTTP)"]:::external
    end

    %% Demo UI Workers
    subgraph "Web Workers"
        CROSS["crossOriginWorker.ts"]:::demo
        EXTHOST["extHostWorker.ts"]:::demo
        FAKE["fakeWorker.ts"]:::demo
    end

    %% Config & Build
    subgraph "Config & Build Files"
        TSCROOT["tsconfig.json"]:::external
        TSCDEMO["demo/tsconfig.json"]:::external
        PKG["package.json"]:::external
        BUN["bun.lockb"]:::external
        DPRINT["dprint.json"]:::external
    end

    %% Demo App Config & Features
    subgraph "Demo App Files"
        HTML["index.html"]:::demo
        VITE1["vite.config.ts"]:::demo
        VITE2["vite.netlify.config.ts"]:::demo
        FEATURES["Feature Modules"]:::demo
        MAINC["main.common.ts"]:::demo
        MAINS["main.v2.ts"]:::demo
        MAINV["main.views.ts"]:::demo
    end

    %% Connections
    CLI -->|uses| NodeEntry
    DemoUI -->|uses| WASMEntry
    NodeEntry -->|initializes| API
    WASMEntry -->|initializes| API
    API -->|parses| JSEP
    API -->|parses| PARSER
    API -->|builds| BUILD
    API -->|builds| COPYMOD
    API -->|serializes| SERIALIZER
    API -->|generates| INTGEN
    API -->|syncs| SYNC
    API -->|types| TYPEDEF
    API -->|reads| READERS
    API -->|utils| UTILS
    API -->|calls| NodeAdapter
    API -->|calls| WASMAdapter
    NodeAdapter -->|executes| DuckDBEngine
    WASMAdapter -->|executes| DuckDBEngine
    DuckDBEngine -->|reads/writes| DataSources
    DEMO_DEPS["Demo UI"] -->|spawns| CROSS
    DEMO_DEPS -->|spawns| EXTHOST
    DEMO_DEPS -->|spawns| FAKE

    %% Click Events
    click JSEP "https://github.com/abelcha/buckdb/blob/master/src/jsep.ts"
    click PARSER "https://github.com/abelcha/buckdb/blob/master/src/parser.ts"
    click BUILD "https://github.com/abelcha/buckdb/blob/master/src/build.ts"
    click COPYMOD "https://github.com/abelcha/buckdb/blob/master/src/copy.ts"
    click SERIALIZER "https://github.com/abelcha/buckdb/blob/master/src/serializer.ts"
    click INTGEN "https://github.com/abelcha/buckdb/blob/master/src/interface-generator.ts"
    click SYNC "https://github.com/abelcha/buckdb/blob/master/src/sync-types.ts"
    click TYPEDEF "https://github.com/abelcha/buckdb/blob/master/src/typedef.ts"
    click READERS "https://github.com/abelcha/buckdb/blob/master/src/readers.ts"
    click UTILS "https://github.com/abelcha/buckdb/blob/master/src/utils.ts"
    click NodeEntry "https://github.com/abelcha/buckdb/blob/master/buckdb.ts"
    click WASMEntry "https://github.com/abelcha/buckdb/blob/master/buckdb.wasm.ts"
    click HTML "https://github.com/abelcha/buckdb/blob/master/demo/index.html"
    click VITE1 "https://github.com/abelcha/buckdb/blob/master/demo/vite.config.ts"
    click VITE2 "https://github.com/abelcha/buckdb/blob/master/demo/vite.netlify.config.ts"
    click FEATURES "https://github.com/abelcha/buckdb/tree/master/demo/src/features"
    click MAINC "https://github.com/abelcha/buckdb/blob/master/demo/src/main.common.ts"
    click MAINS "https://github.com/abelcha/buckdb/blob/master/demo/src/main.v2.ts"
    click MAINV "https://github.com/abelcha/buckdb/blob/master/demo/src/main.views.ts"
    click CROSS "https://github.com/abelcha/buckdb/blob/master/demo/src/tools/crossOriginWorker.ts"
    click EXTHOST "https://github.com/abelcha/buckdb/blob/master/demo/src/tools/extHostWorker.ts"
    click FAKE "https://github.com/abelcha/buckdb/blob/master/demo/src/tools/fakeWorker.ts"
    click CLI "https://github.com/abelcha/buckdb/blob/master/demo.ts"
    click CLI "https://github.com/abelcha/buckdb/blob/master/demo_showcase.ts"
    click TSCROOT "https://github.com/abelcha/buckdb/blob/master/tsconfig.json"
    click TSCDEMO "https://github.com/abelcha/buckdb/blob/master/demo/tsconfig.json"
    click PKG "https://github.com/abelcha/buckdb/blob/master/package.json"
    click BUN "https://github.com/abelcha/buckdb/blob/master/bun.lockb"
    click DPRINT "https://github.com/abelcha/buckdb/blob/master/dprint.json"

    %% Styles
    classDef core fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef adapter fill:#D8F5D8,stroke:#333,stroke-width:1px
    classDef external fill:#FFE0B2,stroke:#333,stroke-width:1px
    classDef demo fill:#F3E5F5,stroke:#333,stroke-width:1px
```
