# canonical/dqlite architecture

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

## Overview

##### Main Components

a) Core Components:
- SQLite Integration Layer
- Raft Consensus Implementation
- Network Protocol Layer
- Event Loop System (libuv-based)
- Client Interface

b) Supporting Components:
- Configuration Management
- Connection Handling
- State Machine
- VFS (Virtual File System)
- Error Handling
- Metrics Collection

##### Component Relationships

**Client Applications**
- ↕
**[Client Interface Layer]**
- Protocol Handler
- Connection Manager
- ↕
**[Core Processing Layer]**
- Gateway
- FSM (Finite State Machine)
- Command Processor
- ↕
**[Consensus Layer]**
- Raft Implementation
- Leader Election
- Log Replication
- ↕
**[Storage Layer]**
- SQLite Integration
- VFS
- Snapshot Management

##### Key Architectural Elements to Highlight

a) Asynchronous Processing:
- Event loop architecture
- Async I/O operations
- Callback paths

b) Replication Flow:
- Leader-follower relationships
- Log replication paths
- Consensus protocol communication

c) Data Flow:
- Client request handling
- Statement execution path
- Replication data path
- Snapshot management

##### Technical Details

- Protocol version indicators
- Key configuration parameters
- System requirements (Linux with native async I/O)
- Critical interfaces (dqlite.h)

##### Implementation Notes

- Single-threaded nature of the system
- Asynchronous operation model
- High availability features
- Automatic failover mechanisms
- SQLite integration points

##### External Dependencies

Clear integration points with:
- libuv
- SQLite
- LZ4 (optional)
- Operating System (Linux)

## Diagram (Mermaid)

```mermaid
graph TB
    %% Define styles
    classDef client fill:#a8d1f0,stroke:#333,stroke-width:1px
    classDef core fill:#90EE90,stroke:#333,stroke-width:1px
    classDef consensus fill:#FFE5B4,stroke:#333,stroke-width:1px
    classDef storage fill:#DDA0DD,stroke:#333,stroke-width:1px
    classDef support fill:#D3D3D3,stroke:#333,stroke-width:1px

    %% Client Layer
    subgraph ClientLayer["Client Interface Layer"]
        API["Public API"]
        Protocol["Protocol Implementation"]
        ClientConn["Connection Handler"]
    end

    %% Core Processing Layer
    subgraph CoreLayer["Core Processing Layer"]
        Gateway["Gateway"]
        FSM["FSM"]
        CmdProc["Command Processor"]
        Query["Query Handler"]
        Statement["Statement Manager"]
    end

    %% Consensus Layer
    subgraph ConsensusLayer["Consensus Layer"]
        Raft["Raft Implementation"]
        Election["Leader Election"]
        LogRepl["Log Replication"]
        Leader["Leader Management"]
    end

    %% Storage Layer
    subgraph StorageLayer["Storage Layer"]
        SQLite["SQLite Integration"]
        VFS["Virtual File System"]
        Registry["Registry"]
        StateMachine["State Machine"]
    end

    %% Supporting Infrastructure
    subgraph Support["Supporting Infrastructure"]
        Config["Configuration"]
        ErrorHandler["Error Handler"]
        Metrics["Metrics Collector"]
        EventLoop["Event Loop (libuv)"]
    end

    %% Relationships
    ClientLayer --> CoreLayer
    CoreLayer --> ConsensusLayer
    ConsensusLayer --> StorageLayer
    Support --> ClientLayer
    Support --> CoreLayer
    Support --> ConsensusLayer
    Support --> StorageLayer

    %% Click events
    click API "https://github.com/canonical/dqlite/blob/master/include/dqlite.h"
    click Protocol "https://github.com/canonical/dqlite/blob/master/src/client/protocol.h"
    click Gateway "https://github.com/canonical/dqlite/blob/master/src/gateway.h"
    click FSM "https://github.com/canonical/dqlite/blob/master/src/fsm.h"
    click CmdProc "https://github.com/canonical/dqlite/blob/master/src/command.h"
    click Raft "https://github.com/canonical/dqlite/blob/master/src/raft/raft.c"
    click Election "https://github.com/canonical/dqlite/blob/master/src/raft/election.h"
    click LogRepl "https://github.com/canonical/dqlite/blob/master/src/raft/replication.h"
    click Leader "https://github.com/canonical/dqlite/blob/master/src/leader.h"
    click SQLite "https://github.com/canonical/dqlite/blob/master/src/db.h"
    click VFS "https://github.com/canonical/dqlite/blob/master/src/vfs.h"
    click Config "https://github.com/canonical/dqlite/blob/master/src/config.h"
    click ClientConn "https://github.com/canonical/dqlite/blob/master/src/conn.h"
    click ErrorHandler "https://github.com/canonical/dqlite/blob/master/src/error.h"
    click Metrics "https://github.com/canonical/dqlite/blob/master/src/metrics.h"
    click EventLoop "https://github.com/canonical/dqlite/blob/master/src/raft/uv.h"
    click Registry "https://github.com/canonical/dqlite/blob/master/src/registry.h"
    click StateMachine "https://github.com/canonical/dqlite/blob/master/src/lib/sm.h"
    click Query "https://github.com/canonical/dqlite/blob/master/src/query.h"
    click Statement "https://github.com/canonical/dqlite/blob/master/src/stmt.h"

    %% Style applications
    class API,Protocol,ClientConn client
    class Gateway,FSM,CmdProc,Query,Statement core
    class Raft,Election,LogRepl,Leader consensus
    class SQLite,VFS,Registry,StateMachine storage
    class Config,ErrorHandler,Metrics,EventLoop support
```
