Hussh wiki — scalable app + MCP architecture

TL;DR: Hussh evolved the LLM Wiki pattern into a live app: Drive is the private source workspace, Cloud Storage and Firestore are the serving/index plane, the MCP server is the capability boundary, and the Next.js reader is a pure MCP client. Anonymous users see the public wiki at https://wiki.hushh.ai; authenticated owners and agents get the full private corpus, write tools, drafts review, and artifact capture through the same routes and the same MCP endpoint.

Status as of 2026-05-26: Production services are live on Cloud Run: reader at https://wiki.hushh.ai, MCP at https://mcp.hushh.ai. The GCS/Firestore serving mode is implemented for runtime reads and indexes, while MCP writes can now persist through wiki Drive source + GCS/Firestore without creating a Git commit per write. A scheduled backup export job mirrors Drive source markdown into Git for audit/export/bootstrap continuity. The reader uses clean wiki URLs such as /wiki/products/one; legacy .md and /wiki/wiki/... forms redirect for compatibility.

Relations

About Wiki — canonical public guide for how this wiki is created and maintained.
LLM Wiki pattern — landscape & R&D — the foundation pattern this builds on.
Wiki search — dual-audience UX + AX — surface design rationale.
Public vs private surfaces — visibility and auth-tier contract.
Apple frame — the design discipline this app inherits.
BYOA and PCHP — architectural commitments this app must honor.
Artifact capture — chat artifacts as first-class wiki entries — Artifact capture into the wiki
Wiki scaling and search — qmd/search growth path.
Wiki-as-app Architecture (editable source) — Editable source
Wiki-as-app — Three-Tier Architecture — Three-tier architecture diagram
Wiki-as-app editable source — alternate editable-source diagram.
Wiki-as-app three-tier architecture — alternate three-tier architecture diagram.

Runtime map

Layer	Code / content	Job
Private source	Restricted Shared Drive source workspace	Human-editable source workspace, private permission boundary, no-redeploy content CRUD.
Serving plane	Cloud Storage snapshots + Firestore metadata/indexes	Fast public/private reads, search/list indexes, chronology, aliases, checksums, publish state, and self-repair.
Git mirror	Wiki schema, page mirror, and raw-source exports	Daily audit/export/bootstrap history while the hosted serving plane stabilizes.
MCP server	Auth and sync service	Auth, visibility filtering, search, write tools, artifact tools, Drive sync, derived publishing, audit.
Reader	Next.js public/private UI	Auth page, drafts UI, artifact rendering, clean routes.
Deployment	`cloudbuild.yaml`	Builds and deploys `hussh-mcp` and `hussh-wiki` to Cloud Run.
Tests	Core release checks, full MCP audit, and focused reader audits	Public/private safety, UI and route verification.

MCP capability model

Anonymous callers get the public reader and 8 public-safe read tools: wiki_read, wiki_search, wiki_list, wiki_relations, wiki_lint, wiki_history, wiki_diff, and wiki_recent_public.

Authenticated callers get 17 tools: the 8 public reads, wiki_recent_changes, and write/capture/artifact tools (wiki_write, wiki_patch, wiki_link, wiki_delete, wiki_promote_visibility, wiki_capture, wiki_artifact_save, wiki_artifact_delete).

Private MCP resources and prompts are gated too. The full index, schema, non-negotiables, glossary, and operational prompts require auth.

Source and serving architecture

The reader does not read markdown from disk. It calls MCP from server components and route handlers. In GCS/Firestore serving mode, MCP reads from hosted snapshots and metadata rather than scanning Drive or the repo on every request:

The reader-to-MCP client forwards authenticated session evidence when present.
Anonymous server-side calls use short-lived response caching and in-flight de-duplication to keep section pages and sort changes fast.
The route helper maps canonical wiki paths to clean reader URLs.
Draft approval/rejection routes call MCP write tools; they never bypass the MCP audit and visibility rules.
MCP writes use a configurable durability mode. In serving mode they mirror changed content into the wiki Drive source workspace and publish affected derived snapshots into Cloud Storage/Firestore without per-write Git commits; git mode is still available for explicit audit/export workflows.
Direct Drive edits are designed to publish through sync/reconcile without a reader redeploy.
The scheduled backup export job keeps Git current as a mirror without adding Git latency or approval churn to normal MCP writes.

Interface layer

The UI is Apple/Hussh in appearance and Material 3 Expressive in interaction semantics:

M3 semantic tokens live in the shared reader style layer.
MUI remains as component infrastructure where useful: ButtonBase, Dialog, form controls, SSR Emotion cache, and theme overrides.
The Hussh theme layer maps MUI defaults onto Hussh tokens and suppresses defaults that conflict with the desired motion/state layer.
The focused reader audit verifies route, viewport, dialog, topbar, and interaction behavior.

Material 3 Expressive and MUI are not treated as the same thing. MUI is an implementation library; M3 Expressive is the interaction contract.

What changed from the original plan

The original plan described phases and a future build. The live system now has:

One auth-tiered MCP server instead of separate private/public MCP servers.
Clean production domains instead of only Cloud Run URLs.
Drive-backed source plus GCS/Firestore serving for no-redeploy content updates.
Git-backed audit/export continuity with protected-path rules.
Keyword-aware search with capped display relevance and public/private filtering.
Auto-capture with drafts fallback.
Artifact save/delete for code, SVG, mermaid, HTML, images, and documents.
Published/edited chronology, section sort toggles, route transitions, centered popovers, and public list performance fixes in the reader.
A lean core MCP release gate, with the full MCP audit available on demand.

Drift-control rule

Karpathy's pattern says good answers become wiki pages. Hussh adds one more constraint: good implementation decisions must also become repo docs or tests. If the founder-facing concept, the public wiki page, and the code diverge, the fix is not more chat. The fix is a small page/doc/test update that makes the contract explicit.

Architecture streamlining boundary

Current repo truth: the wiki/MCP app can expose public and private pages, but publishing rules must keep private bodies, people/contact details, secrets, and partner artifacts out of public prose.
North-star direction: wiki pages can become the public concept contract only when current repo truth, north-star direction, not-shipped caveats, and source notes are explicit.
Not shipped / not implied: wiki-as-app is not a CRM, personal-knowledge app, or partner storage plane.
Source notes: internal architecture catalog and partner-architecture notes.

Sources

Public vs private surfaces
LLM Wiki pattern
Artifact capture
MCP implementation notes — auth tier and tool/resource/prompt dispatch.
MCP implementation notes — public activity feed.
Reader implementation notes — reader-to-MCP client.
Reader implementation notes — clean wiki route mapping.
Reader implementation notes — Material 3 Expressive and Apple/Hussh tokens.