# ADR: Docs Center and Presentation Center are read from the database on request; the static sites are retired

**Status**: Proposed, revision 2, for Elikem's approval. It replaces revision 1 of this draft (a reader service over pages rendered ahead of time, never submitted) and, once approved, supersedes the phase 1 ADR (Eve 43128520, with its earlier copies 1599918a and 592f5788): the pairs, the publication pipeline and the edge routes that ADR built are removed by the last step of the plan below.
**Date**: 2026-10-11
**Owner request**: Elikem, 2026-10-11: "docs and presentations are now stored in db so they should now all be loaded dynamically from db at the appropriate time" and, shown that revision 1 still rendered pages ahead of time, "I want us to completely move away from the static sites fully." The first request was his of 2026-09-25: "shouldn't it be more like db driven, fetching content from db when user navigates to that page?"
**Related**: the Eve content migration ledger (`infra/hetzner/eve/content-migration.json`), whose "consumers" requirement (Docs Center, Presentation Center, CLI and generators consume database content) is still in progress.

## Pinned sources

Read at commit `593990e87bc` of main. Nothing was built or run for this ADR, and the live build host was not inspected.

- `infra/hetzner/platform/publication_release.py`: `prepare` exports a frozen publication, writes a reader tree, runs `tools/presentations/build-eve-oshun.py` and `tools/render-docs-center.py`, prints deck PDFs, builds the assistant search corpus and the product graph, runs the pytest and browser suites and seals the output.
- `infra/hetzner/platform/publication_pipeline.py`, `publication_pairs.py`, `publication_edge.py`: the two-minute Dev content pipeline, the pair (a publication and the renderer build that built it) and the edge routes `/p/<pair>/` on `docs.<env>` and `presentations.<env>`.
- `tools/docs_center/` (about 15,800 lines of Python): the Docs Center generator. `tools/eve-task-board/lib/bffcorpus.mjs` records 3,121 rendered pages on 2026-09-19, 2,803 with a Markdown source and 318 synthesised.
- `apps/oshun/eve-content/src/app/(payload)/workspace/page.tsx` and `workspace/DocumentReader.tsx`, `GranularReader.tsx`, `Diagram.tsx`, `Visual.tsx`, `PresentationEditor.tsx`: the Workspace already renders documents, diagrams and slides from the database on each request, for signed-in users only.
- `infra/hetzner/platform/edge.py`: on the docs host, `/workspace`, `/admin`, `/api/*` and `/_next/*` already go to the content service; every other path goes to the static pair.
- `infra/hetzner/eve/content_snapshot.py`, `provision-content.py`, `serve-content.py`: UAT already runs a read-only Workspace over a database that holds only the promoted publication's pinned rows.
- `apps/oshun/bff/src/assistant/served-pair.ts`, `presentation-library.ts`, `presentation-sources.ts`, `docs-search.ts`, `retrieval/dense-index.ts`, `product-graph-inputs.ts`, `product-graph-runtime.ts`: the BFF reads the slide library, the search corpora and the product graph as files of the served pair.
- `apps/oshun/admin/src/lib/presentation-center-files.ts` and `src/app/presentations/**`: the admin console serves the Presentation Center from mounted pair files, behind the operator session.
- `tools/eve-graph/compile-product-graph.mjs`: the `product-graph` section of the `eve_graph` schema is compiled from the file artifact.

## 1. Context

Documents and presentations are written, reviewed and approved in Eve's PostgreSQL. Reading them is still split in two. The Workspace reads the database directly. The Docs Center and the Presentation Center are static sites: a pipeline exports a frozen copy of the approved content to a file tree of about 5.8 GB, renders every page, tests the result and seals it, and the edge serves the files.

Phase 1 (ADR 43128520) took that build out of code releases and stopped UAT rebuilding it. It kept the build itself. What remains:

- **Approved content is not readable until a build passes.** A pass renders and checks the whole corpus (about 70 minutes of content stages were measured on 2026-09-25, before phase 1). A failed pass leaves the old content in place.
- **A freeze is a separate act from approval.** Dev shows an approved revision only after someone freezes a new Dev content selection, and Dev releases have stopped because the selection predated an approved revision.
- **Two readers, two renderers.** The same document is rendered by Python for the Docs Center and by the Workspace for signed-in readers, with separate tests, and they can differ.
- **Machinery.** About 3,500 lines of pipeline, pair and edge code with two timers, a renderer cache, a PDF store, tracing of every file the renderers read, and build artifacts on disk for every pair still served.

