# hashicorp/raft-boltdb architecture

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

- Interactive diagram: https://gitdiagram.com/hashicorp/raft-boltdb
- Repository: https://github.com/hashicorp/raft-boltdb

## Overview

##### Project type and purpose
- This is a Go library (“raftboltdb”) providing a BoltStore implementation of the HashiCorp Raft interfaces (`LogStore`, `StableStore`).
- Its purpose is to persist Raft log entries and stable state to BoltDB, and optionally emit runtime metrics.

##### File structure
- Top-level files:
- bolt_store.go/bolt_store_test.go – core store implementation + tests
- metrics.go – metrics-emission glue
- util.go – supporting helpers
- bench_test.go – benchmarks
- go.mod/go.sum – module definitions
- CI config (GitHub Actions, Travis, lint settings)
- `v2/` directory: a parallel v2 implementation (same structure), indicating a versioned API line.

##### README for additional insights
- Core components: BoltStore, metrics via build tags (`armonmetrics` vs `hashicorpmetrics`).
- External dependencies:
- github.com/boltdb/bolt (persistent KV store)
- github.com/hashicorp/raft (Raft consensus library)
- github.com/armon/go-metrics OR github.com/hashicorp/go-metrics (metrics emitters)

##### Main components
a. Application / Raft layer
- Represents the consuming system (e.g., Consul) that instantiates Raft and injects this store.
b. Raft API
- The `raft` package interfaces (`LogStore`, `StableStore`) that BoltStore satisfies.
c. BoltStore (this library)
- Implements the Raft interfaces. Core module: `bolt_store.go`.
d. BoltDB
- Underlying on-disk key/value store.
e. Metrics adapters
- Pluggable metric clients selected at build time:
- Armon/go-metrics adapter
- HashiCorp/go-metrics adapter
f. Build-tag switch
- Decides which metrics adapter is compiled in (`armonmetrics` vs `hashicorpmetrics`).

##### Relationships and interactions
- Application → Raft package → calls BoltStore APIs (Append, FirstIndex, Get, Set, etc.).
- BoltStore → BoltDB: performs reads/writes within BoltDB buckets.
- BoltStore → Metrics adapter: emits operation-level counters/timers/gauges.
- Build tag → selects which metrics library is linked.

##### Architectural patterns / design principles
- Adapter pattern: BoltStore adapts Raft interfaces to BoltDB calls.
- Plugin/configuration by build tag: metrics backend is swapped at compile time.
- Single responsibility: store logic vs metrics emission vs util helpers separated.
- Versioned API branch (`v2/`) side-by-side with v1 for migration path.

##### Technologies, frameworks, libraries
- Go modules (v1 & v2)
- BoltDB (embedded KV store)
- HashiCorp Raft (consensus)
- Two metrics libraries (Armon & HashiCorp)
- GitHub Actions / Travis CI for build/test
- golangci-lint for static analysis

##### Key callouts
- Data flows: persistent writes vs metrics emission.
- Versioning: v1 vs v2 module paths (`github.com/hashicorp/raft-boltdb` vs `/v2`).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Consumer and Raft API
    subgraph "Consumer"
        App["Application"]:::consumer
    end
    subgraph "Raft API"
        Raft["LogStore/StableStore Interfaces"]:::raftapi
    end

    %% v1 Module
    subgraph "Library v1 Module"
        BS1["BoltStore (v1)"]:::core
        UT1["util.go"]:::core
        MG1["metrics.go"]:::core
        BT1["bench_test.go"]:::core
        T1["bolt_store_test.go"]:::core
    end

    %% v2 Module
    subgraph "Library v2 Module"
        BS2["BoltStore (v2)"]:::core
        UT2["v2/util.go"]:::core
        MG2["v2/metrics.go"]:::core
        BT2["v2/bench_test.go"]:::core
        T2["v2/bolt_store_test.go"]:::core
    end

    %% External Dependencies
    subgraph "External Dependencies"
        BoltDB["BoltDB"]:::external
        subgraph "Metrics Adapter"
            AM["Armon/go-metrics"]:::adapter
            HM["HashiCorp/go-metrics"]:::adapter
        end
    end

    %% Relationships
    App -->|"uses"| Raft
    Raft -->|"Append/Get/Set"| BS1
    Raft -->|"Append/Get/Set"| BS2
    BS1 -->|"reads/writes"| BoltDB
    BS2 -->|"reads/writes"| BoltDB
    BS1 -->|"build tag: armonmetrics/hashicorpmetrics"| AM
    BS1 -->|"build tag: armonmetrics/hashicorpmetrics"| HM
    BS2 -->|"build tag: armonmetrics/hashicorpmetrics"| AM
    BS2 -->|"build tag: armonmetrics/hashicorpmetrics"| HM

    %% Click Events for v1
    click BS1 "https://github.com/hashicorp/raft-boltdb/blob/master/bolt_store.go"
    click T1 "https://github.com/hashicorp/raft-boltdb/blob/master/bolt_store_test.go"
    click MG1 "https://github.com/hashicorp/raft-boltdb/blob/master/metrics.go"
    click UT1 "https://github.com/hashicorp/raft-boltdb/blob/master/util.go"
    click BT1 "https://github.com/hashicorp/raft-boltdb/blob/master/bench_test.go"

    %% Click Events for v2
    click BS2 "https://github.com/hashicorp/raft-boltdb/blob/master/v2/bolt_store.go"
    click T2 "https://github.com/hashicorp/raft-boltdb/blob/master/v2/bolt_store_test.go"
    click MG2 "https://github.com/hashicorp/raft-boltdb/blob/master/v2/metrics.go"
    click UT2 "https://github.com/hashicorp/raft-boltdb/blob/master/v2/util.go"
    click BT2 "https://github.com/hashicorp/raft-boltdb/blob/master/v2/bench_test.go"

    %% Styles
    classDef consumer fill:#E3F2FD,stroke:#2196F3,color:#0D47A1;
    classDef raftapi fill:#FFF3E0,stroke:#FB8C00,color:#E65100;
    classDef core fill:#E8F5E9,stroke:#43A047,color:#1B5E20;
    classDef external fill:#F3E5F5,stroke:#8E24AA,color:#4A148C;
    classDef adapter fill:#E1F5FE,stroke:#039BE5,color:#01579B;
```
