Skip to content
g! grite refs/grite/wal grite init
Architecture

How grite works

One decision — put the issues in git refs — makes everything else fall out. No server, no database, no merge conflicts. Here is the whole pipeline in one screen.

  grite issue create / label / close
             |
             v   (append-only, CBOR, optionally Ed25519-signed)
   +---------------------------+
   |  refs/grite/wal           |   the WAL — source of truth
   |  event  event  event  ... |   content-addressed, immutable
   +---------------------------+
             |
   git fetch | git push        (sync through your existing remote)
             v
   +---------------------------+     +---------------------------+
   |  local clone A            | --> |  CRDT merge               |
   |  local clone B            | --> |  LWW scalars + set labels |
   +---------------------------+     +---------------------------+
                                            |
                                            v   (deterministic, order-independent)
                                   current issue state  →  grite list / show

The flow, step by step

  1. 1

    Append the event

    Every issue mutation — create, label, assign, close — is written as an append-only, CBOR-encoded event under the git ref refs/grite/wal. Nothing is edited in place.

  2. 2

    Sign it (optional)

    Events can be signed with a per-actor Ed25519 key, binding each mutation to an author for non-repudiable provenance.

  3. 3

    Sync through git

    The WAL travels through your existing remote. git fetch pulls new events; git push shares yours. No API, no keys, no service.

  4. 4

    Merge deterministically

    When two clones diverge, grite merges their WALs with CRDT rules — last-write-wins on scalars, commutative sets on labels and links. The result is identical regardless of merge order.

  5. 5

    Project to state

    grite folds the event log into current issue state (optionally cached by the daemon) so listing and querying stay fast, while the WAL remains the single source of truth.

The WAL

An append-only, CBOR-encoded event log under refs/grite/wal. Content-addressed, so history is tamper-evident and always reconstructable.

The merge

Conflict-free replicated data types: last-write-wins on scalar fields, commutative-set semantics on labels and dependencies. Any two WALs merge to the same result.

The interface

A single CLI, with an optional daemon that keeps the projected state warm and serialises concurrent calls. The CLI works standalone.

New to some of these terms? The glossary explains CRDTs, event logs, and git refs in plain language. Ready to try it? Head to the quickstart.