# tanstack/db architecture

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

- Interactive diagram: https://gitdiagram.com/tanstack/db
- Repository: https://github.com/tanstack/db

## Overview

##### Project type and purpose
- Type: Monorepo for a client-side reactive data library (TanStack DB) with multiple packages.
- Purpose: Provide a blazing-fast, in-memory, reactive “DB” on the client, built on differential dataflow, with live queries and optimistic mutations.

##### File structure
- Top-level files: workspace configs (pnpm-workspace.yaml), linter & build configs (.eslintrc, tsconfig.json), docs, examples, license, README.
- packages/ directory:
- db — core query engine, transaction primitives, differential dataflow implementation
- db-collections — abstractions to pull in data from any backend into “collections”
- react-db & vue-db — React and Vue hooks for live queries and optimistic mutations
- examples/react/todo: A fully working React example showing how all pieces fit together.

##### Extract insights from README
- Core concepts: Collections, live queries, transactional mutators
- Extensibility: backend-agnostic (ElectricSQL, REST, GraphQL, custom)
- Integration: builds on TanStack Query & Store

a. Main components
- Client App (e.g. React Todo example)
- Framework adapters: react-db, vue-db
- Collections API: db-collections
- Core engine: db package (query engine, schema, transactions)
- External data sources: REST API, GraphQL, Sync engines (ElectricSQL)
- Supporting libs: TanStack Query, TanStack Store

b. Relationships and interactions
1. Client App → uses react-db hooks (useLiveQuery, useOptimisticMutation)
2. react-db → wraps db-collections & db APIs
3. db-collections → defines createQueryCollection, binds a queryFn to backend calls
4. db (core)
– query engine: compiles queries to differential dataflow operators
– transactions: batches optimistic updates, rollback, invalidation
5. db communicates with external data sources via queryFns or sync engines
6. TanStack Query & Store: optionally plugged in for caching & state management

c. Architectural patterns / design principles
- Layered monorepo: core engine → collections → framework adapters → examples
- Plugin-style backend agnosticism via pluggable queryFn
- Differential dataflow for incremental, fine-grained reactivity
- Optimistic UI pattern with transaction staging and rollback

d. Key technologies
- TypeScript, differential dataflow (d2ts)
- Monorepo managed by pnpm workspaces
- React / Vue integrations via custom hooks
- TanStack Query & Store

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Core Engine"
        CE["Core Engine\n(packages/db)"]:::core
        QM["Query Modules\n(packages/db/src/query)"]:::core
        TX["Transactions\n(packages/db/src/transactions.ts)"]:::core
    end

    subgraph "Collections API"
        CA["Collections API\n(packages/db-collections)"]:::adapter
        CQ["Query Helpers\n(packages/db-collections/src/query.ts)"]:::adapter
        CEI["ElectricSQL Integration\n(packages/db-collections/src/electric.ts)"]:::adapter
    end

    subgraph "Framework Adapters"
        RA["React Adapter\n(packages/react-db)"]:::adapter
        RL["useLiveQuery\n(packages/react-db/src/useLiveQuery.ts)"]:::adapter
        RO["useOptimisticMutation\n(packages/react-db/src/useOptimisticMutation.ts)"]:::adapter
        VA["Vue Adapter\n(packages/vue-db)"]:::adapter
        VL["useLiveQuery\n(packages/vue-db/src/useLiveQuery.ts)"]:::adapter
        VO["useOptimisticMutation\n(packages/vue-db/src/useOptimisticMutation.ts)"]:::adapter
    end

    subgraph "Client Examples"
        RT["React Todo App\n(examples/react/todo/src/App.tsx)"]:::client
        TD["DB Setup\n(examples/react/todo/src/db/index.ts)"]:::client
        SA["Server API\n(examples/react/todo/src/api/server.ts)"]:::external
    end

    subgraph "External Backends"
        REST["REST API"]:::external
        GQL["GraphQL"]:::external
        EDB["ElectricSQL"]:::external
    end

    subgraph "Supporting Libraries"
        TQ["TanStack Query"]:::support
        TS["TanStack Store"]:::support
    end

    Docs["Documentation\n(docs/index.md)"]:::docs

    %% Core Engine connections
    CE --> QM
    CE --> TX

    %% Collections API connections
    CA --> CQ
    CA --> CEI
    CA --> CE

    %% Adapter layer
    RA --> RL
    RA --> RO
    VA --> VL
    VA --> VO
    RA --> CA
    VA --> CA

    %% Client examples
    RT --> RL
    RT --> RO
    RT --> RA
    RT --> TD
    TD --> SA

    %% Supporting libs
    TQ --> RA
    TS --> RA
    TQ --> VA
    TS --> VA

    %% External backends
    CA --> REST
    CA --> GQL
    CA --> EDB

    %% Documentation
    Docs

    %% Click events
    click CE "https://github.com/tanstack/db/blob/main/packages/db/src/index.ts"
    click QM "https://github.com/tanstack/db/tree/main/packages/db/src/query"
    click TX "https://github.com/tanstack/db/blob/main/packages/db/src/transactions.ts"
    click CA "https://github.com/tanstack/db/blob/main/packages/db-collections/src/index.ts"
    click CQ "https://github.com/tanstack/db/blob/main/packages/db-collections/src/query.ts"
    click CEI "https://github.com/tanstack/db/blob/main/packages/db-collections/src/electric.ts"
    click RA "https://github.com/tanstack/db/blob/main/packages/react-db/src/index.ts"
    click RL "https://github.com/tanstack/db/blob/main/packages/react-db/src/useLiveQuery.ts"
    click RO "https://github.com/tanstack/db/blob/main/packages/react-db/src/useOptimisticMutation.ts"
    click VA "https://github.com/tanstack/db/blob/main/packages/vue-db/src/index.ts"
    click VL "https://github.com/tanstack/db/blob/main/packages/vue-db/src/useLiveQuery.ts"
    click VO "https://github.com/tanstack/db/blob/main/packages/vue-db/src/useOptimisticMutation.ts"
    click RT "https://github.com/tanstack/db/blob/main/examples/react/todo/src/App.tsx"
    click TD "https://github.com/tanstack/db/blob/main/examples/react/todo/src/db/index.ts"
    click SA "https://github.com/tanstack/db/blob/main/examples/react/todo/src/api/server.ts"
    click Docs "https://github.com/tanstack/db/blob/main/docs/index.md"

    %% Styles
    classDef core fill:#D6E4FF,stroke:#1144AA
    classDef adapter fill:#DFFFD6,stroke:#119911
    classDef client fill:#FFE4B5,stroke:#AA6600
    classDef external fill:#E0E0E0,stroke:#666666
    classDef support fill:#F0E68C,stroke:#A0A000
    classDef docs fill:#F8F8F8,stroke:#888888
```
