Portal architecture

LibESys maintains multiple AI workflow repositories under ai-workflows/. Each repository defines how a class of software workspaces is structured, built, governed, and assisted by AI tools. Examples include superbuild-workflow today and planned repositories such as architecture-workflow and adr-workflow.

Those repositories must remain independently versioned, testable, and consumable — often as Git submodules or policy mounts in product workspaces. A single documentation website, however, improves discoverability for humans and provides a stable crawl target for AI agents that need cross-workflow context.

Design decision: one portal, many sources

Rather than hosting documentation only inside each workflow repo (fragmented URLs, inconsistent navigation) or collapsing all authoring into one repo (blurred ownership, submodule coupling), this portal uses a hub-and-spoke publication model:

┌─────────────────────────────────────────────────────────────┐
│                    docs-portal (this repo)                   │
│  docs-common/          portal-authored shared docs           │
│  docs-superbuild/      mirrored from superbuild-workflow   │
│  docs-<workflow>/      mirrored from future workflow repos   │
└─────────────────────────────────────────────────────────────┘
         ▲                    ▲                    ▲
         │ sync               │ sync               │ sync
         │                    │                    │
┌────────┴────────┐  ┌────────┴────────┐  ┌────────┴────────┐
│ superbuild-     │  │ architecture-   │  │ adr-workflow    │
│ workflow        │  │ workflow        │  │ (future)        │
│ docs/ (source)  │  │ docs/ (source)  │  │ docs/ (source)  │
└─────────────────┘  └─────────────────┘  └─────────────────┘

Responsibilities

Layer	Owns	Does not own
Workflow repo	Canonical workflow policy, procedures, templates, AGENTS.md, docs/*.md	Site-wide navigation, cross-workflow landing pages, deployment
Portal repo	Docusaurus site, common docs, per-workflow landing/framing, sync automation, publish pipeline	Authoritative edits to imported workflow body content (except framing)

Docusaurus multi-section layout

The site uses multiple @docusaurus/plugin-content-docs instances, one per content root:

Plugin ID	Content path	URL prefix	Sidebar
common	docs-common/	/common/	sidebarsCommon.ts
superbuild	docs-superbuild/	/superbuild/	sidebarsSuperbuild.ts

Each instance has its own sidebar, route base, and (optionally) edit URL pointing at the correct source repository. Adding a workflow section means registering a new plugin instance — see workflow onboarding.

This approach keeps workflow content physically separated in the repository (docs-<workflow>/ folders), which makes sync scripts straightforward and prevents accidental cross-contamination in Git diffs.

Extension points

New workflow repositories onboard by:

1. Creating docs-<workflow>/ in this portal
2. Adding a docs plugin entry and navbar item in docusaurus.config.ts
3. Adding sidebars<Workflow>.ts
4. Registering the workflow in workflows/registry.yaml and enabling python scripts/sync_workflow.py (and GitLab downstream CI)
5. Publishing a portal-owned intro.md that states the upstream source of truth

Common documentation that applies to all workflows stays in docs-common/ and is edited only in this repository.

Operational characteristics

• Independent workflow evolution: upstream repos merge and release on their own cadence
• Portal rebuild on change: when any upstream workflow docs change, sync and rebuild this site
• Clear provenance: landing pages and edit links identify the authoritative repository
• CI-ready structure: sync scripts and folder conventions are designed for later GitLab pipeline automation without requiring architectural rework