Skip to content

README.md

Latest commit

 

History

History
181 lines (123 loc) · 5.25 KB

README.md

File metadata and controls

181 lines (123 loc) · 5.25 KB

Entity Resolution Service — Architecture and Specification Documentation

Docs Build & Deploy License

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://meaningfy-ws.github.io/entity-resolution-docs/

Contents

  • ERS Architecture — System scope, actors, capabilities, behaviour spines, conceptual models, and deployment architecture
  • ERS–ERE Technical Contract — Message-based integration specification, idempotent processing rules, and canonical identifier semantics
  • Annexe A: Glossary — Normative definitions of all domain and system terms
  • Annexe B: Use Cases — White (business) and Blue (system) level use cases using Cockburn format
  • Annexe C: Architecture Decision Records — Key architectural decisions grouped by theme (A–G)

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)
│   │   ├── ERSArchitecture/        # Baseline architecture
│   │   │   ├── introduction.adoc
│   │   │   ├── scope.adoc
│   │   │   ├── actors.adoc
│   │   │   └── ... (other pages)
│   │   ├── ERS-ERE-Contarct/       # Technical contract
│   │   ├── 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.