# fgrosse/wal architecture

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

- Interactive diagram: https://gitdiagram.com/fgrosse/wal
- Repository: https://github.com/fgrosse/wal

## Overview

##### Project Type & Purpose
- This is a Go library (not a full-stack app) providing a Write-Ahead Log implementation.
- It exposes a WAL abstraction that clients instantiate, write entries to, and close.

##### Main Components
a. WAL Core (entry.go, wal.go, configuration.go, entry_registry.go)
b. Segment Writer (segment_writer.go)
c. Segment Reader (segment_reader.go)
d. Entry Registry (entry_registry.go + waltest for examples)
e. WAL Segment Files (on disk: *.wal under configurable path)
f. External Dependencies (os filesystem, zap.Logger, CRC library)

##### Relationships & Data Flow
- Client code calls wal.New(path, config, entryRegistry, logger).
→ WAL Core loads existing segment files (Segment Reader) and initializes state.
- Client calls WAL.Write(entry):
→ WAL Core serializes entry metadata (offset, type, CRC, payload) via Segment Writer
→ Writes binary frame to current segment file
→ Optionally calls fsync (SyncDelay / fsync config)
→ Returns offset
- When segment file reaches max size:
→ WAL Core rotates to new segment (closes old writer, opens new one)
- Client calls WAL.Close(): flushes and closes current segment writer.
- On restart, WAL Core enumerates segment files on disk and uses Segment Reader to scan/verify entries, delegating binary decoding to Entry Registry.
- Entry Registry maps byte Type codes ←→ Go Entry instances (factory pattern).

##### Architectural Patterns & Principles
- Single Responsibility: Reader, Writer, Registry, Core orchestration each in separate packages/files.
- Factory/Registry Pattern: entry_registry.go to map binary types to concrete Entry implementations.
- Append-only log segmentation: segment rotation simplifies clean-up and backup.
- Pluggable logging: zap.Logger injection for structured logs.
- Durability configuration via SyncDelay to batch fsyncs.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        ClientApp["Client Application"]:::external
    end

    %% Core Layer
    subgraph "Core Layer"
        WalCore["WAL Core Manager"]:::core
        EntryRegistry["Entry Registry"]:::core
        SegmentWriter["Segment Writer"]:::core
        SegmentReader["Segment Reader"]:::core
    end

    %% Storage Layer
    OnDisk["On-Disk Segments"]:::storage

    %% External Dependencies
    Zap["zap.Logger"]:::external
    OSFS["OS Filesystem"]:::external

    %% Connections
    ClientApp -->|"New()/Write()/Close()"| WalCore
    ClientApp -->|"register Entry types"| EntryRegistry
    WalCore -->|"Write(entry)"| SegmentWriter
    WalCore -->|"on startup"| SegmentReader
    WalCore -->|"logs"| Zap
    SegmentWriter -->|"Append(Frame)+fsync"| OnDisk
    SegmentWriter -->|"open/write"| OSFS
    SegmentReader -->|"Scan/Read frames"| OnDisk
    SegmentReader -->|"decode"| EntryRegistry
    EntryRegistry -->|"factory instantiation"| WalCore

    %% Click Events
    click WalCore "https://github.com/fgrosse/wal/blob/main/wal.go"
    click WalCore "https://github.com/fgrosse/wal/blob/main/configuration.go"
    click EntryRegistry "https://github.com/fgrosse/wal/blob/main/entry_registry.go"
    click EntryRegistry "https://github.com/fgrosse/wal/blob/main/entry_registry_test.go"
    click SegmentWriter "https://github.com/fgrosse/wal/blob/main/segment_writer.go"
    click SegmentWriter "https://github.com/fgrosse/wal/blob/main/segment_writer_test.go"
    click SegmentReader "https://github.com/fgrosse/wal/blob/main/segment_reader.go"
    click SegmentReader "https://github.com/fgrosse/wal/blob/main/segment_reader_test.go"
    click OnDisk "https://github.com/fgrosse/wal/blob/main/testdata/segment.wal"
    click ClientApp "https://github.com/fgrosse/wal/blob/main/example_test.go"
    click ClientApp "https://github.com/fgrosse/wal/blob/main/benchmark_test.go"
    click ClientApp "https://github.com/fgrosse/wal/blob/main/waltest/entry.go"
    click ClientApp "https://github.com/fgrosse/wal/blob/main/waltest/entry_test.go"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef storage fill:#90EE90,stroke:#333,stroke-width:1px;
    classDef external fill:#FFA500,stroke:#333,stroke-width:1px;
```
