Entity Resolution Service — Architecture and Specification Documentation

This repository contains the official baseline architecture, technical specifications, and use-case catalogue for the Entity Resolution System (ERSys) ecosystem.

The documentation establishes the architectural foundation, integration contracts, and decision records that govern all ERSys implementations.

📖 Documentation

Live documentation: https://OP-TED.github.io/entity-resolution-docs/

Contents

• ERSys — System overview, getting-started guide, examples, architecture, and use-case catalogue
• ERS — Capabilities, configuration reference, API integration guide, and REST API references (ERS and Curation)
• ERE — ERS–ERE Technical Contract, developer guide, and reference implementation
• Curation App User Guide — UI walkthrough for curators: decisions queue, action history, and user management
• Glossary — Normative definitions of all domain and system terms
• Use Cases — Business and system level use cases using Cockburn format

---

Getting Started

Prerequisites

• Node.js (v18+) and npm — for building the documentation
• Python 3 — for local preview server
• Make — for convenient build commands (optional but recommended)

Install Dependencies

# Initialize Antora and install required packages
make install-antora

Or manually:

npm install
npm install -D antora @antora/cli @antora/site-generator
npm i -D @sntke/antora-mermaid-extension

---

Building the Documentation

Build locally

make build-docs

Output is written to docs/build/site/.

Or manually:

npx antora docs/antora-playbook.local.yml

Preview locally

Build and serve at http://localhost:8080:

make preview-docs

Then open your browser and navigate to http://localhost:8080.

To stop the server, press Ctrl+C.

Clean build artifacts

make clean-docs

---

Updating the Documentation

Directory structure

docs/
├── modules/ROOT/
│   ├── pages/
│   │   ├── index.adoc              # Landing page (high-level orientation)
│   │   ├── ERSys/                  # ERSys overview, getting started, examples
│   │   ├── ERSArchitecture/        # Baseline architecture
│   │   ├── ERS/                    # ERS capabilities and configuration
│   │   ├── ERS-ERE-Contract/       # ERS–ERE Technical Contract
│   │   ├── ERE/                    # ERE developer guide and reference implementation
│   │   ├── UserGuide/              # Curation App user guide
│   │   ├── api-docs/               # REST API references (autogenerated + integration guide)
│   │   ├── AnnexeA-Glossary/       # Glossary
│   │   ├── AnnexeB-UseCases/       # Use cases
│   │   └── AnnexeC-ADRs/           # Architecture Decision Records
│   ├── images/                      # Images and diagrams
│   └── nav.adoc                     # Navigation tree for the sidebar
├── antora-playbook.local.yml        # Local Antora config (development)
└── antora-playbook.yml              # Production Antora config

Editing pages

1. Edit an existing page — modify the corresponding .adoc file in docs/modules/ROOT/pages/.
2. Add a new page — create a new .adoc file and update nav.adoc to include it in the navigation tree.
3. Build locally — run make preview-docs to see your changes.
4. Commit and push — once satisfied, commit and push to your feature branch.

Deployment

CI/CD (GitHub Actions)

Documentation is automatically built and deployed via GitHub Actions:

• On pull requests to develop — the Antora build runs to verify the docs compile without errors.
• On push/merge to develop — the docs are built and deployed to GitHub Pages.

The workflow is defined in .github/workflows/docs-build-deploy.yaml.

Manual deployment

Build the site locally and upload docs/build/site/ to any static host:

make build-docs

---

Contributing

1. Create a feature branch from develop:

   git checkout develop
   git pull
   git checkout -b feature/ERS-XXX-description

2. Edit documentation using AsciiDoc (.adoc files).

3. Preview locally:

   make preview-docs

4. Commit and push:

   git add docs/modules/ROOT/pages/...
   git commit -m "Brief description of changes"
   git push origin feature/ERS-XXX-description

5. Open a Pull Request against develop.

6. Merge after approval — GitHub Actions will automatically build and deploy to GitHub Pages.

---

License

This documentation is licensed under the Apache License 2.0.

You are free to:

• Use, copy, and modify the documentation
• Distribute it, with or without modifications
• Use it for commercial and private purposes

Under the condition that you:

• Include a copy of the Apache 2.0 license with any distribution
• Provide attribution to the original authors
• State significant changes you made to the documentation

See LICENSE for the full text.