tegwick
4543f5dc43
The closest existing engine to shard-wiki's own design: DB-canonical (Postgres/MySQL/SQLite) but with a pluggable storage-module abstraction that bidirectionally syncs clean Markdown (+ YAML frontmatter) to Git (also FS/S3/Azure), each provider acting as backup or source of truth. Two big findings: (1) the storage-module interface is concrete adapter-contract prior art alongside Foswiki::Store, and the closer one (medium = Markdown in Git); (2) the engine-maintained bidirectional Git mirror is the ideal file-store attach (clean MD + git history) and, being bidirectional, makes git commit a write path (overlay/patch as a commit, no API). Also GraphQL API (introspection = capability discovery; selective fields = efficient projection) and authn-delegated auth modules + path-based rule ACL. Added UC-68 (engine-maintained bidirectional Git mirror, write-by-commit), UC-69 (typed/introspectable API for schema discovery + selective projection); enriched UC-06/36/38/40/42/57. Catalog now 69 UCs. Architecture for SHARD-WP-0002 T11/T14: storage-module abstraction as 2nd adapter-contract prior art, engine-maintained Git mirror as attach+write surface, GraphQL introspection for capability discovery. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
260614 — Wiki.js deep dive (the storage-module engine that already speaks Git + Markdown)
Date: 2026-06-14
What this is
A focused study of Wiki.js — the modern Node.js server wiki — read through
shard-wiki's lens. Wiki.js is the closest existing engine to shard-wiki's own design:
it is DB-canonical (Postgres/MySQL/SQLite) but abstracts persistence behind pluggable
"storage modules" — Git, local filesystem, S3, Azure Blob — each acting as backup or
source of truth, with the Git module bidirectionally syncing clean .md files (+ YAML
frontmatter) to a repo. That storage-module interface is, in effect, a shipped version
of shard-wiki's adapter contract — the second concrete prior art after Foswiki::Store,
and the closer one (medium = Markdown in Git).
Distinctive material:
- Architecture — Node.js/Vue; GraphQL API over all resources; DB-canonical; Markdown (primary) + HTML + AsciiDoc; path-based hierarchy; modular (storage/auth/search/render/editor)
- Storage modules — provider connector (Git/FS/S3/Azure) with properties + create/
update/delete/sync methods, backup-or-source-of-truth,
injectMetadata()YAML frontmatter; Git module commits every change → version-controlled clean Markdown, bidirectional - GraphQL — typed, introspectable (capability/schema discovery), selective-field projection
- Auth modules (delegated authn) + path-based rule ACL
Contents
| Path | Role |
|---|---|
findings.md |
Architecture, storage modules (≈ adapter contract), Git mirror as attach+write surface, GraphQL, access control, capability profile, INTENT mapping, UC seeds, architecture notes, sources |
Status
Initial deep dive complete. Two new use cases promoted to spec/UseCaseCatalog.md (UC-68
attach an engine-maintained bidirectional Git mirror of clean Markdown, incl. write-by-
commit; UC-69 attach via a typed, introspectable API — GraphQL — for schema discovery +
selective projection); UC-06/36/38/40/42/57 enriched. Logged for SHARD-WP-0002
(T11/T14): the storage-module abstraction as a second adapter-contract prior art (with
Foswiki::Store), the engine-maintained Git mirror as preferred attach+write surface,
and GraphQL introspection for capability discovery + selective projection.
Key takeaway recorded: Wiki.js is the most shard-wiki-shaped engine yet — its storage-module interface is near-isomorphic to the adapter contract, and its Markdown-in-Git mirror is the ideal file-store attach (clean MD, git history, write-by-commit). Boundary: one server-engine candidate shard, DB-canonical with a maintained Git mirror; don't double-sync; honor its access rules; not the federation layer.