# ncruces/go-sqlite3 architecture

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

- Interactive diagram: https://gitdiagram.com/ncruces/go-sqlite3
- Repository: https://github.com/ncruces/go-sqlite3

## Overview

##### Core Components (Main Layer)
- WebAssembly runtime (wazero) as a fundamental component
- Embedded SQLite WASM build (from /embed directory)

##### Interface Layers
a. Top Layer (Client Interface):
- Database/SQL Driver interface
- GORM Driver interface (gormlite)
- Direct SQLite C API wrapper

b. Bottom Layer (System Interface):
- Virtual File System (VFS) implementation
- OS Interface adaptations

##### Extension System
- Array operations
- Blob I/O
- CSV handling
- Hash functions
- Statistics
- Unicode support
- UUID handling
- Other extensions

##### Virtual File System Components
VFS implementations:
- Memory DB
- Reader VFS
- Encryption (Adiantum, XTS)
- OS-specific implementations

Use the following visualization guidelines:

##### Component Representation
- Use rectangles for main components
- Use hexagons for interfaces
- Use clouds for external dependencies

##### Connection Types

- [Client Applications]
- ↓
- [Database/SQL Driver] → [GORM Driver]
- ↓
- [SQLite Wrapper Core] ← [Extensions]
- ↓
- [Wazero Runtime] → [SQLite WASM]
- ↓
- [VFS Layer] → [OS Interface]

##### Important Details
- Separation between pure Go and WASM components
- Cross-platform support
- Security features (encryption)
- Test coverage integration

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Client Layer"
        Client["Client Applications"]
        DBSQL["Database/SQL Driver"]:::interface
        GORM["GORM Driver"]:::interface
        DirectAPI["Direct SQLite API"]:::interface
    end

    subgraph "Core Layer"
        SQLiteWrapper["SQLite Wrapper Core"]:::core
        WasmRuntime["Wazero Runtime"]:::core
        SQLiteWasm["SQLite WASM Build"]:::core
    end

    subgraph "Extension System"
        direction TB
        ExtArray["Array Operations"]:::extension
        ExtBlob["Blob I/O"]:::extension
        ExtCSV["CSV Handling"]:::extension
        ExtHash["Hash Functions"]:::extension
        ExtStats["Statistics"]:::extension
        ExtUnicode["Unicode Support"]:::extension
        ExtUUID["UUID Handling"]:::extension
    end

    subgraph "VFS Layer"
        direction TB
        VFSCore["VFS Core"]:::vfs
        MemDB["Memory DB"]:::vfs
        ReaderVFS["Reader VFS"]:::vfs
        Encryption["Encryption (Adiantum/XTS)"]:::vfs
        OSImpl["OS-Specific Implementations"]:::vfs
    end

    %% Connections
    Client --> DBSQL
    Client --> GORM
    Client --> DirectAPI
    DBSQL --> SQLiteWrapper
    GORM --> SQLiteWrapper
    DirectAPI --> SQLiteWrapper
    SQLiteWrapper --> WasmRuntime
    WasmRuntime --> SQLiteWasm
    SQLiteWrapper --> VFSCore

    %% Extension connections
    ExtArray & ExtBlob & ExtCSV & ExtHash & ExtStats & ExtUnicode & ExtUUID --> SQLiteWrapper

    %% VFS connections
    VFSCore --> MemDB
    VFSCore --> ReaderVFS
    VFSCore --> Encryption
    VFSCore --> OSImpl

    %% Click events
    click SQLiteWrapper "https://github.com/ncruces/go-sqlite3/blob/main/sqlite.go"
    click DBSQL "https://github.com/ncruces/go-sqlite3/blob/main/driver/driver.go"
    click GORM "https://github.com/ncruces/go-sqlite3/blob/main/gormlite/sqlite.go"
    click SQLiteWasm "https://github.com/ncruces/go-sqlite3/blob/main/embed/sqlite3.wasm"
    click WasmRuntime "https://github.com/ncruces/go-sqlite3/blob/main/embed/init.go"
    click VFSCore "https://github.com/ncruces/go-sqlite3/blob/main/vfs/vfs.go"
    click MemDB "https://github.com/ncruces/go-sqlite3/blob/main/vfs/memdb/memdb.go"
    click ReaderVFS "https://github.com/ncruces/go-sqlite3/blob/main/vfs/readervfs/reader.go"
    click Encryption "https://github.com/ncruces/go-sqlite3/blob/main/vfs/adiantum/adiantum.go"
    click OSImpl "https://github.com/ncruces/go-sqlite3/blob/main/vfs/os_unix.go"
    click ExtArray "https://github.com/ncruces/go-sqlite3/blob/main/ext/array/array.go"
    click ExtBlob "https://github.com/ncruces/go-sqlite3/blob/main/ext/blobio/blob.go"
    click ExtCSV "https://github.com/ncruces/go-sqlite3/blob/main/ext/csv/csv.go"
    click ExtHash "https://github.com/ncruces/go-sqlite3/blob/main/ext/hash/hash.go"
    click ExtStats "https://github.com/ncruces/go-sqlite3/blob/main/ext/stats/stats.go"
    click ExtUnicode "https://github.com/ncruces/go-sqlite3/blob/main/ext/unicode/unicode.go"
    click ExtUUID "https://github.com/ncruces/go-sqlite3/blob/main/ext/uuid/uuid.go"

    %% Styling
    classDef core fill:#2374ab
    classDef interface fill:#57cc99
    classDef extension fill:#ffd60a
    classDef vfs fill:#7209b7
    classDef external fill:#808080

    %% Legend
    subgraph Legend
        L1[Core Components]:::core
        L2[Interfaces]:::interface
        L3[Extensions]:::extension
        L4[VFS Components]:::vfs
        L5[External Dependencies]:::external
    end
```