The static build gave two guarantees. This ADR changes both, and says how in decision 8:

- UAT served files byte-identical to what Dev tested.
- The checks ran on every page readers would get.

## 2. Decision

The Docs Center and the Presentation Center stop being sites that are built. A reader's request is answered by the content service, which reads the approved revision from PostgreSQL and renders it then. No page is rendered ahead of time, no file tree is exported, and the edge serves no content files.

1. **One reader.** The Workspace's reader (`apps/oshun/eve-content`) becomes the reader of every document and presentation. `docs.<env>` and `presentations.<env>` route every path to the content service. The Python generators, the pair and the pipeline are removed (decision 9).

2. **What a reader sees on Dev: the latest approved revision of each document, from the moment it is approved.** Approval is publication on Dev. The Dev content selection and its freeze are removed, and with them the rule that a release waits for a selection that includes an approved revision. Authors and reviewers keep seeing drafts and revisions in review in the Workspace, as now.

3. **What a reader sees on UAT: the promoted publication, as today.** A publication stays an immutable record of (document, revision, content hash). Promotion to UAT freezes one from Dev's approved revisions and copies its pinned rows into the UAT database, which the read-only UAT content service already serves. Promotion stays Elikem's explicit act. Nothing else creates a publication.

4. **Old addresses keep working.** Every Docs Center and Presentation Center path that exists today (a document's legacy path, a deck, a slide anchor, a `/p/<pair>/…` path) redirects to the same document, section or slide in the reader. A path with no document answers 404. The redirect table is written once from the last static build's file list and kept in the database.

5. **Presentations are read in the same reader.** The Workspace's slide view grows into the full deck reader: the catalog, a deck's slides in order, presentation mode, narration playback, source excerpts and downloads.
   - Narration audio and images are already media in the object store and are streamed from there, with byte ranges.
   - A deck's PDF is printed from the reader's own page the first time it is asked for, and kept in the object store under the revision's content hash. A later request for the same revision gets the kept file.
   - The admin console's `/presentations` reads the catalog and slides through the content API with the operator's session, not from mounted files.

6. **Pages made from code become data.** Seventeen page families have no document behind them. They are computed from tracked files: the entity catalog, API and contract reference, Rust crates, dependencies, data schema, lifecycle, events, errors, configuration, observability, performance, localization, ComfyUI workflows, Unreal reference, testing map, repo map and owners. Each Dev code release computes these as records and writes them to PostgreSQL under its commit; the reader renders them on request, for the commit the environment runs. This is minutes of a release and depends on no content. A family Elikem strikes in section 6 is dropped and not ported.

7. **Search and the assistant read the database.**
   - The search corpus (sections with their anchors, slides, and the code records of decision 6) is rows in PostgreSQL full-text search, written when a revision is approved or a release writes code records, split by audience as today. The member corpus stays empty, and member search stays off, until pages are cleared for members.
   - Dense retrieval keeps exact cosine in the BFF, because pgvector cannot compute a distance on this host. Embeddings are stored per section by content hash, so an approval embeds only the sections that changed.
   - The slide tools read the catalog, chapters and source excerpts through the content API.
   - The product graph's document inputs are compiled into `eve_graph` straight from the database and the code records. The file artifact and its mount are removed.
   - On UAT each of these reads the UAT database, so search there answers from the promoted publication.

8. **Checks move to where the content changes, and the two guarantees change.**
   - **Per revision, before approval.** Link checks, walkthrough-result pins, presentation validators and the document-code couplings (the SMX scorecard record, the route matrices) run on a revision when it is submitted. A revision that fails cannot be approved. Today they run on a whole built site.
   - **Per code release.** The reader's unit and browser tests run against fixtures, and against a fixed sample of real documents and decks read from Dev: the largest, the most diagram-heavy, one of every kind and format.
   - **Nightly, on Dev.** A crawl requests every document, deck and code-record route and reports any that fails to render, as a `platform-ops` task.
   - **What is given up.** UAT no longer serves bytes Dev tested. It serves the same revisions, rendered by the reader code of the commit Dev tested (the UAT content service already refuses to start on any other commit). A page that renders wrongly is found by the sample or the nightly crawl, not before every publication.

9. **What is removed**, by the last step of the plan and not before:
   - `infra/hetzner/platform/`: `publication_release.py`, `publication_pipeline.py`, `publication_pairs.py`, `publication_edge.py`, `publication_outputs.py`, `publication_inputs.py`, `publication_artifacts.py`, `pair_links.py`, `build_poppler.py`, `renderer_trace/`, their tests, and the parts of `publication_deployments.py`, `release.py` and `rollout.py` that select, prepare, mount or point at a pair.
   - The timers `oshun-publication-pipeline` and `oshun-edge-reconcile`; the pair, pointer and edge-report tables and endpoints in Eve.
   - `tools/docs_center/`, `tools/render-docs-center.py`, `tools/render-vdocs.py`, `tools/presentations/build-eve-oshun.py` and the build-only parts of `tools/presentations/`, `tools/build-assistant-docs-search.mjs`, `tools/build-publication-product-graph.mjs`, and `tools/eve-content/export-publication.mjs` and `prepare-publication.mjs` as build inputs (the export stays as a recovery and review tool, skill `eve-publication-inputs`).
   - The GitHub workflows `vdocs-html-fresh.yml` and `vdocs-reader-ui.yml`.
   - The BFF and admin file mounts and `served-pair.ts`.
   - On the build host: `ci/publications`, the pair exports, the presentation cache and the PDF store.
   - `AGENTS.md` loses the freeze step in "Content lands in order" and the assistant's standing authority to freeze a Dev content selection, which has nothing left to act on.

## 3. Alternatives considered

- **Keep phase 1 (built once per publication, promoted by pointer).** Rejected by Elikem on 2026-10-11: it is still a static site with a build.
- **A reader service over pages rendered when a publication is validated (revision 1 of this draft).** It keeps both guarantees and removes only the edge's file serving. Rejected by Elikem on 2026-10-11 for the same reason: every page is still rendered ahead of time by a pipeline.
- **Render in the browser from an API.** Rejected: the renderer that turns content into markup must stay on the server, where content is data and cannot run as code; first paint and accessibility are also worse.

## 4. Plan

Each step ships on its own and leaves the static sites serving until step 7. A step is done when its tests pass on Dev.

1. **Documents on the docs host.** Reader routes for every document kind and format the Docs Center shows, its navigation (products, disciplines, domains, walkthroughs, the library) read from the database, and the redirect table of decision 4. Measure render time for the 20 largest documents and set a budget before step 7.
2. **The deck reader** of decision 5, with narration, source excerpts, downloads and on-request PDFs.
3. **The admin console and the slide tools** read through the content API.
4. **Search and the product graph** from the database (decision 7), with the existing retrieval checks run through the new path.
5. **Code records** (decision 6), family by family, most used first.
6. **Checks** (decision 8): the per-revision gate, the release sample and the nightly crawl.
7. **Switch and remove.** Point both hosts at the content service on Dev, then promote to UAT, then remove everything in decision 9 and close the ledger's "consumers" requirement.

## 5. Consequences

**Gains**
- An approved revision is readable on Dev at once. No build, no freeze, no pass that can fail and hold content back.
- One renderer and one reader to build, test and design.
- The content pipeline, its two timers and its disk use are gone from the build host; code releases and content no longer take turns for it.

**Costs and risks**
- **No fallback.** Static files were served while PostgreSQL or the content service was down. After step 7, readers get an error page until the service is back.
- **Rendering errors can reach readers** between the release sample and the nightly crawl (decision 8).
- **UAT is no longer byte-identical to Dev.** Same revisions, same reader commit.
- **A large port.** The Docs Center's navigation and its seventeen code-derived families are rebuilt in the reader, and the deck reader has to match the static Presentation Center. About 92 pytest and 133 browser tests of the Docs Center, and about 735 pytest tests of the presentation build, are rewritten against the reader or retired with the code they test.
- **Render cost moves to request time.** The largest documents need the Workspace's bounded parts, and a rendered revision may be cached in the content service's memory by content hash. Not measured yet (plan step 1).

## 6. Decisions asked of Elikem with this approval

Approving the ADR approves each recommendation unless he changes it.

- **Who may read.** Today `docs.<env>` and `presentations.<env>` serve pages without sign-in, and the Workspace requires it. Recommended: sign-in required on both hosts, as the Workspace is now; nothing on Dev or UAT is public. The other choice is an anonymous read-only role limited to approved revisions.
- **Approval is publication on Dev** (decision 2). Recommended. The other choice keeps a freeze on Dev, and with it the step that has stopped releases.
- **The seventeen code-derived families** (decision 6). Recommended: port all, in the order of step 5. Any he names instead are dropped.
- **No fallback during an outage** (section 5). Recommended: accept it for Dev and UAT.
