# nationalarchives/miiify architecture

> Architecture diagram of the GitHub repository nationalarchives/miiify, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nationalarchives/miiify
- Repository: https://github.com/nationalarchives/miiify

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TD
    Clients["IIIF Viewer / HTTPie / miiifyctl"]:::external
    Clients -->|HTTP GET/POST /annotations| Kong["Kong API Gateway"]:::api

    subgraph "Kubernetes Cluster"
        CM["cert-manager"]:::infra
        CM --> Kong

        subgraph "Services"
            Kong -->|Routes to| MIIIFY["miiify Server"]:::app
            MIIIFY -->|"Search API calls"| SEARCH["miiifysearch Service"]:::app
        end

        MIIIFY -->|"Git push/pull"| GIT["Git Backend (PVC or external Git host)"]:::storage
        MIIIFY -->|"Pack read/write"| PACK["Pack Backend (PVC ledger files)"]:::storage
        Env["Select via MIIIFY_BACKEND env or config.json"]:::note
        Env --> MIIIFY
    end

    CLI["miiifyctl CLI"]:::external
    CLI -->|Admin HTTP Calls| Kong

    click Kong "https://github.com/nationalarchives/miiify/blob/main/deploy/k8s/kong/Chart.yaml"
    click MIIIFY "https://github.com/nationalarchives/miiify/blob/main/miiify/bin/main.ml"
    click SEARCH "https://github.com/nationalarchives/miiify/blob/main/deploy/k8s/miiifysearch/Chart.yaml"
    click CLI "https://github.com/nationalarchives/miiify/blob/main/deploy/k8s/miiifyctl/Chart.yaml"

    classDef api fill:#91caff,stroke:#0366d6,color:#000;
    classDef app fill:#b2f2bb,stroke:#0f5132,color:#000;
    classDef storage fill:#ffd8a8,stroke:#d97706,color:#000;
    classDef infra fill:#e2e3e5,stroke:#6c757d,color:#000;
    classDef external fill:#f0f0f0,stroke:#555,color:#000;
    classDef note fill:#fff3bf,stroke:#d39e00,color:#000;
```
