Integration Map

Integration Map

The UI bundle is the presentation layer for the entire Domus Digitalis documentation ecosystem. Every page across all 15 spoke repositories renders through the same bundle.

Architecture

domus-antora-ui
  │
  ├── npm run build / make
  │       │
  │       ▼
  │   build/ui-bundle.zip (~320 KB)
  │       │
  │       ├── Cloudflare Pages ──▶ ui.domusdigitalis.dev/ui-bundle.zip
  │       │                              │
  │       │                   (CF Access auth)
  │       │                              │
  │       └── Local path ─────────┐      │
  │                               │      │
  │                               ▼      ▼
  │                         domus-docs (hub)
  │                     antora-playbook.yml
  │                               │
  │           ┌───────────────────┼───────────────────┐
  │           ▼                   ▼                   ▼
  │    15 spoke repos      Kroki diagrams       Lunr search
  │    (GitHub HTTPS)      (local/remote)       (index_latest_only)
  │           │
  │           ▼
  │    build/site/index.html
  │           │
  │           ▼
  │    https://docs.domusdigitalis.dev

Playbook Configuration

The UI bundle is referenced in both playbook variants:

Production (antora-playbook.yml):

ui:
  bundle:
    url: ./ui-bundle.zip
    snapshot: true

The build.sh script fetches the bundle from ui.domusdigitalis.dev via Cloudflare Access authentication before running Antora.

Local development (antora-playbook-local.yml):

ui:
  bundle:
    url: /home/evanusmodestus/atelier/_bibliotheca/domus-antora-ui/build/ui-bundle.zip
    snapshot: true

snapshot: true forces Antora to re-read the bundle on every build (no caching).

Bundle Contents

The ui-bundle.zip contains the compiled UI assets:

ui-bundle.zip
├── css/
│   └── site.css          Compiled + minified CSS (all 18 files merged)
├── js/
│   ├── site.js           Bundled files 01-07
│   └── vendor/
│       ├── domus-ui.js   Theme toggle, focus mode, code enhancements
│       └── highlight.js  Syntax highlighting (async-loaded)
├── layouts/
│   ├── default.hbs       Main page layout
│   └── 404.hbs           Error page layout
├── partials/             All 27 Handlebars partials
├── helpers/              9 Handlebars helper functions
├── img/                  SVG icons (back, caret, chevron, home, menu, octicons)
└── font/                 Roboto + Roboto Mono web fonts

How Changes Propagate

  1. Edit CSS, JS, or HBS files in domus-antora-ui

  2. Build: make or npm run build

  3. Push to GitHub

  4. Cloudflare Pages auto-builds domus-antora-ui → new ui-bundle.zip at ui.domusdigitalis.dev

  5. Push to any spoke repo (or domus-docs)

  6. Cloudflare Pages builds domus-docs → build.sh fetches fresh bundle via CF Access → Antora generates site with updated UI

  7. Site live at docs.domusdigitalis.dev

UI changes alone don’t trigger a docs rebuild. Either push to a spoke repo or push an empty commit to domus-docs to trigger a rebuild with the new bundle.

Spoke Registry

Repository Component start_path Category Notes

domus-docs

home

docs

Core

Hub aggregator — contains playbook, build.sh, landing pages

domus-captures

captures

docs

Core

Work chronicles — noindex attribute excludes from Lunr search (size control)

domus-infra-ops

infra-ops

docs/asciidoc

Infrastructure

PKI, VyOS HA, k3s, Vault, DNS, hypervisors (~500+ attributes)

domus-automation-ops

automation-ops

docs/asciidoc

Infrastructure

Ansible, GitOps, IaC workflows

domus-linux-ops

linux-ops

docs/asciidoc

Infrastructure

Arch, RHEL, Fedora, Debian, Ubuntu, Alpine

domus-windows-ops

windows-ops

docs/asciidoc

Infrastructure

PowerShell, WSL, certificates, Active Directory

domus-ise-ops

ise-ops

docs/asciidoc

Network Security

ISE cluster management, policy, profiling (multi-module)

domus-ise-linux

ise-linux

docs/asciidoc

Network Security

Linux 802.1X/EAP-TLS deployment methodology

domus-ise-windows

ise-windows

docs/asciidoc

Network Security

Windows EAP-TLS/TEAP deployment methodology

domus-netapi-docs

netapi

docs/asciidoc

Network Security

CLI docs — 15+ vendor commands (ISE, WLC, Vault, etc.)

domus-identity-ops

identity-ops

docs/asciidoc

Identity

Keycloak, SAML, Active Directory, LDAP

domus-secrets-ops

secrets-infrastructure

docs/asciidoc

Identity

HashiCorp Vault PKI, gopass, age, dsec

domus-siem-ops

siem-ops

docs/asciidoc

Observability

QRadar, Sentinel, Wazuh, Splunk

domus-o11y-ops

o11y

docs/asciidoc

Observability

Prometheus, Grafana, Loki, Wazuh monitoring

domus-python

python-ops

docs/asciidoc

Development

Python 3.11+, uv package manager, automation

Ecosystem Improvement Proposals

Cross-cutting proposals from full ecosystem audit — 2026-04-04. For team review. These affect multiple spoke repos and the domus-docs hub.

Spoke Consistency

Priority Proposal Rationale Effort

P1

Standardize nav_order across 6 missing spokes

windows-ops, ise-windows, captures, gabriel-docs, secrets-ops, and o11y-ops lack nav_order in their antora.yml. Navigation ordering is undefined for these components.

S

P1

Add start_page to identity-ops and o11y-ops

Missing start_page: ROOT:index.adoc means Antora picks an arbitrary landing page for these components.

S

P2

Document component name vs repo name mapping

3 repos have confusing name mismatches: domus-secrets-ops → secrets-infrastructure, domus-netapi-docs → netapi, domus-python → python-ops. Developers xref the wrong name.

S

P2

Standardize doc-id metadata across all spokes

Only infra-ops and netapi-docs define doc-id. The rest lack traceability identifiers.

S

Hub (domus-docs) Improvements

Priority Proposal Rationale Effort

P1

Fix Lunr search config in local playbook

antora-playbook-local.yml loads @antora/lunr-extension without index_latest_only: true. Local search index can grow unbounded. Production playbook is correct.

S

P2

Add gabriel-docs to production playbook

domus-gabriel-docs exists in local and CI playbooks but not antora-playbook.yml. Any xrefs to gabriel-docs break in production.

S

P2

Create "Getting Started" guide in hub

New team members have no onboarding path. A guide mapping: "I need X" → "Go to component Y" would reduce ramp-up time.

M

P3

Evaluate Algolia for captures search inclusion

domus-captures (176 pages) is excluded from Lunr search via noindex to keep index under 25 MiB. Algolia has no size limit.

M

P3

Delete or re-enable GitHub Actions workflow

.github/workflows/deploy.yml is disabled and outdated (missing 5 components). Either delete it or update as a backup pipeline.

S

Playbook Consistency

Priority Proposal Rationale Effort

P1

Align component lists across 3 playbooks

antora-playbook.yml, antora-playbook-local.yml, and antora-playbook-ci.yml have different component counts. Creates environment-specific build failures.

S

P2

Add Antora extension config consistency

Lunr, tabs, and Kroki extensions are configured differently across playbooks. Standardize extension blocks.

S