# wiselibs/better-sqlite3 architecture

> Architecture diagram of the GitHub repository wiselibs/better-sqlite3, 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/wiselibs/better-sqlite3
- Repository: https://github.com/wiselibs/better-sqlite3

## Overview

##### Main Components

a) Core Components:
- Node.js Runtime Environment
- better-sqlite3 Bridge Layer
- SQLite3 Engine
- File System (for database storage)

b) Internal Modules:
- Database Interface
- Statement Handler
- Transaction Manager
- Custom Functions/Aggregates Handler
- Worker Thread Integration

**┌─────────────────────────────────────────┐**
- Application Layer            │
- ┘
- ↕
**┌─────────────────────────────────────────┐**
- Node.js Runtime Layer           │
- ┘
- ↕
**┌─────────────────────────────────────────┐**
- better-sqlite3 Bridge Layer      │
- ┬──────────────┬───────────-┤
- Database   │  Statement   │Transaction │
- Handler    │  Handler     │Manager     │
- ┼──────────────┼───────────-┤
- Custom     │   Worker     │  Utility   │
- Functions  │   Threads    │  Methods   │
- ┴──────────────┴───────────-┘
- ↕
**┌─────────────────────────────────────────┐**
- SQLite3 Engine               │
- ┘
- ↕
**┌─────────────────────────────────────────┐**
- File System                  │
- ┘

##### Important Details to Highlight

a) Core Features:
- Synchronous API design
- Transaction support
- Custom functions and aggregates
- Worker thread support
- 64-bit integer handling

b) Key Integration Points:
- Native binding interface (src/better_sqlite3.cpp)
- Statement preparation and execution
- Transaction management
- Extension loading capability

##### Implementation Details

- Relationship between lib/ (JavaScript interface) and src/ (C++ implementation)
- Methods/ directory structure for different functionalities
- Benchmark capabilities
- Test coverage areas

##### Special Notations

Indicators for:
- Safety mechanisms
- Memory management
- Error handling (sqlite-error.js)
- Extension points

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph AL[Application Layer]
        App[Node.js Application]
    end

    subgraph NRL[Node.js Runtime Layer]
        NodeJS[Node.js Runtime Environment]:::nodejs
    end

    subgraph BSL[better-sqlite3 Bridge Layer]
        Bridge["Native Bridge Interface"]:::bridge
        click Bridge "https://github.com/WiseLibs/better-sqlite3/blob/master/src/better_sqlite3.cpp"

        subgraph Core[Core Components]
            direction TB
            DB["Database Interface"]:::core
            click DB "https://github.com/WiseLibs/better-sqlite3/blob/master/lib/database.js"
            SH["Statement Handler"]:::core
            click SH "https://github.com/WiseLibs/better-sqlite3/blob/master/src/objects/statement.lzz"
            TM["Transaction Manager"]:::core
            click TM "https://github.com/WiseLibs/better-sqlite3/blob/master/lib/methods/transaction.js"
        end

        subgraph Handlers[Handlers & Utilities]
            direction TB
            CF["Custom Functions"]:::handler
            click CF "https://github.com/WiseLibs/better-sqlite3/blob/master/lib/methods/function.js"
            CA["Custom Aggregates"]:::handler
            click CA "https://github.com/WiseLibs/better-sqlite3/blob/master/lib/methods/aggregate.js"
            WT["Worker Threads"]:::handler
        end

        subgraph Utils[Utility Layer]
            direction TB
            DC["Data Conversion"]:::util
            click DC "https://github.com/WiseLibs/better-sqlite3/blob/master/src/util/data-converter.lzz"
            EH["Error Handler"]:::util
            click EH "https://github.com/WiseLibs/better-sqlite3/blob/master/lib/sqlite-error.js"
            BU["Backup System"]:::util
            click BU "https://github.com/WiseLibs/better-sqlite3/blob/master/lib/methods/backup.js"
            CM["Core Methods"]:::util
            click CM "https://github.com/WiseLibs/better-sqlite3/blob/master/lib/methods/pragma.js"
            UF["Utility Functions"]:::util
            click UF "https://github.com/WiseLibs/better-sqlite3/blob/master/lib/util.js"
        end
    end

    subgraph DBL[Database Layer]
        SQLite["SQLite3 Engine"]:::sqlite
        click SQLite "https://github.com/WiseLibs/better-sqlite3/tree/master/deps/sqlite3/"
        FS["File System"]:::system
    end

    %% Connections
    App --> NodeJS
    NodeJS --> Bridge
    Bridge --> Core
    Bridge --> Handlers
    Bridge --> Utils
    Core --> SQLite
    Handlers --> SQLite
    Utils --> SQLite
    SQLite --> FS

    %% Styles
    classDef nodejs fill:#68a063,color:white
    classDef bridge fill:#2b2b2b,color:white
    classDef core fill:#3178c6,color:white
    classDef handler fill:#cc7000,color:white
    classDef util fill:#9c27b0,color:white
    classDef sqlite fill:#044a64,color:white
    classDef system fill:#666666,color:white

    %% Legend
    subgraph Legend
        direction TB
        L1["Node.js Component"]:::nodejs
        L2["Bridge Component"]:::bridge
        L3["Core Component"]:::core
        L4["Handler Component"]:::handler
        L5["Utility Component"]:::util
        L6["SQLite Component"]:::sqlite
        L7["System Component"]:::system
    end
```
