02 · The map, and the DB↔filesystem correspondence

This chapter is the map for the entire book. We'll survey the five crates that make up Quipu-Log, and — more importantly — show in a single table how concepts a database gives you for free appear in their file-based forms. Get that table into your head and the chapters that follow will read much faster.

Five crates at a glance

Quipu-Log is not a single monolithic crate. It's split into five crates by responsibility. Let's see what each one does.

Embedded mode vs. server mode

There are two main ways to use Quipu-Log.

Embedded mode: add quipu-core + quipu-middleware to your Rust service as a library. The audit store runs inside the service's own process. No separate daemon, no network, no database. This is the simplest choice when a single Rust service needs audit logging.

Server mode: run quipu-server as a standalone process and have multiple services (any language) write to it over the HTTP/JSON API. Choose this when you want to consolidate audit records from multiple services in one place, or when you're writing services in languages other than Rust.

The book's backbone: DB ↔ Filesystem correspondence table

Here is the heart of this chapter. If you've worked with databases you already know these concepts: WAL, indexes, lock manager, MVCC, partition deletion, checksums. Quipu-Log implements all of them directly on files, without a database engine. Let's see the full mapping in one shot.

Once this table clicks, later chapters read as "oh, X from DB world is implemented as Y on files." Come back to it whenever something doesn't make sense.

Store layout: the actual file structure

Opening a Quipu-Log store creates the following structure under the root directory.

crates/quipu-core/src/store.rs — AuditStore layout commentroot/
  meta/          type schemas + custom column registry (replayed on open)
  logs/          AuditLog rows
  relations/     log -> target-entity-version relations
  registry/<t>/ one versioned registry table per entity/actor type
  access/        meta-audit (opt-in)
  LOCK           advisory OS lock file

Each directory corresponds to one Table<T> — that is, a single append-only log made up of multiple segment files. In database terms, this is like one table stored in a tablespace (a set of files). Format versioning and more are covered in Ch. 18.