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

# MojoMojo — deep dive (findings)

**Date:** 2026-06-14 · **Source:** SHARD-WP-0003 T8 · **Subject:** MojoMojo, a Perl
Catalyst wiki/CMS.

## Why this dive

The file-store classics (TWiki, Foswiki, Oddmuse, UseMod) keep pages as files; the modern
SaaS keep them behind APIs. MojoMojo is the **classic relational-DB-backed** wiki — a
Catalyst MVC app over **DBIx::Class** with pages and their history in **SQL tables**, and
**no file store and no first-class content API**. It anchors the *"attach by reading the
database directly"* hard case the adapter contract must account for (T13/T14).

## 1. Architecture

- **Stack:** Perl **Catalyst** (MVC web framework) + **DBIx::Class** (ORM) over a relational
  DB (SQLite / PostgreSQL / MySQL). Templating via Template Toolkit.
- **Content:** **Markdown** (Text::MultiMarkdown) is the page markup — so the *body* is
  Markdown, but it lives **in a DB column**, not a file.
- **Pages are hierarchical:** a **path tree** (`/parent/child`) modeled as rows with
  parent/lineage relations — structure is relational, not directory-based.
- **Versioning:** each page edit creates a **new version row** (a `page_version`-style
  table) — full revision history lives in **DB version tables**, with author/timestamp.
- **Features:** inline **AJAX editing**, **attachments** (stored as DB rows / blobs +
  metadata), diffs, RSS feeds, full-text search, per-page permissions.

## 2. The attach problem — DB or nothing

MojoMojo exposes its content through the **web app** (HTML) and the **database**; there is
**no clean REST/GraphQL content API** and **no file store**. So a shard adapter has two
realistic paths:

1. **Direct relational read** (preferred): read the `page` + `page_version` (+ `content`,
   `attachment`) tables via DBIx::Class schema — pages, the path tree, and **full history**
   are all there, importable to the coordination journal (UC-41-style history import, but
   from **DB version rows** rather than RCS/git).
2. **HTML scrape** (fallback): parse rendered pages — lossy, last resort.

This makes MojoMojo the **direct-DB-read** binding archetype: the canonical store is a
relational schema, and the adapter's job is to map that schema to the wiki page model +
journal.

## 3. Capability profile

| Dimension (synthesis spectrum) | MojoMojo |
|--------------------------------|----------|
| Attachment mode | **direct DB read** (relational); HTML-scrape fallback; no file store, no API |
| Addressing granularity | page (row); path tree via lineage rows |
| Content identity | DB page id; path as human key |
| Identity vs placement | row id vs path lineage (separable) |
| Structure | **relational**: page rows + parent/lineage; attachments as rows |
| History | **DB version tables** (per-edit version rows, author/timestamp) |
| Merge model | app-level last-writer; DB transactions |
| Native query | SQL over the schema (not a wiki query language) |
| Translation | **Markdown body in a DB column** — minimal translation, but extraction needed |
| Write granularity | page (row) per save |
| Operational envelope | a Perl app + its DB; direct DB access needs credentials |
| Access grant | per-page permissions in DB; app auth |
| Content opacity | transparent if you can read the DB |
| Provenance | author/timestamp on version rows |

## 4. INTENT mapping

### Reinforcements

- **Backend-neutral page model**: the body is **Markdown** — once extracted from the DB
  column it maps directly; the adapter's work is **schema→page-model**, not format
  translation.
- **History portability** (T13): DB **version rows** are a third history-source shape beside
  git commits and RCS files — importable to the journal as discrete revisions with
  author/timestamp.
- **Graceful degradation**: even with only DB read (no API), MojoMojo is a usable
  read/projection/backup shard; with DB write it could be write-through, but carefully
  (app invariants).

### Divergences (boundaries / notes)

- **No file store, no API** ⇒ the **direct-DB-read** binding is a first-class attach mode the
  contract must name (alongside file-store, in-engine host, external-API, CRDT, P2P) — or a
  sub-mode of "external store" where the medium is **a relational schema** (T14). Reading a
  third-party app's DB is **coupling to its schema** (versioned, may drift across MojoMojo
  versions) — a stated risk (UC-43 backend-swap analogue at the schema level).
- **Writing by direct DB** risks violating app invariants (lineage, version counters,
  search index) — default to **read/projection/overlay**; write-through only with the app's
  cooperation.

### What to keep

1. **Direct-DB-read as a named binding** for DB-backed engines with no file/API (UC-81),
   mapping a **relational schema → wiki page model + journal**.
2. **DB version rows as a history source** for the journal (T13), beside git and RCS.
3. **Schema-coupling caution** — treat the schema as a versioned interface that can drift
   (relates UC-43).

## 5. UC seed

| # | Seed | Disposition |
|---|------|-------------|
| UC-81 | Attach a **DB-backed wiki with no file store / no API** (MojoMojo) by reading its **relational store directly** (page + version tables), mapping schema → page model and **importing DB-resident history** to the journal | **new** |
| — | DB attach vs file attach | enrich **UC-02** / **UC-40** |
| — | DB version-table history import | enrich **UC-36** |
| — | relational page rows / lineage as structure | enrich **UC-34** |

## 6. Architecture notes for SHARD-WP-0002

- **T14 (binding):** add **direct relational read** as a binding (or external-store sub-mode
  whose medium is a SQL schema) for DB-backed engines lacking a file store or API; HTML
  scrape is the lossy fallback. Schema is a **versioned coupling** (drift risk, UC-43).
- **T13 (history portability):** **DB version rows** = a history source alongside git commits
  and RCS revisions — import as discrete journal entries (author/timestamp).
- **T11 (capability):** "has-file-store" / "has-API" are **absent** here; "has-readable-DB"
  is the capability — a sparse profile relying on schema knowledge.

## 7. Open questions

1. Does shard-wiki sanction **direct third-party DB reads** as a binding, or restrict them
   (schema coupling/drift) to a documented best-effort mode? How is schema drift across
   MojoMojo versions handled (UC-43)?
2. Is **write-through by direct DB** ever allowed (risking app invariants), or are DB-backed
   no-API engines read/projection/overlay/backup only?

## 8. Sources

- MojoMojo — github.com/mojomojo/mojomojo; metacpan MojoMojo (Catalyst app, DBIx::Class
  schema: Page / PageVersion / Content / Attachment)
- Catalyst + DBIx::Class framework docs (architecture context)
- prior: `research/260613-twiki-deep-dive/` (file-store classic contrast, UC-40/41)

## 9. Traceability

New UC **UC-81** carries the marker **⊙** in the wikiengines column of
`spec/UseCaseCatalog.md`. Enriched: UC-02, UC-40, UC-36, UC-34. Architecture cross-refs:
SHARD-WP-0002 T14 (direct-DB binding), T13 (DB version-row history), T11.