# tursodatabase/limbo architecture

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

- Interactive diagram: https://gitdiagram.com/tursodatabase/limbo
- Repository: https://github.com/tursodatabase/limbo

## Overview

##### Main Components

a) Core Database Engine Layer:
- Core storage engine components (found in /core/storage/)
- Virtual Database Engine (VDBE) components (/core/vdbe/)
- Query translation system (/core/translate/)

b) Interface Layers:
- SQLite3 C API compatibility layer (/sqlite3/)
- Language Bindings:
- Python bindings (/bindings/python/)
- WebAssembly/JavaScript bindings (/bindings/wasm/)

c) I/O Subsystem:
- Platform-specific I/O implementations (found in /core/io/)
- Linux (io_uring)
- Darwin
- Windows
- Generic

##### Component Relationships

**[Client Applications]**
- ↓
**[Language Bindings Layer]**
- Python ← → WASM
- ↓
**[SQLite3 Compatibility Layer]**
- ↓
**[Query Processing Layer]**
- Parser → Translator → Optimizer
- ↓
**[Virtual Database Engine]**
- ↓
**[Storage Engine]**
- Buffer Pool → B-Tree → WAL
- ↓
**[I/O Subsystem]**
- Platform-specific I/O

##### Important Details to Highlight

a) Query Flow:
- Path from SQL input through parsing (/vendored/sqlite3-parser/)
- Query translation (/core/translate/)
- Execution in the VDBE (/core/vdbe/)

b) Storage Architecture:
- Buffer pool management
- B-tree storage structure
- WAL (Write-Ahead Logging) mechanism

c) Cross-Platform Support:
- Demonstrate how the I/O abstraction layer handles different platforms
- Relationship between generic and platform-specific I/O

##### Specific Implementation Details

- Async I/O support for Linux (io_uring)
- SQLite compatibility layers
- Relationship with external tools and libraries

## Diagram (Mermaid)

```mermaid
graph TB
    %% Client Applications and Language Bindings
    subgraph Clients
        ClientApps[Client Applications]:::client
        PythonBindings[Python Bindings]:::binding
        WASMBindings[WebAssembly Bindings]:::binding
    end

    %% SQLite3 Compatibility Layer
    SQLiteAPI[SQLite3 C API]:::api

    %% Query Processing Layer
    subgraph QueryProcessing
        Parser[SQL Parser]:::query
        Translator[Query Translator]:::query
        Optimizer[Query Optimizer]:::query
    end

    %% Virtual Database Engine
    subgraph VDBE
        VDBEBuilder[VDBE Builder]:::vdbe
        VDBEExecution[VDBE Execution]:::vdbe
        VDBEExplain[Query Explanation]:::vdbe
    end

    %% Storage Engine
    subgraph Storage
        BufferPool[Buffer Pool]:::storage
        BTree[B-Tree]:::storage
        WAL[Write-Ahead Log]:::storage
        PageCache[Page Cache]:::storage
    end

    %% I/O Subsystem
    subgraph IO
        IOLinux[Linux io_uring]:::io
        IODarwin[Darwin I/O]:::io
        IOWindows[Windows I/O]:::io
        IOGeneric[Generic I/O]:::io
    end

    %% Core Types and Error Handling
    subgraph Core
        Types[Core Types]:::core
        ErrorHandling[Error Handling]:::core
        Results[Results]:::core
    end

    %% Relationships
    ClientApps --> PythonBindings & WASMBindings
    PythonBindings & WASMBindings --> SQLiteAPI
    SQLiteAPI --> Parser
    Parser --> Translator
    Translator --> Optimizer
    Optimizer --> VDBEBuilder
    VDBEBuilder --> VDBEExecution
    VDBEExecution --> VDBEExplain
    VDBEExecution --> BufferPool
    BufferPool --> BTree
    BTree --> WAL
    BufferPool --> PageCache
    WAL & PageCache --> IOLinux & IODarwin & IOWindows & IOGeneric
    Core --> Storage
    Core --> VDBE

    %% Click Events
    click PythonBindings "https://github.com/tursodatabase/limbo/tree/main//bindings/python/"
    click WASMBindings "https://github.com/tursodatabase/limbo/tree/main//bindings/wasm/"
    click SQLiteAPI "https://github.com/tursodatabase/limbo/tree/main//sqlite3/"
    click Parser "https://github.com/tursodatabase/limbo/tree/main//vendored/sqlite3-parser/"
    click Translator "https://github.com/tursodatabase/limbo/tree/main//core/translate/"
    click Optimizer "https://github.com/tursodatabase/limbo/blob/main//core/translate/optimizer.rs"
    click VDBEBuilder "https://github.com/tursodatabase/limbo/blob/main//core/vdbe/builder.rs"
    click VDBEExecution "https://github.com/tursodatabase/limbo/blob/main//core/vdbe/mod.rs"
    click VDBEExplain "https://github.com/tursodatabase/limbo/blob/main//core/vdbe/explain.rs"
    click BufferPool "https://github.com/tursodatabase/limbo/blob/main//core/storage/buffer_pool.rs"
    click BTree "https://github.com/tursodatabase/limbo/blob/main//core/storage/btree.rs"
    click WAL "https://github.com/tursodatabase/limbo/blob/main//core/storage/wal.rs"
    click PageCache "https://github.com/tursodatabase/limbo/blob/main//core/storage/page_cache.rs"
    click IOLinux "https://github.com/tursodatabase/limbo/blob/main//core/io/linux.rs"
    click IODarwin "https://github.com/tursodatabase/limbo/blob/main//core/io/darwin.rs"
    click IOWindows "https://github.com/tursodatabase/limbo/blob/main//core/io/windows.rs"
    click IOGeneric "https://github.com/tursodatabase/limbo/blob/main//core/io/generic.rs"
    click Types "https://github.com/tursodatabase/limbo/blob/main//core/types.rs"
    click ErrorHandling "https://github.com/tursodatabase/limbo/blob/main//core/error.rs"
    click Results "https://github.com/tursodatabase/limbo/blob/main//core/result.rs"

    %% Styles
    classDef client fill:#f9f,stroke:#333
    classDef binding fill:#9f9,stroke:#333
    classDef api fill:#ff9,stroke:#333
    classDef query fill:#f96,stroke:#333
    classDef vdbe fill:#69f,stroke:#333
    classDef storage fill:#39f,stroke:#333
    classDef io fill:#f63,stroke:#333
    classDef core fill:#c9f,stroke:#333
```
