shard-wiki/research/260614-wikijs-deep-dive/findings.md

# Findings — Wiki.js: the storage-module engine that already speaks Git + Markdown

Date: 2026-06-14
Source kind: **modern shipped product** — a server wiki engine; a *candidate shard* and
the closest existing engine to shard-wiki's own design (DB-canonical, but with a
**pluggable storage-module abstraction** that bidirectionally syncs clean Markdown to
**Git**/FS/S3/Azure)
Lens: shard-wiki — storage-module-as-adapter-contract prior art, the engine-maintained
Git mirror as an attach + write surface, GraphQL as a typed/introspectable API, and
path-based access rules

> Why Wiki.js is special in this set. Every prior engine/tool stored content in *one*
> substrate and exposed *one or two* surfaces. Wiki.js is DB-canonical (Postgres/MySQL/
> SQLite) **but abstracts persistence behind pluggable "storage modules"** — Git, local
> filesystem, S3, Azure Blob — each of which can act as **backup *or* source of truth**,
> and the **Git module bidirectionally syncs clean `.md` files (with YAML frontmatter)**
> to a repo. In other words, Wiki.js already does, internally, much of what shard-wiki's
> adapter contract is meant to do: a **versioned, capability-bearing, multi-provider
> persistence interface over Markdown**. It is the second concrete prior art for the
> contract after **Foswiki::Store** — and arguably the closer one, because its content
> is **Markdown in Git**, exactly shard-wiki's native shape.

Contrast set: the engine dives (XWiki DB/components, TWiki/Foswiki file+RCS) and the
modern tools. Wiki.js = **modern server engine, DB-canonical, Git-storage-of-Markdown,
GraphQL API, pluggable modules**.

---

## 1. Core architecture

- **Stack:** Node.js backend, Vue front end; **everything is accessible via a GraphQL
  API** (`/graphql`, with a Playground). The DB is **Postgres** (primary; MySQL/SQLite
  supported), read-replica-capable.
- **Content:** **Markdown (primary)**, plus **HTML** and **AsciiDoc**, via pluggable
  **editors** (Markdown, WYSIWYG/visual, raw HTML). Pages live on **paths** (a path-based
  hierarchy) with tags.
- **Modular architecture:** typed pluggable **modules** — **storage**, **auth**,
  **search**, **rendering**, **editor**. The contract-relevant ones are *storage* (§2)
  and *auth* (§4).
- **3.0:** a large rewrite is in development; storage remains a headline subsystem.

---

## 2. Storage modules — the headline (≈ shard-wiki's adapter contract)

A **storage module** "connects Wiki.js with a local or remote storage provider, to act as
**backup or source of truth** for content. It consists of **properties** (user-set) and
**methods called on events** — create, update, delete content, and sync." Providers
include **Git, local filesystem, S3, Azure Blob**.

The **Git module** is the most-used: **every page change commits to a Git repository**,
turning the wiki into **version-controlled `.md` files**. Content is written as **clean
Markdown**, and `injectMetadata()` prepends **YAML frontmatter** (for Markdown) or HTML
comments (for HTML) carrying page metadata. The sync is **bidirectional** with the remote
repo, and access to the synced files honors Wiki.js **access rules** (§4).

Why this matters to shard-wiki — three distinct payoffs:

1. **Prior art for the adapter contract.** Wiki.js's storage-module interface is a
   shipped instance of what `SHARD-WP-0002` T11 specifies: a *versioned, capability-
   bearing, multi-provider* persistence abstraction, with a backup-vs-source-of-truth
   choice and lifecycle methods (create/update/delete/sync). It joins **Foswiki::Store**
   as concrete prior art — and is closer, because its medium is **Markdown in Git**.
2. **The ideal file-store attach.** A Wiki.js instance with the Git module **is a git
   repo of clean Markdown + YAML frontmatter**, maintained by the engine. shard-wiki can
   attach that repo **directly** (UC-40) — better than reading the DB — and get **git
   history for free** (UC-36, *adopt* not supplement, via the mirror).
3. **A write path via Git, no API needed.** Because the Git sync is **bidirectional**,
   shard-wiki can **write-through by committing Markdown** to the repo; Wiki.js **ingests
   git→DB**. This is overlay/patch application as a *git commit*, not an API call (UC-68).
   Caution: Wiki.js owns the DB↔git sync — **don't double-sync**, and coordinate which
   side is **source of truth** (configurable).

---

## 3. GraphQL — a typed, introspectable external API

Unlike the REST/local-REST tools (Joplin, Trilium, Notion), Wiki.js exposes a **GraphQL
API** over all resources. Two shard-wiki-relevant properties:

- **Introspection = capability/schema discovery.** A GraphQL schema is self-describing;
  an adapter can introspect the content/page schema rather than hard-coding it — feeding
  T11's *capability discovery*.
