# kojix2/leveldb architecture

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

- Interactive diagram: https://gitdiagram.com/kojix2/leveldb
- Repository: https://github.com/kojix2/leveldb

## Overview

#### Purpose and Entry Point
This is a Crystal shard exposing Google LevelDB as an idiomatic Crystal key-value database API. Consumers load `src/leveldb.cr`, which assembles the public namespace and binding layers. The native LevelDB shared library is an external runtime dependency installed through the host OS package manager.

Paths: `src/leveldb.cr`, `shard.yml`, `c.h`

#### Native Binding Boundary
`LevelDB::LibLevelDB` is the FFI boundary to LevelDB’s C API: opaque native handles, C enums, and calls for database operations, options, iterators, snapshots, and batches. Crystal-facing code must translate strings/buffers, native error outputs, and handle ownership across this boundary.

Paths: `src/leveldb/lib_leveldb.cr`, `c.h`, `src/leveldb/errors.cr`

#### Database Lifecycle and Core Operations
`LevelDB::DB` owns an opened native database handle and is the primary application control surface. `DB.open` supports scoped use so callers can reliably close the database. It provides reads, writes, deletes, indexed access, batch writes, iteration, snapshots, and error propagation.

Primary flow: application → `LevelDB::DB` → `LibLevelDB` C API → local LevelDB database files. Native failures become `LevelDB::Error`.

Paths: `src/leveldb/db.cr`, `src/leveldb/lib_leveldb.cr`, `src/leveldb/errors.cr`

#### Configuration and Read/Write Semantics
Crystal option wrappers encapsulate native LevelDB option handles and setters. `Options` configures database creation, cache/file behavior, and compression; `ReadOptions` carries consistency choices such as snapshots; write options control write behavior. These objects form a configuration boundary: callers set policy before passing handles into DB operations.

Paths: `src/leveldb/options.cr`, `src/leveldb/db.cr`, `src/leveldb/lib_leveldb.cr`

#### Iteration and Snapshot Consistency
`Iterator` wraps a native iterator and exposes seek, validity checks, movement, key/value access, and deferred error checking. DB convenience iteration delegates to this lifecycle. Snapshots are native consistency handles created by the DB, attached to read options, then explicitly released, allowing stable reads while writes continue.

Paths: `src/leveldb/iterator.cr`, `src/leveldb/db.cr`, `src/leveldb/options.cr`

#### Atomic Batch Mutation
`WriteBatch` is a separate native-backed mutation accumulator. Callers add puts and deletes, submit the batch through `DB#write`, and close it when finished. This separates construction of an atomic write unit from database execution and makes batch-handle lifetime explicit.

Paths: `src/leveldb/write_batch.cr`, `src/leveldb/db.cr`, `src/leveldb/lib_leveldb.cr`

#### Execution and Verification Context
The runtime is Crystal plus the system-installed LevelDB C library on macOS or Debian/Ubuntu. Examples demonstrate the intended public API patterns; CI validates the shard’s native integration and Crystal behavior.

Paths: `examples/basic.cr`, `examples/iterator.cr`, `.github/workflows/ci.yml`

