Skip to content

docs/specs/

Post-implementation specifications — the authoritative "what this subsystem is and what it guarantees" reference for shipped features.

A spec captures the final intent and contract of an implementation after a brief's work has fully shipped. It supersedes the brief (which moves out of docs/briefs/ when its phases all merge) and complements the operator reference in docs/<feature>.md.

See CLAUDE.md for the full lifecycle and the rule on when to author a spec.

What a spec is (and is not)

A spec is the durable contract a future re-implementation would need to satisfy. It answers:

  • What does this subsystem do?
  • What invariants does it maintain?
  • What is its public surface (interfaces, env vars, config fields, error semantics, exit codes, on-disk layout, network protocols)?
  • What guarantees does it make to callers / operators?

A spec is not:

  • A changelog — CHANGELOG.md owns that.
  • A how-to guide — docs/<feature>.md owns that for operators.
  • An API reference for individual functions — Go doc comments own that.
  • A history of how the design evolved — git history + retired briefs own that.

When a fact could live in more than one place, this is the split:

Question Spec Operator doc (docs/<feature>.md) Go doc
What does it do / guarantee? yes (one paragraph + invariants) yes (expanded, with examples) —
How do I set it up? — yes —
What config fields / env vars? mention + link to the operator doc yes (full table) the struct field
What's the on-disk / wire format? yes (if a re-implementer needs it) only if operators debug/migrate it —
How does function X work? — — yes

Terminology

Used consistently across specs:

  • Source — origin of image bytes (filesystem / HTTP / S3); never called a "backend".
  • Backend — a pluggable storage or strategy choice (cache: heap / filesystem / s3 / redis; auth access-service: builtin / header / external / oidc).
  • Handler — an HTTP route handler. Service — an IIIF service (e.g. AuthProbeService2). Interface — a Go interface (Source, Authorizer, Hook, RenderCache).

Naming

One file per subsystem. Current specs:

  • scaffold.md — initial project scaffold + cache contract
  • http-interface.md — routes, middleware, status codes, cache/CORS semantics
  • auth.md — IIIF Authorization Flow 2.0 contract
  • presentation.md — IIIF Presentation API 3.0/2.1 serve/derive/viewer contract
  • htj2k.md — HTJ2K decode + distroless image contract
  • cache-filesystem.md — filesystem cache backend contract
  • image-decode.md — resolution-aware decode + source I/O contract
  • bench-harness.md — comparative benchmark harness contract
  • windows-build.md — Windows build/runner contract
  • releases.md — release process contract
  • telemetry.md — Sentry error tracking + OpenTelemetry tracing contract