# bloomdb-labs/bloom_lfs architecture

> Architecture diagram of the GitHub repository bloomdb-labs/bloom_lfs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bloomdb-labs/bloom_lfs
- Repository: https://github.com/bloomdb-labs/bloom_lfs

## Overview

Bloom_lfs is an append-oriented durable storage engine. Its main workflow accepts application writes through the store API, stages and batches them in a buffer ring, and dispatches aligned writes to a durable backing file; reads use the dispatcher, while completion tracking exposes contiguous durable offsets. The graph also preserves the documented write modes and flush/sync capabilities. Source evidence is concentrated in src/lib.rs; other subsystem details rely on the README’s architecture and feature descriptions.

Main entry points: [`src/lib.rs`](https://github.com/bloomdb-labs/bloom_lfs/blob/main/src/lib.rs) (Log-Structured Store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Store API"]
  node_config["Store Configuration<br/>[lib.rs]"]
  node_store["Log-Structured Store<br/>[lib.rs]"]
  node_reservation["Write Reservation<br/>[lib.rs]"]
  node_read["Offset Read<br/>[lib.rs]"]
  node_flush_sync["Flush and Sync<br/>[lib.rs]"]
end

subgraph group_write["Write Coordination"]
  node_write_modes["Write Modes<br/>[lib.rs]"]
  node_buffer_ring["Buffer Ring<br/>[lib.rs]"]
end

subgraph group_io["I/O and Storage"]
  node_quikio["QuikIO Dispatcher<br/>[lib.rs]"]
  node_uring["io_uring"]
  node_direct_io["Direct I/O"]
  node_backing_file[("Backing File<br/>[lib.rs]")]
end

subgraph group_durability["Durability"]
  node_completion["Write Completion<br/>[lib.rs]"]
  node_stable_offsets["Stable Offsets<br/>[lib.rs]"]
end

node_application(("Application"))

node_application -->|"configures"| node_config
node_application -->|"writes and reads"| node_store
node_config -->|"opens"| node_store
node_store -->|"reserves space"| node_reservation
node_store -->|"stages writes"| node_buffer_ring
node_write_modes -->|"selects ordering"| node_buffer_ring
node_buffer_ring -->|"submits flushes"| node_quikio
node_quikio -->|"dispatches writes"| node_uring
node_uring -->|"issues aligned I/O"| node_direct_io
node_direct_io -->|"writes batches"| node_backing_file
node_store -->|"reads by offset"| node_read
node_read -->|"reads data"| node_quikio
node_flush_sync -->|"flushes buffers"| node_buffer_ring
node_flush_sync -.->|"syncs storage"| node_quikio
node_quikio -->|"reports completions"| node_completion
node_completion -->|"advances contiguous offsets"| node_stable_offsets
node_application -->|"checks durability"| node_stable_offsets

click node_config "https://github.com/bloomdb-labs/bloom_lfs/blob/main/src/lib.rs"
click node_store "https://github.com/bloomdb-labs/bloom_lfs/blob/main/src/lib.rs"
click node_reservation "https://github.com/bloomdb-labs/bloom_lfs/blob/main/src/lib.rs"
click node_read "https://github.com/bloomdb-labs/bloom_lfs/blob/main/src/lib.rs"
click node_flush_sync "https://github.com/bloomdb-labs/bloom_lfs/blob/main/src/lib.rs"
click node_write_modes "https://github.com/bloomdb-labs/bloom_lfs/blob/main/src/lib.rs"
click node_buffer_ring "https://github.com/bloomdb-labs/bloom_lfs/blob/main/src/lib.rs"
click node_quikio "https://github.com/bloomdb-labs/bloom_lfs/blob/main/src/lib.rs"
click node_backing_file "https://github.com/bloomdb-labs/bloom_lfs/blob/main/src/lib.rs"
click node_completion "https://github.com/bloomdb-labs/bloom_lfs/blob/main/src/lib.rs"
click node_stable_offsets "https://github.com/bloomdb-labs/bloom_lfs/blob/main/src/lib.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_config,node_store,node_reservation,node_read,node_flush_sync toneBlue
class node_write_modes,node_buffer_ring toneAmber
class node_quikio,node_uring,node_direct_io,node_backing_file toneMint
class node_completion,node_stable_offsets toneRose
class node_application toneIndigo
```

## Components

### Store API

- [Store Configuration](https://github.com/bloomdb-labs/bloom_lfs/blob/main/src/lib.rs): `src/lib.rs`
- [Log-Structured Store](https://github.com/bloomdb-labs/bloom_lfs/blob/main/src/lib.rs): `src/lib.rs`
- [Write Reservation](https://github.com/bloomdb-labs/bloom_lfs/blob/main/src/lib.rs): `src/lib.rs`
- [Offset Read](https://github.com/bloomdb-labs/bloom_lfs/blob/main/src/lib.rs): `src/lib.rs`
- [Flush and Sync](https://github.com/bloomdb-labs/bloom_lfs/blob/main/src/lib.rs): `src/lib.rs`

### Write Coordination

- [Write Modes](https://github.com/bloomdb-labs/bloom_lfs/blob/main/src/lib.rs): `src/lib.rs`
- [Buffer Ring](https://github.com/bloomdb-labs/bloom_lfs/blob/main/src/lib.rs): `src/lib.rs`

### I/O and Storage

- [QuikIO Dispatcher](https://github.com/bloomdb-labs/bloom_lfs/blob/main/src/lib.rs): `src/lib.rs`
- **io_uring**
- **Direct I/O**
- [Backing File](https://github.com/bloomdb-labs/bloom_lfs/blob/main/src/lib.rs): `src/lib.rs`

### Durability

- [Write Completion](https://github.com/bloomdb-labs/bloom_lfs/blob/main/src/lib.rs): `src/lib.rs`
- [Stable Offsets](https://github.com/bloomdb-labs/bloom_lfs/blob/main/src/lib.rs): `src/lib.rs`

### Other components

- **Application**

## Connections

- Application → Store Configuration: configures (evidence: `README.md`)
- Application → Log-Structured Store: writes and reads (evidence: `README.md`)
- Store Configuration → Log-Structured Store: opens (evidence: `src/lib.rs`)
- Log-Structured Store → Write Reservation: reserves space (evidence: `src/lib.rs`)
- Log-Structured Store → Buffer Ring: stages writes (evidence: `src/lib.rs`)
- Write Modes → Buffer Ring: selects ordering (evidence: `README.md`)
- Buffer Ring → QuikIO Dispatcher: submits flushes (evidence: `src/lib.rs`)
- QuikIO Dispatcher → io_uring: dispatches writes (evidence: `README.md`)
- io_uring → Direct I/O: issues aligned I/O (evidence: `README.md`)
- Direct I/O → Backing File: writes batches (evidence: `README.md`)
- Log-Structured Store → Offset Read: reads by offset (evidence: `README.md`)
- Offset Read → QuikIO Dispatcher: reads data (evidence: `src/lib.rs`)
- Flush and Sync → Buffer Ring: flushes buffers (evidence: `README.md`)
- Flush and Sync → QuikIO Dispatcher: syncs storage (evidence: `src/lib.rs`)
- QuikIO Dispatcher → Write Completion: reports completions (evidence: `src/lib.rs`)
- Write Completion → Stable Offsets: advances contiguous offsets (evidence: `src/lib.rs`)
- Application → Stable Offsets: checks durability (evidence: `README.md`)
