# electric-sql/pglite architecture

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

- Interactive diagram: https://gitdiagram.com/electric-sql/pglite
- Repository: https://github.com/electric-sql/pglite

## Overview

##### Project type and purpose
- This is a multi‐package monorepo hosting an open‐source library/tool: a WASM-compiled build of PostgreSQL (PGlite) plus a TypeScript client and related extension packages (React, Vue, web-REPL, sync engine, CLI tools, protocol layer).
- Its primary use case is embedding a single-user Postgres instance in browser/Node/Deno/Bun applications, with optional persistence (IndexedDB or file system) and wrappers for various frameworks.

##### File structure
- Top‐level “packages/” folder holds independent npm packages:
- packages/pglite – core WASM+TS client and FS abstraction
- packages/pg-protocol – low-level message parser/serializer for Postgres wire protocol
- packages/pglite-react / pglite-vue – React/Vue hook providers
- packages/pglite-repl – web component UI for SQL REPL
- packages/pglite-sync – synchronization engine for multi-tab or client-server syncing
- packages/pglite-tools – CLI scripts (bundle-WASM, pg_dump integration)
- packages/benchmark – performance test harness
- “docs/” and “examples/” directories provide documentation site and runnable sample apps.
- Build/config files: Dockerfiles (implied), pnpm-workspace.yaml, GitHub Actions workflow, tsconfig/tup.config/vitest.config in each package.

##### README for additional insights
- Describes two-stage build: (1) Docker/Emscripten → Postgres WASM module → copied to packages/pglite/release; (2) pnpm builds TypeScript packages in dependency order.
- Runtime environments: browser IndexedDB, Node FS, Bun, Deno.
- Extensions support via “packages/pglite/src/contrib” and FS plugins under “src/fs/”.

##### Elements
- Clear labels: “Docker/Emscripten”, “WASM Module”, “TS Bundler”, “pnpm Workspace”, “Core Client”, “Protocol Layer”, “React Hooks”, “Vue Hooks”, “REPL WebComponent”, “Sync Engine”, “FS Abstraction”, “IndexedDB”, “Node FS”
- Runtime hosts (rounded rectangles)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build Pipeline
    subgraph "Build Pipeline"
        Docker["Docker/Emscripten"]:::build
        TSBundle["TS Bundler (tsup + pnpm)"]:::build
        CICD["CI/CD (GitHub Actions)"]:::build
    end

    %% Package Modules
    subgraph "Package Modules"
        Core["Core WASM Client\n(packages/pglite)"]:::package
        Protocol["Protocol Layer\n(packages/pg-protocol)"]:::package
        subgraph "Wrappers"
            React["React Hooks"]:::package
            Vue["Vue Hooks"]:::package
            REPL["REPL WebComponent"]:::package
            Sync["Sync Engine"]:::package
        end
        Tools["CLI Tools"]:::package
        Benchmark["Benchmark Harness"]:::package
    end

    %% Runtime Environment
    subgraph "Runtime Environment"
        Browser["Browser Host"]:::runtime
        Node["Node/Bun/Deno Host"]:::runtime
        FSAbstraction["FS Abstraction Layer"]:::runtime
        IndexedDB["IndexedDB"]:::storage
        NodeFS["Node FS"]:::storage
    end

    %% External Services
    subgraph "External Services"
        NPM["npm Registry"]:::external
        DockerHub["Docker Hub"]:::external
        GitHub["GitHub"]:::external
    end

    %% Build Flow
    GitHub -->|"source + CI trigger"| CICD
    CICD --> Docker
    Docker -->|"produce WASM artifact"| Core
    CICD --> TSBundle
    TSBundle --> Core
    TSBundle --> Protocol
    TSBundle --> React
    TSBundle --> Vue
    TSBundle --> REPL
    TSBundle --> Sync
    TSBundle --> Tools
    TSBundle --> Benchmark
    TSBundle --> NPM
    DockerHub -.-> Docker

    %% Package Dependencies
    Core --> Protocol
    React --> Core
    Vue --> Core
    REPL --> Core
    Sync --> Core
    Tools --> Core
    Benchmark --> Core

    %% Runtime Flow
    Browser --> React
    Browser --> Vue
    Browser --> REPL
    Browser --> Sync
    Browser --> Core
    Node --> React
    Node --> Vue
    Node --> REPL
    Node --> Sync
    Node --> Core

    Core -->|"FS operations"| FSAbstraction
    FSAbstraction --> IndexedDB
    FSAbstraction --> NodeFS

    %% Publishing
    Core --> NPM
    Protocol --> NPM
    React --> NPM
    Vue --> NPM
    REPL --> NPM
    Sync --> NPM
    Tools --> NPM
    Benchmark --> NPM

    %% Click Events
    click Docker "https://github.com/electric-sql/pglite/blob/main/packages/pglite/scripts/bundle-wasm.ts"
    click TSBundle "https://github.com/electric-sql/pglite/blob/main/pnpm-workspace.yaml"
    click CICD "https://github.com/electric-sql/pglite/blob/main/.github/workflows/build_and_test.yml"
    click Core "https://github.com/electric-sql/pglite/tree/main/packages/pglite"
    click Protocol "https://github.com/electric-sql/pglite/tree/main/packages/pg-protocol"
    click React "https://github.com/electric-sql/pglite/tree/main/packages/pglite-react/src"
    click Vue "https://github.com/electric-sql/pglite/tree/main/packages/pglite-vue/src"
    click REPL "https://github.com/electric-sql/pglite/tree/main/packages/pglite-repl/src-webcomponent"
    click Sync "https://github.com/electric-sql/pglite/tree/main/packages/pglite-sync/src"
    click Tools "https://github.com/electric-sql/pglite/blob/main/packages/pglite-tools/scripts/bundle-wasm.ts"
    click Benchmark "https://github.com/electric-sql/pglite/tree/main/packages/benchmark/src"
    click FSAbstraction "https://github.com/electric-sql/pglite/tree/main/packages/pglite/src/fs"
    click NPM "https://github.com/electric-sql/pglite/blob/main/pnpm-workspace.yaml"

    %% Styles
    classDef build fill:#ececec,stroke:#333,stroke-width:1px
    classDef package fill:#cce5ff,stroke:#0366d6,stroke-width:1px
    classDef runtime fill:#d4edda,stroke:#155724,stroke-width:1px
    classDef storage fill:#f8d7da,stroke:#721c24,stroke-width:1px
    classDef external fill:#fff3cd,stroke:#856404,stroke-width:1px
```