Main entry points: [`src/leveldb/lib_leveldb.cr`](https://github.com/kojix2/leveldb/blob/main/src/leveldb/lib_leveldb.cr) (LibLevelDB), [`src/leveldb.cr`](https://github.com/kojix2/leveldb/blob/main/src/leveldb.cr) (LevelDB namespace), [`src/leveldb/db.cr`](https://github.com/kojix2/leveldb/blob/main/src/leveldb/db.cr) (DB), [`src/leveldb/iterator.cr`](https://github.com/kojix2/leveldb/blob/main/src/leveldb/iterator.cr) (Iterator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Crystal API"]
  node_entry["LevelDB namespace<br/>shard entry point<br/>[leveldb.cr]"]
  node_db["DB<br/>database facade<br/>[db.cr]"]
  node_options["Options<br/>option wrappers<br/>[options.cr]"]
  node_iterator["Iterator<br/>[iterator.cr]"]
  node_batch["WriteBatch<br/>mutation accumulator<br/>[write_batch.cr]"]
  node_errors["LevelDB::Error<br/>error model<br/>[errors.cr]"]
end

subgraph group_native["Native boundary"]
  node_ffi{{"LibLevelDB<br/>Crystal FFI<br/>[lib_leveldb.cr]"}}
  node_header["LevelDB C header<br/>C API declaration<br/>[c.h]"]
end

subgraph group_runtime["Runtime &amp; verification"]
  node_native_lib{{"System LevelDB<br/>shared library"}}
  node_files[("LevelDB files<br/>local storage")]
  node_examples["Usage examples<br/>consumer examples<br/>[basic.cr]"]
  node_iterator_example["Iterator example<br/>consumer example<br/>[iterator.cr]"]
  node_ci["CI<br/>integration validation<br/>[ci.yml]"]
  node_manifest["Shard manifest<br/>package manifest<br/>[shard.yml]"]
end

node_entry -->|"exports"| node_db
node_entry -->|"exports"| node_options
node_entry -->|"exports"| node_iterator
node_entry -->|"exports"| node_batch
node_entry -->|"loads bindings"| node_ffi
node_db -->|"accepts policies"| node_options
node_db -->|"creates and drives"| node_iterator
node_db -->|"submits batch"| node_batch
node_db -->|"database operations"| node_ffi
node_iterator -->|"iterator calls"| node_ffi
node_batch -->|"batch calls"| node_ffi
node_ffi -->|"translates failures"| node_errors
node_ffi -.->|"maps C API"| node_header
node_ffi -->|"FFI calls"| node_native_lib
node_native_lib -->|"reads and writes"| node_files
node_examples -->|"uses"| node_db
node_iterator_example -->|"uses"| node_iterator
node_ci -.->|"tests integration"| node_native_lib
node_manifest -.->|"packages"| node_entry

click node_entry "https://github.com/kojix2/leveldb/blob/main/src/leveldb.cr"
click node_db "https://github.com/kojix2/leveldb/blob/main/src/leveldb/db.cr"
click node_options "https://github.com/kojix2/leveldb/blob/main/src/leveldb/options.cr"
click node_iterator "https://github.com/kojix2/leveldb/blob/main/src/leveldb/iterator.cr"
click node_batch "https://github.com/kojix2/leveldb/blob/main/src/leveldb/write_batch.cr"
click node_errors "https://github.com/kojix2/leveldb/blob/main/src/leveldb/errors.cr"
click node_ffi "https://github.com/kojix2/leveldb/blob/main/src/leveldb/lib_leveldb.cr"
click node_header "https://github.com/kojix2/leveldb/blob/main/c.h"
click node_examples "https://github.com/kojix2/leveldb/blob/main/examples/basic.cr"
click node_iterator_example "https://github.com/kojix2/leveldb/blob/main/examples/iterator.cr"
click node_ci "https://github.com/kojix2/leveldb/blob/main/.github/workflows/ci.yml"
click node_manifest "https://github.com/kojix2/leveldb/blob/main/shard.yml"

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_entry,node_db,node_options,node_iterator,node_batch,node_errors toneBlue
class node_ffi,node_header toneAmber
class node_native_lib,node_files,node_examples,node_iterator_example,node_ci,node_manifest toneMint
```

## Components

### Crystal API

- [LevelDB namespace](https://github.com/kojix2/leveldb/blob/main/src/leveldb.cr): shard entry point · Assembles the public API and bindings. · `src/leveldb.cr`
- [DB](https://github.com/kojix2/leveldb/blob/main/src/leveldb/db.cr): database facade · Owns the opened native database handle. · `src/leveldb/db.cr`
- [Options](https://github.com/kojix2/leveldb/blob/main/src/leveldb/options.cr): option wrappers · Own native option handles and read/write policy. · `src/leveldb/options.cr`
- [Iterator](https://github.com/kojix2/leveldb/blob/main/src/leveldb/iterator.cr): iterator wrapper · Wraps native traversal and deferred error checks. · `src/leveldb/iterator.cr`
- [WriteBatch](https://github.com/kojix2/leveldb/blob/main/src/leveldb/write_batch.cr): mutation accumulator · Builds an atomic native-backed write unit. · `src/leveldb/write_batch.cr`
- [LevelDB::Error](https://github.com/kojix2/leveldb/blob/main/src/leveldb/errors.cr): error model · Represents translated native failures. · `src/leveldb/errors.cr`

### Native boundary

- [LibLevelDB](https://github.com/kojix2/leveldb/blob/main/src/leveldb/lib_leveldb.cr): Crystal FFI · C API handles, enums, calls, and ownership boundary. · `src/leveldb/lib_leveldb.cr`
- [LevelDB C header](https://github.com/kojix2/leveldb/blob/main/c.h): C API declaration · `c.h`

### Runtime & verification

- **System LevelDB**: shared library · Host-installed LevelDB C runtime.
- **LevelDB files**: local storage
- [Usage examples](https://github.com/kojix2/leveldb/blob/main/examples/basic.cr): consumer examples · Demonstrate basic database and iterator API patterns. · `examples/basic.cr`
- [Iterator example](https://github.com/kojix2/leveldb/blob/main/examples/iterator.cr): consumer example · `examples/iterator.cr`
- [CI](https://github.com/kojix2/leveldb/blob/main/.github/workflows/ci.yml): integration validation · Validates Crystal behavior against native LevelDB. · `.github/workflows/ci.yml`
- [Shard manifest](https://github.com/kojix2/leveldb/blob/main/shard.yml): package manifest · `shard.yml`

## Connections

- LevelDB namespace → DB: exports
- LevelDB namespace → Options: exports
- LevelDB namespace → Iterator: exports
- LevelDB namespace → WriteBatch: exports
- LevelDB namespace → LibLevelDB: loads bindings
- DB → Options: accepts policies
- DB → Iterator: creates and drives
- DB → WriteBatch: submits batch
- DB → LibLevelDB: database operations
- Iterator → LibLevelDB: iterator calls
- WriteBatch → LibLevelDB: batch calls
- LibLevelDB → LevelDB::Error: translates failures
- LibLevelDB → LevelDB C header: maps C API
- LibLevelDB → System LevelDB: FFI calls
- System LevelDB → LevelDB files: reads and writes
- Usage examples → DB: uses
- Iterator example → Iterator: uses
- CI → System LevelDB: tests integration
- Shard manifest → LevelDB namespace: packages
