chronicle GitHub ↗
docs documentation

Documentation

Three short paths through these pages, depending on whether you are adopting the library, evaluating it, or extending it. Every page has one job and links out rather than repeating another.

Start

Why It Exists

The problem it solves: every incident, bug or dispute, reduces to what the data was, what it is now, when it changed, and who changed it — and why that answer belongs behind a port rather than in one database.

Getting Started

One program, grown five times: record a change, read the document back, verify the chain, then swap the dev backend for a real database by changing one line.

Understand

Git Model

The side-by-side with git: what Append, Commit, and Head correspond to, the one inversion (git stores snapshots, chronicle stores diffs), and the two git reflexes that deliberately don't exist here.

Architecture

The map — how the repo is laid out, for readers who know Clean Architecture or ports-and-adapters. The rings are go.mod files, not folders.

Design Decisions

The rationale behind that map — one decision per section, each with the alternative that was rejected and what the choice costs. Read it to judge, extend, or argue with the design; you do not need it to use chronicle.

Build

The Kit

chroniclekit end to end — diff a document into changes, seal them, replay them back into display-ready rows, driven by one schema vocabulary.

Sealing Patches

Optional: the RFC 6902 write path, nine stages from request to commit. Only if a client sends you JSON Patch — a patch carries no before-values, and sealing one directly records that gap permanently.

Operate

Operations

Running it for real: picking a backend by consistency model, pool tuning, migrations, pruning, backup and restore, observability.

Reference

Reference

The normative contract — every exported call's inputs, guarantees, and failure modes, the error sentinels, and what the library deliberately does not do.

Concepts

The lookup table for names — hash chain, event sourcing, snapshots, LCA — what each pattern is called, which file implements it, and the prior art it comes from.

Contributing

The invariants a change must not break, the file-by-file reading order for the source, and what the conformance suite expects of a new backend.

Pick a path

Every page has one job. The how pages tell you what to call; the why pages argue the decisions behind it. They link to each other and never repeat each other, so you can read one without the other.

Adopting it — why it exists → getting started → the kit, with reference open when you need the exact contract of a call. Getting started is one program grown five times; it does not ask you to read anything else first.

Evaluating it — why it exists for the problem, design decisions for every choice and what it cost, concepts for the prior art it borrows from, operations for what running it costs. If you know git, the git model is the fastest way to see the whole shape.

Extending it — read the three Understand pages in order: the git model for the vocabulary, architecture for the map onto Clean Architecture names, then design decisions for which of those choices are load- bearing before you change one. Contributing is the invariants, the file-by-file reading order for the source, and how to write a backend; reference is the contract your backend must meet.

Optional side paths, safe to skip until you need them: sealing RFC 6902 patches if a client sends you JSON Patch, and operations when you are ready to run it for real.

Pick a backend

Adapters are optional sibling modules; the core never imports one. Implement the 3-method Log yourself and prove it with conformance.RunLogConformance.

BackendModuleConsistencyLog conformanceSerializable append
changelogmemory.New() adapters/memory in-memory · dev/test only, lost on restart ✓ — can fork
changelogsql.Open(…) adapters/sql transactional MySQL · FOR UPDATE + unique constraints ✓ ✓ fork-free
changelogclickhouse.Open(…) adapters/clickhouse eventual · ReplacingMergeTree + FINAL ✓ — no synchronous locks

Choose adapters/sql when concurrent writers must form one linear chain per document; adapters/clickhouse for cheap columnar retention and analytics where producers serialize per document. The full comparison, and the operational detail behind it, is in operations.