Architecture overview

archAIc is a four-layer stack. Reading bottom to top: HTR output flows in, gets normalised into a pair of indices plus a corpus database, gets served by a small set of application binaries, and emerges through a wide set of standards-shaped endpoints. Every layer is replaceable on its own boundary; nothing higher up reaches around to anything lower down.

The deliberate stance is producer for every standard archAIc speaks. The platform is the one-stop server that emits IIIF manifests, Linked Art records, ISAD(G), EAD, METS, PREMIS, ALTO, PAGE, hOCR, TSDO, AtoM CSV, OAIS DIP-zip, OpenAPI, MCP, and webhooks. It does not act as a downstream client of AtoM, Archivematica, or any other system; sync flows outward, and standards contributions are made from the producer side.

Layer 1. HTR and ingestion

The bottom of the stack is the input pipeline. archAIc does not run HTR itself. It consumes the output of tranSkriptorium’s PrIx (Probabilistic Indexing) pipeline: per-page TSDO JSON for layout and line geometry, plus per-libro .txt files where every line is a word hypothesis (<word> <log-prob> <page> <line> <x> <y> <w> <h> <line-x> <line-y> <line-w>). The gd-cli binary (shipped as the archaic command) discovers collections, libros, and pages under corpora/INDEX/... and corpora/optimized_jpg/..., normalises the layout payloads through gd-ingest, and writes thumbnails plus a corpus SQLite database alongside the original images.

The Rust workspace’s gd-ingest and gd-build crates own this layer (gd-build writes the LMDB index). Nothing else in the stack reads PrIx files directly; the upper layers see the normalised view.

Layer 2. Indices and corpus database

Three storage backends, each shaped for a different access pattern:

• LMDB-backed lexical index under corpora/gd-index/. The gd-engine crate writes a memory-mapped store of FST vocabularies, RoaringBitmap postings, decile-bucket aggregates, and per-page word probabilities. This is where probabilistic KWS lives. RMCR-scale (around 347K pages) lands at about 3 GB on disk and roughly 50 MB resident.
• Qdrant-backed semantic store. gd-semantic computes dense μ-passage embeddings (sliding-window passages over PrIx 1-best paths) and sparse TF-IDF vectors per passage, then upserts both into Qdrant. At query time the two are fused with Reciprocal Rank Fusion, so semantic recall and low-frequency lexical signals both survive.
• Corpus SQLite database (corpora.db). The structured ledger: collections, libros, pages, image and thumbnail paths, Document Logical Units, change log, sync state, audit, encrypted secrets, config. gd-config owns the schema and the migration runner.

All three are written once at build time and read-only at query time. Ground-truth writes from the web UI queue a coalesced reindex; nothing on the hot path touches a writer.

Layer 3. Application binaries

Three binaries sit on top of the indices, all in the same Rust workspace and all sharing the same engine library:

• gd-server. The REST API. axum 0.8, utoipa for OpenAPI, tower-http for CORS and tracing. Serves keyword search, semantic search, DLU CRUD, IIIF endpoints, every export format, and the natural-language Q&A surface.
• gd-mcp. The MCP server. Wraps gd-server over HTTP, exposes roughly 30 tools to AI agents over the Model Context Protocol with OAuth 2.1 + PKCE + JWT, RFC 8414 discovery, RFC 7591 dynamic client registration.
• PHP UI. The curator and researcher web frontend. Today the deployed UI is PHP 8 served by Apache (the dipucoru deployment). An in-progress UI branch is modernising it toward Twig templates, Pest-driven tests, Lit web components for shared widgets, and FrankenPHP as the planned application server. The two run side-by-side under nginx during the migration (dipucoru and newdipucoru). The UI talks to gd-server over HTTP using the same API anyone else can call.

The three binaries are independent processes. They communicate over HTTP, not in-process. Any of them can run on a separate host if the customer needs it.

Layer 4. Standards-shaped surfaces

The top layer is the public face. Every output archAIc emits lands on a named specification, and every spec is reachable through three transports (REST, IIIF, MCP) over the same underlying engine.

• Per page. TSDO, ALTO, PAGE, hOCR, IIIF AnnotationPage.
• Per DLU. Linked Art (CIDOC-CRM JSON-LD), ISAD(G), EAD, EAC-CPF, METS, PREMIS.
• Per libro. IIIF Manifest 3.0, navPlace, Content Search 1.0/2.0, AtoM CSV, OAIS DIP-zip.
• Cross-cutting. OpenAPI, MCP, webhooks, IIIF Change Discovery, Content State, OpenTelemetry.

See the Standards section for the full surface and per-standard pages.

Next

• Technology stack. What archAIc is built on and why.
• Crate map. The Rust workspace, one line per crate.
• Deployment overview. Getting an archAIc node up.