# couchbaselabs/couchbase-lite-rust architecture

> Architecture diagram of the GitHub repository couchbaselabs/couchbase-lite-rust, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/couchbaselabs/couchbase-lite-rust
- Repository: https://github.com/couchbaselabs/couchbase-lite-rust

## Overview

##### Project Type & Purpose
- This repository provides Rust API bindings for Couchbase Lite, an embedded NoSQL document database engine with sync functionality.
- The main goal is to bridge Couchbase Lite’s C API to the Rust ecosystem using FFI (Foreign Function Interface) and bindgen.
- As such, the project is essentially a library that enables Rust developers to interact with Couchbase Lite while also exposing some high-level contructs (e.g., Database, Document, Query, Replicator).

##### Analyzing the File Structure
- Top-level Files: You have typical Rust project files such as Cargo.toml, build.rs (a build script that likely sets up paths for the C headers/libs), LICENSE, README, and configuration files.
- The src Directory: Contains several modules, for example:
- blob.rs, document.rs, database.rs: Likely wrap corresponding Couchbase Lite functionalities.
- c_api.rs and wrapper.h: Hint at a direct C API binding layer where the Rust code calls into the C library.
- fleece.rs and fleece_mutable.rs: Suggest integration with Fleece, a data representation used internally.
- query.rs and replicator.rs: Provide logic to build queries and manage syncing/replication.
- main.rs and lib.rs: Indicating the project may be used both as a standalone executable and as a library.
- Tests Directory: Contains unit tests that validate the integration with Couchbase Lite, emphasizing single-threaded execution for reliable leak detection.

a. Main Components:
- Rust Binding Library (Core Layer)
- Contains modules like database, document, query, replicator, and others.
- Exposes idiomatic Rust API to consumers.
- C API Layer
- Represented via the c_api.rs and associated header file (wrapper.h).
- This is where the Rust API bridges to Couchbase Lite’s C shared library.
- Fleece Layer
- Highlighted by fleece.rs files.
- Responsible for handling data serialization/deserialization or property mapping.
- External Dependency: Couchbase Lite For C
- The actual embedded NoSQL database engine that the bindings interface with.
b. Supporting Components:
- Build System:
- build.rs which sets up the paths and runs bindgen to generate Rust FFI interfaces from the C headers.
- Testing Framework:
- The tests directory ensuring the integrity of bindings; includes test practices like leak detection by comparing object counts.
- Logging & Error Management:
- Modules like logging.rs and error.rs show cross-cutting concerns integrated into the library.

##### Relationships and Interactions
- How the Rust API calls into the C API layer.
- How build.rs generates necessary FFI bindings before the Rust code is compiled.
- Data flow between Rust modules (e.g., database module calling document manipulation functions that internally use the Fleece layer).
- Dependency flow from the core application (the library exposed via lib.rs and main.rs) down to the external Couchbase Lite For C shared library.
- Dependency on external systems like LLVM/Clang (used by bindgen) and the Couchbase Lite shared library that must be provided by the user.

##### Highlighting Architectural Patterns & Design Principles
- FFI boundary between Rust and C code.
- Use of an adapter pattern where the binding layer converts between Rust idioms and the raw C API.
- Separation of concerns by isolating database, document, and query functionality into different modules.
- If applicable, note the layering: High-level API (wrappers) → FFI layer (bindgen output) → External dependency (Couchbase Lite).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Layer: Rust Binding Library
    subgraph "Core Layer: Rust Binding Library"
        LIB["lib.rs"]:::rust
        DB["database.rs"]:::rust
        DOC["document.rs"]:::rust
        QRY["query.rs"]:::rust
        REPL["replicator.rs"]:::rust
        BLOB["blob.rs"]:::rust
        LOG["logging.rs"]:::rust
        ERR["error.rs"]:::rust
    end

    %% FFI Layer: C API Layer
    subgraph "FFI Layer: C API Layer"
        CAP["c_api.rs"]:::ffi
        WRAP["wrapper.h"]:::ffi
    end

    %% Fleece Layer
    subgraph "Fleece Layer"
        FLE["fleece.rs"]:::fleece
        FLE_MUT["fleece_mutable.rs"]:::fleece
    end

    %% Build System
    subgraph "Build System"
        BUILD["build.rs"]:::build
    end

    %% Testing Framework
    subgraph "Testing Framework"
        TEST["tests"]:::test
    end

    %% External Dependency
    EXT["Couchbase Lite For C"]:::external

    %% Relationships and Interactions
    LIB -->|"exposes_API"| DB
    LIB -->|"exposes_API"| DOC
    LIB -->|"exposes_API"| QRY
    LIB -->|"exposes_API"| REPL
    LIB -->|"exposes_API"| BLOB

    DB -->|"uses"| DOC
    DOC -->|"integrates_with"| FLE
    QRY -->|"integrates_with"| FLE
    REPL -->|"calls"| CAP

    CAP -->|"bridges_to"| EXT
    WRAP -->|"bridges_to"| EXT

    BUILD -->|"generates_FFI"| CAP
    BUILD -->|"generates_FFI"| WRAP

    LIB -->|"logs_errors"| LOG
    LIB -->|"logs_errors"| ERR

    TEST -->|"validates"| LIB
    TEST -->|"validates"| FLE

    %% Click Events
    click LIB "https://github.com/couchbaselabs/couchbase-lite-rust/blob/main/src/lib.rs"
    click DB "https://github.com/couchbaselabs/couchbase-lite-rust/blob/main/src/database.rs"
    click DOC "https://github.com/couchbaselabs/couchbase-lite-rust/blob/main/src/document.rs"
    click QRY "https://github.com/couchbaselabs/couchbase-lite-rust/blob/main/src/query.rs"
    click REPL "https://github.com/couchbaselabs/couchbase-lite-rust/blob/main/src/replicator.rs"
    click BLOB "https://github.com/couchbaselabs/couchbase-lite-rust/blob/main/src/blob.rs"
    click CAP "https://github.com/couchbaselabs/couchbase-lite-rust/blob/main/src/c_api.rs"
    click WRAP "https://github.com/couchbaselabs/couchbase-lite-rust/blob/main/src/wrapper.h"
    click FLE "https://github.com/couchbaselabs/couchbase-lite-rust/blob/main/src/fleece.rs"
    click FLE_MUT "https://github.com/couchbaselabs/couchbase-lite-rust/blob/main/src/fleece_mutable.rs"
    click BUILD "https://github.com/couchbaselabs/couchbase-lite-rust/blob/main/build.rs"
    click TEST "https://github.com/couchbaselabs/couchbase-lite-rust/tree/main/tests"
    click LOG "https://github.com/couchbaselabs/couchbase-lite-rust/blob/main/src/logging.rs"
    click ERR "https://github.com/couchbaselabs/couchbase-lite-rust/blob/main/src/error.rs"

    %% Styles
    classDef rust fill:#add8e6,stroke:#000,stroke-width:2px;
    classDef ffi fill:#ffa500,stroke:#000,stroke-width:2px;
    classDef fleece fill:#90ee90,stroke:#000,stroke-width:2px;
    classDef build fill:#d3d3d3,stroke:#000,stroke-width:2px;
    classDef test fill:#ffc0cb,stroke:#000,stroke-width:2px;
    classDef external fill:#f5deb3,stroke:#000,stroke-width:2px;
```