- **Selective-field projection.** GraphQL fetches **exactly the fields a projection
  needs** (page body vs. metadata vs. tags), reducing over-fetch — relevant to projection
  efficiency and the operational envelope. (UC-69; an external-API sub-mode beside
  Notion's REST, UC-57.)

---

## 4. Auth modules + path-based access rules

- **Auth modules** (local, LDAP, OAuth, SAML, …) — **authentication is delegated to
  pluggable providers**, exactly shard-wiki's **authn-delegated** stance
  ([[shard-wiki-auth-in-core-decision]]).
- **Access rules** are **path-based / rule-based ACL**: allow/deny access to all or
  specific sections of the wiki per group; the Git-synced files honor the same rules. For
  shard-wiki this is a richer ACL than TWiki's per-topic flags (UC-06) — **rule-based by
  path pattern** — and informs how a projection should **honor/surface a shard's
  restricted regions** (union without erasure: show that a region is restricted, don't
  silently drop or expose it).

---

## 5. Wiki.js as a shard — capability profile

| Capability | Wiki.js | Notes for the adapter contract |
|------------|---------|--------------------------------|
| Read | yes (Git mirror / GraphQL / DB) | **Git mirror = clean Markdown** is the best surface |
| Write | yes (GraphQL **or git commit**) | bidirectional Git ingest = write-by-commit (UC-68) |
| Write granularity | per-page | — |
| Identity / addressing | path (+ page id) | path-based; YAML frontmatter carries metadata/id |
| Structure | YAML frontmatter (in-file via Git module) | git-diffable in-text structure (good) |
| History | **git-native via Git module** (else DB versions) | adopt the mirror's git history (UC-36) |
| Native query | GraphQL; pluggable search (DB/Elastic/Algolia) | delegate search; GraphQL selective fetch (UC-69) |
| Translation | Markdown primary; HTML/AsciiDoc too | mostly native; multi-format = light translation (UC-42) |
| Attach modes | **file-store (engine-maintained Git mirror)** / external-API (GraphQL) | clean MD in git is the ideal file-store (UC-40, UC-68) |
| Access control | **path-based rule ACL**; delegated auth modules | authn-delegated; honor restricted regions (UC-06) |
| Storage abstraction | **pluggable storage modules (Git/FS/S3/Azure)** | **adapter-contract prior art** (T11) |
| Content types | pages + media/assets | assets via storage modules |

Verdict: **the most shard-wiki-shaped engine yet.** Best attached via its **Git storage
mirror** (clean Markdown + frontmatter + git history, with write-by-commit), or via
**GraphQL** for live/selective access. Its standout gift is **architectural**: a shipped
storage-module abstraction that is near-isomorphic to shard-wiki's adapter contract.

---

## 6. Mapping to shard-wiki INTENT (compare, do not equate)

### 6.1 Reinforcements

- **Storage modules = the adapter contract, shipped.** A versioned, capability-bearing,
  multi-provider persistence interface with backup-vs-source-of-truth — exactly T11's
  shape, in production (with Foswiki::Store as the other prior art).
- **Markdown-in-Git is the native shape.** Wiki.js validates that a serious engine can
  keep content as **clean `.md` + frontmatter in git** — shard-wiki's preferred medium —
  while still offering a rich app over a DB.
- **authn-delegated** (auth modules) and **git coordination** (Git storage) are both core
  shard-wiki stances, here shipped.

### 6.2 Deliberate divergences (design bugs if conflated)

1. **DB is Wiki.js's canonical store; the Git repo is a maintained mirror.** Treat the
   mirror as the attach surface, but respect that **Wiki.js runs the DB↔git sync** —
   don't double-sync; coordinate source-of-truth (UC-68).
2. **Bidirectional write needs care.** Committing Markdown is a real write path, but
   races with the engine's own sync; apply overlays as commits the engine can ingest
   cleanly, never out-of-band DB edits (overlay before mutation, no silent mutation).
3. **One Wiki.js instance = one shard**, not the federation layer; its access rules are
   the shard's, to be honored/surfaced, not re-implemented.
4. **HTML/AsciiDoc pages** need light translation; Markdown pages are native.

### 6.3 What Wiki.js teaches that shard-wiki should keep

- **Model the contract on a real storage-module interface** (Wiki.js + Foswiki::Store):
  properties + lifecycle methods (create/update/delete/sync) + a **backup-vs-source-of-
  truth** flag + a provider list. (T11.)
- **Prefer the engine-maintained Git mirror** as the attach surface for DB-canonical
  engines that offer one — clean Markdown, git history, and write-by-commit (UC-68).
- **Use GraphQL introspection for capability discovery and selective projection** where a
  shard offers it (UC-69).

---

## 7. Use-case seeds → catalog (promoted 2026-06-14)

Last existing UC is **UC-67**. New UCs **UC-68, UC-69** added; existing UCs enriched.

| Seed | Catalog action |
|------|----------------|
| **Attach an engine-maintained bidirectional Git mirror of clean Markdown** (Wiki.js Git storage module): attach the repo as a file-store shard (clean MD + YAML frontmatter + git history) and optionally **write-through by committing Markdown the engine ingests**; coordinate source-of-truth, don't double-sync | **UC-68 (new)** |
| **Attach via a typed, introspectable API (GraphQL)**: discover the shard's schema by introspection (capability discovery) and fetch only the fields a projection needs (selective projection) | **UC-69 (new)** |
| Pluggable **storage modules** (Git/FS/S3/Azure) = adapter-contract prior art; modular auth/search/render/editor | **enriches UC-38** |
| Git storage = **clean Markdown in git**, the ideal engine-maintained file-store attach | **enriches UC-40** |
| Git history natively via the storage module (**adopt** via mirror) | **enriches UC-36** |
| GraphQL external-API variant (typed/introspectable/selective) | **enriches UC-57** |
| Multi-format (Markdown primary; HTML/AsciiDoc) | **enriches UC-42** |
| Path-based rule ACL; delegated auth modules | **enriches UC-06** (links authz decision) |
| Engine-maintained clean git shard | links UC-02 |

---

## 8. Architecture notes for SHARD-WP-0002 (no UC)

- **Second adapter-contract prior art (T11).** Wiki.js's **storage-module interface**
  (properties + create/update/delete/sync methods + backup-vs-source-of-truth + multi-
  provider Git/FS/S3/Azure) is, with **Foswiki::Store**, the model to base the contract
  on — and the closer one (medium = Markdown in Git). Cite both in T11.
- **Engine-maintained Git mirror (T14).** Add to the attachment taxonomy: for a
  DB-canonical engine that offers a bidirectional Git-of-Markdown mirror, the **mirror is
  the preferred attach + write surface** (clean MD, git history, write-by-commit). A
  cleaner sibling of Joplin's proprietary interchange mirror (UC-60) and the file-store
  native-store kind (UC-40).
- **GraphQL → capability discovery + selective projection (T11/T14).** Typed/
  introspectable APIs give schema discovery (capability negotiation) and reduce over-fetch
  — note alongside Notion's REST external-API mode.
- **authn-delegated + path-based ACL** reinforce the settled authz decision and inform how
  projections honor/surface restricted regions (union without erasure).

---

## 9. Open questions (for spec / workplans)

1. For an engine with a bidirectional Git mirror (UC-68), is the **mirror or the DB the
   source of truth** from shard-wiki's view, and how do we avoid races with the engine's
   own sync (write-by-commit cadence, locking)?
2. When both a **Git mirror and GraphQL** are available, which does a binding prefer —
   mirror for content/history, GraphQL for live/selective metadata? Can one binding use
   both?
3. How does shard-wiki **honor/surface path-based access rules** (UC-06) in a projection
   without re-implementing the shard's ACL engine?
4. Should the adapter contract's **storage-module shape** be standardized directly on
   Wiki.js + Foswiki::Store, or generalized further?

---

## 10. Sources

| Source | Used for |
|--------|----------|
| Wiki.js — GraphQL API docs (https://docs.requarks.io/dev/api) | Everything via GraphQL; `/graphql` Playground; access/modify all resources |
| Wiki.js — Git storage (https://docs.requarks.io/storage/git) | Per-change commit to git; clean `.md`; bidirectional sync with remote repo |
| Wiki.js — Storage overview + dev/storage.md (https://docs.requarks.io/storage ; https://github.com/requarks/wiki-docs/blob/master/dev/storage.md) | Storage module = provider connector; backup-or-source-of-truth; properties + create/update/delete/sync methods; `injectMetadata()` YAML frontmatter; providers Git/FS/S3/Azure |
| Wiki.js 3.0 storage preview (https://beta.js.wiki/blog/2021-wiki-js-3-feature-preview-storage) | Storage subsystem direction (3.0) |
| Wikipedia — Wiki.js (https://en.wikipedia.org/wiki/Wiki.js) | Node.js/Vue, DB options, formats, modular architecture |
| BrightCoding / Grokipedia overviews | Auth providers, access rules, editors, read replicas |

Cross-references: `research/260613-foswiki-deep-dive/findings.md` (Foswiki::Store, the
other storage-interface prior art), `research/260614-joplin-deep-dive/findings.md`
(interchange/sync-mirror contrast), `research/260614-notion-deep-dive/findings.md`
(external-API/REST contrast), `research/260614-shard-spectrum-synthesis/findings.md`
(attachment-mode spectrum), `spec/UseCaseCatalog.md` (UC-02, UC-06, UC-36, UC-38, UC-40,
UC-42, UC-57), `workplans/SHARD-WP-0002-federation-architecture.md` (T11, T14).

---

## 11. Traceability

- New UCs: **UC-68, UC-69** → `spec/UseCaseCatalog.md`.
- Enriched UCs: **UC-06, UC-36, UC-38, UC-40, UC-42, UC-57** (links UC-02, authz decision).
- Architecture (no UC): **storage-module abstraction = 2nd adapter-contract prior art**
  (with Foswiki::Store); engine-maintained Git mirror as attach+write surface; GraphQL
  introspection → capability discovery + selective projection; path-based ACL + authn-
  delegated → `SHARD-WP-0002` (T11, T14).
- Boundary recorded: Wiki.js is **one server-engine candidate shard**, DB-canonical with a
  **bidirectional Git-of-Markdown mirror** that is the preferred attach surface; not a
  substrate and not the federation layer (don't double-sync; honor its access rules).
</content>