Kevin Wiki UI Architecture
The wiki reader is a Next.js App Router app that renders flat markdown as a private/public knowledge site with search, diagrams, graph views, server-side gating, and crawler/agent discovery endpoints.
Runtime Layout
| Layer | Role |
|---|---|
ui/ |
Next.js reader app; local dev on port 4000 |
../wiki/ |
source markdown tree in local development |
ui/.content/wiki/ |
bundled markdown snapshot for Vercel runtime |
/api/search |
debounced typeahead and search page backing API |
/wiki/meta/knowledge-graph/view |
3D force graph view built from page index |
| public discovery endpoints | /sitemap.xml, /robots.txt, /llms.txt, /llms-full.txt, /opengraph-image |
Content Pipeline
Local development reads from ../wiki at request time. Production builds run scripts/bundle-wiki.mjs from prebuild, copying markdown into .content/wiki because parent directories are not available to the Vercel runtime when the root directory is ui.
Rendering
The app renders markdown with:
- theme-aware monochrome UI
- Mermaid diagram blocks
- Recharts chart blocks
- article toolbar: copy, download, share, reading time
- heading anchors with click-to-copy
- animated navigation rails respecting
prefers-reduced-motion
Privacy and Gating
Private content is withheld server-side until the unlock cookie is present. Global passwords come from WIKI_GATE_PASSWORD / WIKI_GATE_PASSWORDS; per-article gate_passwords can share single pages. Private pages are excluded from search/listings and should be noindex.
Production can expose a curated public subset with WIKI_PUBLIC_CATEGORIES=1 or WIKI_VISIBLE_CATEGORIES.
Search and Discovery
The UI's HTTP search is separate from qmd, but both serve the same broader memory architecture. qmd is the agent-facing retrieval layer; the UI search is the reader-facing layer. Public deployments also publish llms.txt and llms-full.txt so crawlers and AI agents have a canonical entry point.
Operational Invariants
- Set
NEXT_PUBLIC_SITE_URLin production so canonical URLs and discovery feeds resolve. - Run build-index/qmd after broad wiki edits before trusting search.
- Keep private categories out of public sidebar/search when
WIKI_PUBLIC_CATEGORIES=1. - Bundle content during Vercel builds; do not assume
../wikiexists at runtime.
Architecture Position
| Axis | Value |
|---|---|
| Family | Memory, context, and retrieval |
| Boundary owned | Next.js reader app for the flat-file wiki: rendering, search, graph, privacy, crawler endpoints. |
| Read with | Wiki Content Bundle Pipeline, Knowledge System Architecture Comparison, Agent Memory System Architecture |
| Use this page when | working on the wiki reader app |
Timeline
-
2026-07-01 | Architecture category refresh added this page to the Memory, context, and retrieval family, linked it to Architecture System Map, and kept it standalone because it owns this boundary: Next.js reader app for the flat-file wiki: rendering, search, graph, privacy, crawler endpoints. Source: User request, 2026-07-01
-
2026-06-18 | Expanded with current UI README details: content bundling, discovery endpoints, server-side gating, search split, and operational invariants. Source: User request, 2026-06-18; ui/README.md
-
2026-05-31 | Architecture page compiled from UI README and wiki graph. Source: ui/README.md