docs: add unified architecture design spec (2026-09-03)

[zmuhls]

Summary

Add a comprehensive architecture design document proposing a refactor to consolidate duplicated deck model implementations across the codebase into a single shared core consumed by thin hosts (editor, API, export).

Overview

This spec (docs/superpowers/specs/2026-09-03-unified-architecture-design.md) addresses the current architectural debt where the same deck concerns (rendering, styling, mutations, artifacts, theming, markdown, loading) are implemented separately for each surface (canvas edit, canvas view, iframe preview, zip export, chat, planner).

Key Sections

• Problem statement — Inventory of 5–8 parallel implementations of core concerns across 4,500+ lines of duplicated code, with two dedicated audit agents and a parity test to detect drift
• Target architecture — One @slide-maker/core package (document schema, mutation reducer, inverses, validation) consumed by three hosts:
  • @slide-maker/render — Pure Svelte 5 view components with SSR support
  • @slide-maker/artifacts — 13 native factories with dual Vite build (ESM + IIFE)
  • @slide-maker/ai — Provider adapters with generated tool schema
• Data model changes — Document-based storage (decks.document JSON + deck_mutations log) replacing normalized slides/content_blocks tables; single POST /api/decks/:id/mutations endpoint replacing 14 REST endpoints
• Six-phase migration plan — Each phase leaves main deployable; Phases 1–2 deliver atomic edits and correct undo/redo
• Testing strategy — Property tests for apply/inverse identity, golden export tests, vitest coverage of render package (unblocked by removal of $lib alias)
• Risks and mitigations — Svelte SSR from API, document write scale, tool-use fidelity, component wrapping complexity
• Explicitly unchanged — Auth, admin dashboard, sharing, locking, presence, 7 layouts, 14 module types, zone model, export zip structure

Impact

• ~6,000–7,000 lines deleted (duplicated code, dead code, per-surface implementations)
• ~2,000 lines added (core reducer, render package, AI adapters)
• Resolves several open items in TODO.md as by-products (undo/redo hardening, mutation expansion, system prompt generation)
• Unblocks unit test coverage of render and mutation logic (currently blocked by $lib import limitation in vitest)

Companion

#12 pairs this with the host decision: one Cloudflare Worker behind the lab's CUNY-login doorway, model access through the lab's model gateway, per-deck Durable Objects on top of the reducer proposed here. The two can be reviewed independently and land in order.

This is a proposal document for discussion and planning; no code changes are included.

https://claude.ai/code/session_015B7qW78KqCz7p1Po2Q9bXE

[szweibel]

The consolidation direction is useful, but the proposed dual-write transition and retained fenced-parser/token-estimate fallbacks conflict with the current fleet direction. Please revise to one authoritative path and identify the real data-preservation boundary separately, without maintaining old/new writes in parallel. Coordinate mutation-log row/version semantics with #12 before implementation. Current CI proves the unchanged app builds; it does not validate this proposed architecture.

[zmuhls]

Revised in 7519049 to address the review:

• One write path per phase, no dual writes. Phase 1 keeps slides + content_blocks as the only store: the mutations endpoint loads rows into a document, runs the reducer, and writes the rows back in one transaction. There is no document column until Phase 2, and the legacy endpoints carry no traffic by then (every client caller moves to dispatch in Phase 1) rather than being maintained alongside.
• Data-preservation boundary named separately. Phase 2 is now that boundary: API frozen, SQLite file backed up, a verified round trip (rows → document → rows, deep-equal) for every deck before any write, one system:import commit row per deck, tables dropped one release cycle later, rollback = restore + redeploy the Phase 1 build.
• No retained fallbacks. The Phase 0 unified fence parser is the only AI path until Phase 5 replaces it with tool use and deletes it. The chars / 4 estimate is deleted, not kept; a stream without a usage event is logged as usage: null and flagged. Models without function calling are dropped from the model list instead of getting a second parser.
• Commit/version semantics coordinated with docs: Cloudflare Workers transition design (companion to #11) #12. §2.2 now defines a commit as one batch, version incremented exactly once per commit, one deck_commits row keyed by (deck_id, version) carrying mutations[] and inverses[], propose writing nothing. docs: Cloudflare Workers transition design (companion to #11) #12 §2.4 uses the identical definition (its Durable Object table is the same row with the deck id implied).
• Review scope stated. The header now says CI proves the unchanged app builds and validates nothing about the design; the first validation is the Phase 0 golden test, and the first irreversible step (Phase 2) needs its own approval.

---

Generated by Claude Code

[szweibel]

Reviewed the revision at 7519049. The dual-write transition and retained fenced-parser/token-estimate fallbacks are removed, and the data-preservation boundary now names the freeze, round-trip verification, backup and rollback. Those address the corresponding earlier findings.

One migration contradiction remains, noted inline: Phase 1 already records a commit at the current version, while Phase 2 inserts system:import at that same primary key. Please preserve the existing history and define a checkpoint/import operation consistent with the shared version contract. Also make the single-writer/freeze boundary explicit for the retained legacy endpoints; moving the current frontend off them does not prevent an old client from writing.

These are design-review findings. I inspected the revised document and its prior-review changes; the green application CI does not validate the migration. The next step is a document revision by the proposal author, followed by our review of these preservation boundaries.

[szweibel]

[P1] Preserve existing commit history during document import. Phase 1 writes deck_commits and advances decks.version (line 192); the primary key is (deck_id, version) (line 137). For a deck edited during Phase 1, inserting this import row at the current version collides with its latest commit. Replacing that row would destroy history. Specify a separate checkpoint or a versioned import that preserves prior rows and follows the shared version contract.

[szweibel]

Closing as superseded. The reconciliation in #13 absorbed this design (including the version-collision finding) and now lands through #15. The spec stays readable here as design history.