How nationalarchives/miiify works
Project type and purpose
• Miiify is a lightweight, full-stack web annotation server built in OCaml.
• It exposes a RESTful API (Web Annotation Model/Protocol) to store and retrieve annotation containers for IIIF viewers.
• It runs in Docker/Kubernetes and offers two pluggable storage backends: “git” (versioned via Git) and “pack” (Tezos-style ledger pack files).
File structure
• Top-level:
• Dockerfile, docker-compose.yml → containerized service
• deploy/k8s → Helm charts for Kong (API gateway), miiify server, miiifyctl (CLI), miiifysearch (search service), cert-manager
• miiify/ → OCaml source: bin/main.ml, lib/* (controller, model, storage_git, storage_pack, db, view, utils), config.json, tests
• doc/swagger.yml → OpenAPI spec
• kong/ → local Docker Compose for Kong
• Patterns:
• MVC-style: controller.ml routes → model + storage → view → HTTP response
• Pluggable storage: storage_git.ml vs storage_pack.ml implementing same signature
• CLI/tooling: miiifyctl for admin tasks, miiifysearch for full-text search
• Config files:
• miiify/config.json or env var MIIIFY_BACKEND
• Kubernetes values.yaml in each Helm chart
Key insights from the README
• REST API endpoints for containers and pages
• Two deployment modes: git or pack backend
• ETag caching, ATD validation
• Sample usage via docker-compose and k8s
Main components and interactions (to represent
a. External clients:
• IIIF viewer (e.g., Mirador) or httpie/curl
• CLI tool (miiifyctl)
b. API gateway:
• Kong ingress (handles TLS, routing, authentication)
c. Core service:
• miiify server pod:
– HTTP controller
– Annotation Container Model
– Storage plugin (git or pack)
– Embedded DB (if any) and ETag caching
d. Ancillary services:
• miiifysearch (optional): full-text search index service
e. Backends:
• Git repository (persistent volume or external Git host)
• Pack storage (persistent volume(s) storing ledger pack files)
f. Kubernetes infrastructure:
• cert-manager (TLS certificates)
• ConfigMaps/Secrets for config.json and env vars
• PersistentVolumeClaims for storage
• Helm charts per component
Architectural patterns and design principles
• Micro-service decomposition:
• API gateway (Kong)
• Core annotation service (miiify)
• Search service (miiifysearch)
• CLI management (miiifyctl)
• Pluggable strategy pattern for storage backends
• RESTful, resource-oriented API
• Container-native deployment (Docker + Kubernetes + Helm)