Code documentation and coverage
This pass reviews active subsystem boundaries and the seven public code samples. It is a contract review, not a claim that every implementation line needs a comment. Generated output, vendor code, archived styling and historical plans are excluded. Runtime behaviour is unchanged except for docs-only diagram rendering.
Review outcomes
| Subsystem | Outcome | Evidence and contract |
|---|---|---|
| Public web | Updated | Content endpoint, docs source/renderer and gallery filtering; server collection reads avoid client SQLite races. |
| Admin | Updated | Media service owns server credentials and caches local handles; blog plugin injects request-selected stores. |
| Web e2e | Reviewed | Cypress config supports an external server through E2E_BASE_URL; the suite exercises user paths rather than comment text. |
| Utilities | Reviewed | Node, browser and universal entry headers already explain import boundaries; data-backend resolver documents override precedence and errors. |
| Image | Reviewed | Node-only sharp entry, ingest preflight and image limits already identify runtime and input boundaries. |
| Media domain | Updated | SQLite factory opens/migrates storage and returns a caller-owned close handle, even for an injected database. |
| AWS media | Updated | Server/worker adapter entry separates credentials and clients from browser consumption. |
| PostgreSQL media | Updated | Catalog persistence and blob storage are separate; injected pool ownership remains with the caller. |
| Media HTTP client | Updated | Portable UI boundary and typed server-error contract. |
| Media Nuxt | Updated | Build-time route registration is separate from runtime auth and backend resolution. |
| Media player | Updated | Queue serializes both tracks; pending versus in-flight cleanup and error callback obligations are explicit. |
| Base Nuxt layer | Reviewed | Existing config header covers theme, Sass, icons, accessibility and explicit utility imports. |
| UI Nuxt layer | Reviewed | Existing config documents base inheritance, PrimeVue opt-out and app-owned runtime flags. |
| Admin Nuxt layer | Reviewed | Existing config documents host-owned auth, injected blog facade and client-only session pages. |
| likwidlibs | Reviewed | Current entry exports package identity only; no invented runtime API documentation. |
| Theme | Updated | Pure brand-token construction and fill-contrast ranking limits; no claim that choosing the better ink proves AA. |
| Browser examples | Updated | All seven /code excerpts checked against source; standalone helix entry identifies its document-lifetime canvas and random illustrative data. |
| Build scripts | Updated | Nitro output normalizer documents invalid-environment errors and absence of filesystem side effects. |
| Docker | Reviewed | Development Compose selects DynamoDB Local with MinIO; Postgres is opt-in. See the operational Docker guide. |
| SAM infrastructure | Reviewed | Existing infrastructure guide owns Lambda, queues, DynamoDB and CDN provisioning; new diagrams summarize rather than duplicate configuration. |
| GitHub workflows | Reviewed | Development regression precedes the main promotion gate; test and production deployment have separate triggers. |
| Existing architecture work in the original checkout | Deferred | User-owned staged/untracked admin and media docs were not copied into this development-based worktree. Integrate their links after that work lands. |
Reviewed means the listed entry-point contract was checked and adequate documentation retained. It does not imply exhaustive security or runtime verification. Future work should review comments and examples together with the implementation it changes.
Public examples
All samples remain curated excerpts in the existing code content schema. IDs, deep links and public source URLs are stable. Slug normalization is a complete helper; other samples identify omitted imports, types or setup. Gallery filtering and brand-token construction now use current implementations. The helix excerpt includes the local geometry/material declarations it previously omitted.
Security and numerical limits are part of the explanation: HMAC authenticates but does not encrypt; a bounded client cookie is not a durable replay ledger; contrast ranking does not composite alpha or prove every gradient pixel meets AA.
Diagram authoring and maintenance
Use Mermaid fences for static structure, sequences and state transitions. Include accTitle and a one-line accDescr, followed by prose describing the same flow. Keep labels short and split dense diagrams by responsibility. Distinguish current behaviour from proposed changes.
On /docs, rendering is client-only and lazy; SSR and JavaScript-disabled readers retain source. A failed diagram displays its source and a status message. Successful diagrams offer a native source disclosure. Wide diagrams use a named, keyboard-focusable local scroll region so text remains readable without page overflow. Other pages and ordinary code fences keep their existing rendering.
Diagram-authored configuration, click actions and external resources are disabled. Do not put initialization directives, YAML configuration, links or remote images in fences. Prefer theme defaults over author-defined colours; colour alone must never carry meaning. The application supplies contrast roles for both themes, sanitizes generated SVG and does not bind diagram callbacks.
See runtime flows, architecture hub, and contributing.
Follow-ups and verification
The existing source-buffer retry behaviour can recurse indefinitely if a missing buffer is not resolved or cleared by onError. AI continuation cookies cannot enforce durable replay prevention. Both are recorded in the shared follow-up list; this documentation pass does not change those behaviours.
Run documentation catalog/link/source and code-page checks, renderer component/security tests, and the affected Nx build/lint targets. Browser review includes /code copy/navigation and /docs diagrams at phone and desktop widths, keyboard-only access, source fallback, zoom and light/dark themes. Tests must exercise behaviour rather than exact explanatory wording.
Validation record — 2026-10-21
The final Nx web build passed, followed by all 254 Cypress user-path tests, including diagram layout at 320px and 1280px. The 51 focused renderer, documentation catalog/source/link, public-source-link, code-page and component-style tests passed. Git diff whitespace validation passed.
Browser checks confirmed six diagrams, source disclosure by keyboard, 48px disclosure targets, theme redraw, and wrapped descriptions without page overflow at 320px in light and dark modes. Earlier checks covered code sample navigation and copy feedback, ordinary fences, route cleanup and theme-role contrast. Clipboard contents were not independently confirmed.
Full-project lint remains blocked by an existing formatting error in tests/app-orbit-stage.spec.ts. The Nx type-check dependency remains blocked by existing theme-test typing/import errors; focused renderer type checking passed. These checks do not establish full WCAG conformance: physical touch devices, assistive screen readers, actual browser zoom, authenticated admin flows and deployed AWS topology were not verified. A router warning for the unmatched /README link remains a follow-up.
The two build-generated tracked files were backed up and restored to their starting versions with explicit owner authorization. Original-checkout work remains separate. No staging, commit, push or deployment was performed.
Review: direct (Lead) — not independent.