# instantdb/instant architecture

> Architecture diagram of the GitHub repository instantdb/instant, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/instantdb/instant
- Repository: https://github.com/instantdb/instant

## Overview

##### Main Components

a. Client-Side Components:
- Client SDK Layer (with variants for React, React Native, and Vanilla JS)
- Client-side Triple Store
- Local Storage (IndexedDB/AsyncStorage)
- Query Interface
- Transaction Manager

b. Server-Side Components:
- Sync Server (Clojure)
- Query Engine (InstaQL/Datalog)
- Permissions System (CEL)
- WAL Listener
- Multi-tenant PostgreSQL Database

##### Key Relationships to Highlight

a. Data Flow:
- Client to Sync Server communication
- WAL change propagation
- Query invalidation paths
- Transaction synchronization
- Real-time updates flow

b. Storage Relationships:
- PostgreSQL to Triple Store mapping
- Local cache synchronization
- Offline data persistence

**┌─ Client Layer ──────────────────────────────────┐**
- ┌─ SDK Implementation ─┐  ┌─ Local Storage ───┐ │
- React            │  │  - IndexedDB      │ │
- React Native     │──│  - AsyncStorage   │ │
- Vanilla JS       │  └──────────────────┘ │
- ┘                        │
- ┌─ Client Store ───────────────────────────┐  │
- Triple Store                          │  │
- Query Cache                           │  │
- Transaction Queue                     │  │
- ┘   │
- ┘

**┌───────────────────▼──────────────────────────┐**
- ┌─ Sync Server ──────┐  ┌─ Query Engine ───┐ │
- Real-time Sync  │  │  - InstaQL      │ │
- Query Handler   │──│  - Datalog      │ │
- WAL Listener    │  └────────────────┘ │
- ┘                       │
- ┌─ Security Layer ────────────────────────┐ │
- CEL Permissions                      │ │
- Authentication                       │ │
- ┘ │
- ┘

**┌───────────────────▼──────────────────────────┐**
- ┌─ Database Layer ────────────────────────┐  │
- Multi-tenant PostgreSQL              │  │
- Triple Store Schema                  │  │
- WAL                                  │  │
- ┘  │
- ┘

##### Additional Elements
- Version indicators for different SDK implementations
- Offline capability paths
- Multiplayer synchronization flows
- Optimistic update paths
- Permission check points

##### Implementation Details to Note
- The system uses a triple store model for data storage
- WAL tailing for change detection
- CEL-based permission system
- Multi-tenant architecture
- Client-side caching strategy
- Real-time synchronization mechanisms

## Diagram (Mermaid)

```mermaid
graph TB
    %% Style definitions
    classDef client fill:#3498db,stroke:#2980b9,color:white
    classDef server fill:#2ecc71,stroke:#27ae60,color:white
    classDef security fill:#f1c40f,stroke:#f39c12,color:black
    classDef database fill:#9b59b6,stroke:#8e44ad,color:white
    classDef storage fill:#e74c3c,stroke:#c0392b,color:white

    subgraph ClientLayer["Client Layer"]
        subgraph SDKImpl["SDK Implementation"]
            React["React SDK"]
            ReactNative["React Native SDK"]
            VanillaJS["Vanilla JS SDK"]
        end

        subgraph ClientStore["Client Store"]
            TripleStore["Triple Store"]
            QueryCache["Query Cache"]
            TxQueue["Transaction Queue"]
        end

        subgraph LocalStorage["Local Storage"]
            IndexedDB["IndexedDB"]
            AsyncStorage["AsyncStorage"]
        end
    end

    subgraph ServerLayer["Server Layer"]
        subgraph SyncServer["Sync Server"]
            RTSync["Real-time Sync"]
            QueryHandler["Query Handler"]
            WALListener["WAL Listener"]
        end

        subgraph QueryEngine["Query Engine"]
            InstaQL["InstaQL"]
            Datalog["Datalog"]
        end

        subgraph SecurityLayer["Security Layer"]
            CEL["CEL Permissions"]
            Auth["Authentication"]
        end
    end

    subgraph DBLayer["Database Layer"]
        PostgreSQL["Multi-tenant PostgreSQL"]
        DBSchema["Triple Store Schema"]
        WAL["Write-Ahead Log"]
    end

    %% Relationships
    React & ReactNative & VanillaJS --> TripleStore
    TripleStore --> QueryCache
    TripleStore --> TxQueue
    TripleStore -.-> IndexedDB & AsyncStorage
    TxQueue --> RTSync
    QueryCache --> QueryHandler
    RTSync --> WALListener
    QueryHandler --> InstaQL & Datalog
    InstaQL & Datalog --> CEL
    WALListener --> WAL
    CEL --> PostgreSQL
    PostgreSQL --> DBSchema
    PostgreSQL --> WAL

    %% Click events
    click React "https://github.com/instantdb/instant/tree/main/client/packages/react/"
    click ReactNative "https://github.com/instantdb/instant/tree/main/client/packages/react-native/"
    click VanillaJS "https://github.com/instantdb/instant/tree/main/client/packages/core/"
    click TripleStore "https://github.com/instantdb/instant/blob/main/client/packages/core/src/store.js"
    click IndexedDB "https://github.com/instantdb/instant/blob/main/client/packages/core/src/IndexedDBStorage.js"
    click AsyncStorage "https://github.com/instantdb/instant/blob/main/client/packages/core/src/StorageAPI.ts"
    click TxQueue "https://github.com/instantdb/instant/blob/main/client/packages/core/src/instatx.ts"
    click InstaQL "https://github.com/instantdb/instant/blob/main/server/src/instant/db/instaql.clj"
    click Datalog "https://github.com/instantdb/instant/blob/main/server/src/instant/db/datalog.clj"
    click CEL "https://github.com/instantdb/instant/blob/main/server/src/instant/db/cel.clj"
    click WALListener "https://github.com/instantdb/instant/blob/main/server/src/instant/jdbc/wal.clj"
    click RTSync "https://github.com/instantdb/instant/blob/main/server/src/instant/reactive/session.clj"
    click QueryHandler "https://github.com/instantdb/instant/blob/main/server/src/instant/reactive/query.clj"
    click PostgreSQL "https://github.com/instantdb/instant/tree/main/server/src/instant/db/model/"
    click WAL "https://github.com/instantdb/instant/blob/main/server/src/instant/db/transaction.clj"

    %% Class assignments
    class React,ReactNative,VanillaJS,TripleStore,QueryCache,TxQueue,IndexedDB,AsyncStorage client
    class RTSync,QueryHandler,WALListener,InstaQL,Datalog server
    class CEL,Auth security
    class PostgreSQL,DBSchema,WAL database
    class IndexedDB,AsyncStorage storage
```
