Open-source GLAM platform on Laravel 12 - archival description, museum collections, digital asset management, and records management in one system, with Records in Contexts (RiC) as a first-class capability.
A modern, self-hostable alternative to legacy archival and museum software such as AtoM and ArchivesSpace, built for the international GLAM market.
Heratio is a pure Laravel 12 application designed and developed by The Archive and Heritage Digital Commons Group (Pty) Ltd (The AHG). It unifies archival description, museum collections management, digital asset management, digital preservation, and records management on a single standards-based stack (PHP 8.3, MySQL 8, Elasticsearch 8).
Heratio supports galleries, libraries, archives, and museums of any size, and universities managing special collections, institutional archives, and research data together. It is built for the international GLAM market: the core is jurisdiction-neutral, and country-specific compliance (for example GRAP 103, POPIA, GDPR, IPSAS) ships as pluggable per-market modules rather than baked into the core.
Supported standards include ISAD(G), ISAAR(CPF), ISDIAH, Records in Contexts (RiC and RiC-O), and Dublin Core, with the OAIS / PREMIS / OCFL / BagIt preservation stack and IIIF deep-zoom image delivery. Museum collections management is Spectrum-capable, supporting the Spectrum 5.1 procedures.
RiC (Records in Contexts) is a first-class capability within Heratio - not a hidden add-on. Every major entity page supports both a traditional archival view and a RiC contextual view over the same data, permissions, and identifiers.
The RiC-native semantic framework, documentation, and ecosystem is centralised under OpenRiC.
A live demonstration instance is available at https://heratio.theahg.co.za.
- Full archival description, hierarchy, workflows, editing, and administration
- Plugin architecture with modular packages for every functional domain
- Role-based access controls and institutional deployment support
- Import/export flows and digital object management
- NLP-based Named Entity Recognition (NER) pipeline extracts persons, organisations, dates, locations, and subjects
- Extracted entities mapped to archival description fields and authority records
- Human-in-the-loop review - AI suggestions presented for archivist approval before committing
- Model-agnostic architecture supports locally hosted models via Ollama, ensuring data sovereignty under POPIA
- Dual-view on every major entity page: traditional archival view and RiC contextual view
- RiC Explorer with interactive 2D/3D graph visualization (Cytoscape.js, Three.js)
- Automatic sync to Apache Jena Fuseki triplestore
- SPARQL endpoint queryable by external systems
- JSON-LD / RDF outputs and multi-standard export (EAD3, EAC-CPF, Turtle, RDF/XML)
- Semantic search across the archival graph (Qdrant vector search + Elasticsearch)
- EAD/ISAD to RiC-O mapping
- Integrity checking, orphan management, and provenance tracking
- Dedicated portal for field researchers, subject matter experts, and contributing institutions
- Simplified ISAD(G)-mapped description forms accessible to non-archivists
- Five-stage workflow: Draft, Submitted, Under Review, Published, Returned for Revision
- Archivist review gate maintains description quality before public accessibility
- Automated POPIA/GDPR sensitivity screening
- AES-256-GCM digital object encryption for restricted holdings
- On-the-fly decryption for authorised access with streaming delivery
- Full audit logging of access and encryption events
┌─────────────────────────────────────────────────────────┐
│ Heratio (Laravel 12 / PHP 8.3) - Application Layer │
├──────────────┬──────────────┬────────────┬──────────────┤
│ MySQL │ Fuseki │ Elastic │ Qdrant │
│ Archival DB │ RiC-O graph │ Full-text │ Semantic │
│ (AtoM- │ 17.9M+ │ search │ search │
│ compatible) │ triples │ │ │
├──────────────┴──────────────┴────────────┴──────────────┤
│ RiC Explorer - Graph visualization (Flask/Cytoscape.js) │
│ Bootstrap 5 - WCAG 2.1 Level AA │
└─────────────────────────────────────────────────────────┘
Heratio operates alongside the existing AtoM MySQL database. Both application stacks coexist with no code dependency - metadata enriched by Heratio is immediately available through both platforms.
Heratio uses a monorepo plugin architecture:
packages/
├── ahg-core/ - Models, base services, pagination, components
├── ahg-theme-b5/ - Layouts, nav, footer, static assets
├── ahg-information-object-manage/ - IO browse/show (ISAD)
├── ahg-actor-manage/ - Actor browse/show
├── ahg-repository-manage/ - Repository browse/show (ISDIAH)
├── ahg-accession-manage/ - Accession browse/show
├── ahg-donor-manage/ - Donor browse/show
├── ahg-rights-holder-manage/ - Rights holder browse/show
├── ahg-storage-manage/ - Physical object browse/show
├── ahg-term-taxonomy/ - Term + taxonomy browse/show
├── ahg-function-manage/ - Function browse/show (ISDF)
├── ahg-user-manage/ - User browse/show (admin)
├── ahg-settings/ - Settings dashboard (admin)
├── ahg-jobs-manage/ - Jobs browse/show (admin)
├── ahg-iiif-collection/ - IIIF Collection management
└── ... - Additional domain packages
Heratio is the operational platform institutions use.
OpenRiC is the public RiC-native initiative that centralises RiC implementation guidance, semantic architecture, graph capabilities, documentation, mappings, and ecosystem collaboration.
OpenRiC powers the RiC capabilities within Heratio and is available as a standalone framework for the broader archival community.
| Requirement | Version | Notes |
|---|---|---|
| PHP | 8.3 or higher | required for metal install |
| Laravel | 12 | bundled in composer.json |
| MySQL / MariaDB | 8.0+ / 10.3+ | utf8mb4 |
| Nginx | 1.18+ | Apache works too |
| Elasticsearch | 7.x or 8.x | prefix heratio_ |
| Apache Jena Fuseki | 4.10+ | optional, for RiC SPARQL endpoint |
| Ollama | Latest stable | optional, remote - never bundled |
| Docker (alternative) | 24+ with the Compose plugin | Scenario 3 below - replaces every row above |
Heratio supports three install scenarios.
| Scenario | When to use | Entry point |
|---|---|---|
| 1. Overlay onto an existing AtoM database | You already run AtoM and want to add Heratio without losing your catalogue, or you're cutting a customer over from AtoM | ./bin/install-overlay |
| 2. Standalone clean install | No AtoM. New deployment from scratch | ./bin/install - full guide: docs/standalone-install-howto.md |
| 3. Docker test stack | You want to try Heratio without touching the host - laptop demo, CI, throwaway evaluations, libvirt VMs | docker compose -f docker/docker-compose.yml up -d --build |
Scenarios 1 and 2 share the same Laravel-side bootstrap (composer install, .env, key:generate, ServiceProvider auto-seed). The two scenarios differ only in how the database is brought to life. Scenario 3 wraps Scenario 2's pipeline inside a containerised stack - same code, no host setup.
Heratio sits on top of your existing AtoM database without destroying any data. The overlay adds Heratio-only tables, syncs missing columns on shared tables, and seeds Heratio's settings + help - using INSERT IGNORE everywhere so customer customisations are preserved. Re-runnable / idempotent.
git clone https://github.com/ArchiveHeritageGroup/heratio.git /path/to/heratio
cd /path/to/heratio
composer install
cp .env.example .env
php artisan key:generate
# Point .env at your existing AtoM DB
# DB_DATABASE=your_atom_db
# DB_USERNAME=root
# DB_PASSWORD=...
# Dry-run first to see what would change (read-only)
./bin/install-overlay --target=your_atom_db --dry-run
# Apply
./bin/install-overlay --target=your_atom_dbThe overlay runs eight idempotent stages: pre-flight → schema overlay → column-delta sync → settings replicate → help replicate → ServiceProvider boot (auto-seed dropdowns) → Elasticsearch reindex → smoke test.
Full guide: docs/overlay-install-howto.md
For a fresh deployment with no AtoM. bin/install is a 14-stage idempotent installer: preflight → composer → npm build → .env + key:generate → create DB → core schema (database/core/) → plugin schema (heratio:install-bootstrap) → seeds (database/seeds/) → admin user → storage paths → Elasticsearch reindex → nginx config → smoke test. Install the OS prerequisites first (PHP 8.3, MySQL 8, nginx, Redis, Node, Elasticsearch - see the how-to §3). (bin/install-host-tools.sh is separate: it installs the optional 3D / provenance tools only.)
Full step-by-step guide: docs/standalone-install-howto.md. (The original design doc is docs/standalone-install-plan.md.)
A self-contained Compose stack - PHP 8.3 + nginx + MySQL 8 + Elasticsearch 8 - for clients, laptops, CI, throwaway evaluations, and libvirt VMs. Cantaloupe (IIIF) and Ollama (AI) stay external by design.
AI / model policy: The Heratio image contains no model weights or AI runtimes. Heratio is an AI client - HTR, NER, condition scan, and semantic search call out via HTTP to a separate Ollama / vLLM host you operate. The image is fully public on GHCR; nothing in Heratio itself is private. The Dockerfile asserts the AI-free invariant at build time and refuses to build if any model artefact is detected in the build context.
For production demos, customer evaluations, and any "I just want it running" scenario. Pulls a versioned, prebuilt image from GitHub Container Registry. No git clone required.
curl -fsSL https://raw.githubusercontent.com/ArchiveHeritageGroup/heratio/main/docker/install-heratio.sh | bashOr pin to a specific version:
HERATIO_VERSION=v1.41.3 \
curl -fsSL https://raw.githubusercontent.com/ArchiveHeritageGroup/heratio/main/docker/install-heratio.sh | bashThe installer:
- Downloads
docker-compose.client.ymland.env.docker.exampleinto./heratio/ - Prompts for admin email + password + DB passwords + host port
- Sets
vm.max_map_countif running as root (Elasticsearch requires it) docker compose pull && up -d- typical install completes in 30-60 s after the image is local
Image: ghcr.io/archiveheritagegroup/heratio:{latest,vX.Y.Z,X.Y} - multi-arch (amd64 + arm64), so it runs on Apple Silicon clients too. Published by .github/workflows/docker-publish.yml on every release tag.
For contributors and local code-change testing.
git clone https://github.com/ArchiveHeritageGroup/heratio.git
cd heratio
cp docker/.env.docker.example docker/.env.docker
# edit docker/.env.docker - set ADMIN_PASSWORD at minimum
docker compose -f docker/docker-compose.yml --env-file docker/.env.docker up -d --build
docker compose -f docker/docker-compose.yml logs -f heratioFirst boot runs docker/init.sh which mirrors the standalone-install pipeline inside the container: generates .env, runs key:generate, loads database/core/*.sql, runs heratio:install-bootstrap passes 1+2, loads seeds, creates the admin user, and creates the heratio_* Elasticsearch indices. A marker at storage/.heratio-installed makes subsequent boots skip the schema/seed work.
Once the heratio container reports healthy, browse to http://<host>:8088/ and log in.
Reset everything (drops MySQL + ES + uploads volumes):
docker compose -f docker/docker-compose.yml down -vAny KVM host. Downloads the Ubuntu 24.04 cloud image, cloud-inits Docker, deploys the repo, brings the stack up, prints the VM IP:
sudo bin/heratio-vm.sh # default name: heratio-test
sudo bin/heratio-vm.sh --name h2 # custom name
sudo bin/heratio-vm.sh --force # destroy + rebuildDefaults: 4 vCPU, 4 GB RAM, 40 GB disk, bridged on br0. Override with --cpus / --ram / --disk / --bridge.
Full Docker reference (config files, supervisord layout, healthchecks, caveats, AI-policy details): docker/README.md.
Point a subdomain (e.g. heratio.yourdomain.com) to Heratio's public/ directory. Nginx vhost templates ship under config/nginx/ for reference.
php artisan heratio:generate-encryption-keyHeratio is designed to support compliance with:
- POPIA - Protection of Personal Information Act 4 of 2013 (South Africa)
- PAIA - Promotion of Access to Information Act 2 of 2000 (South Africa)
- NARSSA - National Archives and Records Service of South Africa Act 43 of 1996
- GDPR - General Data Protection Regulation (EU)
- ISO 15489 - Records management principles
- ISO 23081 - Metadata for records
Institutions are responsible for configuring the system appropriately for their legislative context.
- Full NER pipeline integration with human-in-the-loop review
- RiC Explorer with 2D/3D graph visualization
- Fuseki triplestore sync and SPARQL endpoint
- IIIF manifest generation for digitised collections
- RiC dual-view on all major entity pages
- Relation-aware editing widgets
- SHACL and semantic validation in admin workflows
- PostgreSQL Heratio-native domains (workflow, audit, enrichment)
- Multi-language NER support (including isiZulu, Sesotho, Afrikaans)
- Bulk shared drive ingestion agent with automated classification
- Document Management (DM) - versioned digital-document workflows, check-in/check-out, redaction, watermarking, derivative chains
- Records Management (RM) - file plans, retention schedules, disposal workflows (recommend / approve / execute / reject / legal hold), audit-grade event log; full ISO 15489 / ISO 16175 alignment
Contributions are welcome. Please read CONTRIBUTING.md before submitting pull requests.
Heratio is released under the GNU Affero General Public License v3.0 (AGPL-3.0).
Heratio is the brainchild of Johan Pieterse, conceived and architected as the operational platform for AI-assisted archival, records, and digital asset management. The AI subsystems and platform were built by:
- Johan Pieterse - concept, architecture, platform lead
- Renaldo Venter - AI engineering
- Stefan du Toit - AI engineering
Heratio runs against the Qubit schema originally created for AtoM (Access to Memory) by Artefactual Systems Inc. (Copyright © 2006–2014, Artefactual Systems Inc., licensed under the GNU Affero General Public License v3.0 - see https://www.accesstomemory.org).
AtoM remains a foundational contribution to the open-source archival software ecosystem. Heratio's data model, descriptive standards (ISAD(G), ISAAR(CPF), ISDIAH, ISDF), class-table inheritance, and many cataloguing patterns derive directly from AtoM's design. Heratio is a Laravel-based platform built on top of that schema; it is not a fork of AtoM and contains no AtoM source code, but its existence depends on Artefactual's two decades of standards work, and that contribution is gratefully acknowledged.
The Heratio team thanks Artefactual Systems Inc., the AtoM contributor community, and the International Council on Archives (ICA) for the standards and tooling on which this work stands.
If you use Heratio in your research, please cite:
@article{pieterse2026heratio,
author = {Pieterse, Johannes Jurie},
title = {AI-Driven Digital Transformation of Unstructured Records:
A Socio-Technical Framework and Proof-of-Concept Implementation},
journal = {Information Systems Frontiers},
year = {2026},
note = {Submitted}
}
@article{pieterse2026samab,
author = {Pieterse, Johannes Jurie},
title = {Artificial Intelligence as Collections Steward:
Enabling Inclusive, Sustainable Museum Collections Management
in the African Context},
journal = {South African Museums Association Bulletin (SAMAB)},
volume = {48},
year = {2026},
note = {Abstract accepted; full paper due 30 May 2026;
editorial decision by 26 June 2026}
}The Archive and Heritage Group (Pty) Ltd Johan Pieterse - johan@theahg.co.za
Heratio in front. RiC beside it. OpenRiC above and beneath it.