Knowledge Publishing Architecture Wiki

A living knowledge base of design decisions, trade-offs, and architectural patterns for ListHub and WikiHub — two products that share DNA but optimize for different things.

What this is

This is a Karpathy-style LLM wiki: a markdown knowledge base that grows over time as we make decisions, discover patterns, and learn from implementation. Each article captures a specific trade-off or decision with enough context for a future agent or human to understand why.

Index

Architecture

• [[beads-vs-wikihub-architecture]] — Steve Yegge's Beads (SQLite→JSONL) vs WikiHub (git→Postgres): why they flip source-of-truth direction
• [[git-source-of-truth-rationale]] — Why git is the source of truth for public content in WikiHub (not Postgres)
• [[no-content-duplication]] — Public content lives in git only, private in Postgres only, never both
• [[two-bare-repos-per-wiki]] — Authoritative + public mirror architecture
• [[post-receive-vs-plumbing]] — No-loop sync invariant: hooks fire one way, plumbing the other

Data Model

• [[acl-codeowners-pattern]] — .wikihub/acl glob-based permissions, most-specific wins
• [[private-bands]] — <!-- private --> HTML comment sections as lightweight sub-file privacy
• [[visibility-modes]] — The 8-mode vocabulary: private, public, public-edit, unlisted, unlisted-edit, signed-in, link-share, shared
• [[frontmatter-acl-specificity]] — Frontmatter wins for its file, ACL globs below, repo default at bottom

ListHub Specific

• [[listhub-db-git-mirror-pattern]] — DB source-of-truth + one-way per-user bare git mirrors
• [[listhub-sqlite-vs-postgres]] — Why ListHub uses SQLite (single-server, simple) vs WikiHub's Postgres
• [[bare-repo-provisioning-bug]] — jacobcole has no bare repo — signup never calls git init --bare

Open Questions

• [[milkdown-editor]] — Rich editor choice (pending)
• [[quartz-style-reference]] — Style reference only, don't fork
• [[deployment-domain]] — wikihub.globalbr.ai? New Lightsail? Cohabit with ListHub?
• [[concurrent-edit-posture]] — Last-write-wins vs git-merge vs optimistic-lock
• [[events-jsonl-scope]] — v1 or v2? Content+permission mutations only, not stars/views

How to contribute

Each article should follow this pattern:
1. Decision/trade-off in the title
2. Context — what problem are we solving?
3. Options considered — what did we evaluate?
4. Decision — what did we pick and why?
5. Consequences — what does this enable or constrain?

Products covered