Root architecture audit

[stevenle]

Description

Identify improvements to the overall Root architecture.

[stevenle]

Claude:

If I were rewriting root / root-cms from scratch

Context

This is an architectural critique, not an implementation plan — the user asked
what I'd change if starting over. Findings are grounded in the current
codebase (packages/root, packages/root-cms) and the pain points surfaced by
recent commits and outstanding TODOs.

What I'd keep

These are architectural choices that have aged well and I'd port forward
unchanged:

• Vite as the build/dev substrate. SSR + client islands work well, HMR
  story is solid, plugin ecosystem is mature.
• File-based routing with i18n baked into URL structure (routes/[locale]/...
  via RouteTrie in packages/root/src/render/route-trie.ts). The
  trie-based matcher is fast and the URL-first i18n model is the right
  default.
• Pod composition for plugins (packages/root/src/core/plugin.ts). The
  idea that plugins can mount a self-contained mini-site (routes, elements,
  translations, collections) is a strong primitive — keep it, simplify the
  contract.
• root.config.ts loaded via bundle-require with dependency tracking for
  hot reload — this just works.
• pnpm + turbo monorepo layout with separate packages for core / cms /
  scaffolder.
• TSX-first authoring model — the JSX-everywhere DX is good.

What I'd change

1. Don't ship a custom JSX runtime

Today packages/root/src/jsx/jsx-runtime.ts + jsx-render.ts implement
JSX→HTML serialization by hand to avoid pulling Preact into SSR. That choice
keeps producing paper cuts — attribute serialization, boolean attrs,
void/raw-content/block-element handling, event handler stringification have
all been patched repeatedly (commits 1ad324c, ead5f31, 19d81d5; the
file is ~500 lines of hand-rolled HTML rules).

Rewrite choice: use preact-render-to-string (or a streaming renderer)
directly on the server. The marginal cost of pulling Preact server-side is
small compared to the maintenance burden of a bespoke serializer, and it
unlocks streaming SSR + Suspense for free.

2. Make the runtime web-standard, not Express

packages/root/src/middleware/* and the dev/build/start CLIs lean on Express
(req/res). That couples the framework to Node and makes Cloudflare
Workers / Deno / Bun / Vercel Edge deployment a per-adapter problem
(packages/root/src/functions/ only solves it for Cloud Functions).

Rewrite choice: core handler signature is Request → Response (Web
Fetch). Provide thin adapters for Node, Cloud Functions, Workers, Bun.
Middleware becomes a composable chain over Web Request/Response. This is
a one-time cost that buys runtime portability forever.

3. Consolidate the post-build HTML pipeline

There's an explicit TODO in two places (packages/root/src/render/render.tsx:408
and packages/root/src/cli/build.ts:502) — "consolidate post-build html
transformation logic." Minification, prettify, asset injection, custom
element script injection, and Vite transformations run in multiple paths
with no shared abstraction.

Rewrite choice: a single HtmlTransformer pipeline (ordered, named
stages) used by both SSR and SSG. Plugins register transforms by name with
declared ordering, similar to PostCSS/unified.

4. Plugin contract is just two things

Today the plugin surface is large: lifecycle hooks (preBuild, postBuild,
preRender), Vite plugin slot, server middleware, configureServer, pod
registration, custom 404. It's powerful but the contract is sprawling.

Rewrite choice: plugins are (a) a Vite plugin and (b) an optional
RootIntegration with a tiny lifecycle (setup, routes, render,
build). Everything else (middleware, redirects, headers, security) goes
through the integration's routes contribution rather than separate
slots. Easier to reason about, easier to compose.

5. CMS: abstract the data layer

Today root-cms is welded to Firestore. The fingerprints are everywhere:

• Rich text Table field can't ship because "firestore doesn't support…"
  (root-cms/ui/components/RichTextEditor/EditorJSEditor.tsx:132)
• Locale fallback trees aren't fully implemented (client.ts:2483)
• "TODO: avoid the extra db write here" in DocEditor.tsx:211, 232
  (Firestore write cost is the unstated reason)
• Schemas use glob self-references to dodge import cycles
• Draft/Published live as parallel collections
  (Drafts/{slug} + Published/{slug}) — works, but reinvents what a
  proper versioning model gives you
• Translations hash-keyed in a side store
  (TranslationsManager/{mode}/Translations/{hash}:{locale}) — clever, but
  doesn't survive moving off Firestore

Rewrite choice: content store is behind a small ContentStore interface
(getDoc, listDocs, saveDraft, publish, subscribe). Ship adapters
for Firestore (parity), Postgres (Drizzle/libsql), and SQLite (for local
dev). Schema design stops being constrained by document-store quirks.
Realtime becomes optional (only Firestore needs it as a primitive; others
can poll or use logical replication). Draft/published becomes a typed
version graph rather than two literal collections.

6. Schemas are TypeScript-first with Standard Schema

Current schema files are loaded via glob and self-reference to break cycles.
That's clever but fragile.

Rewrite choice: define collections as plain TS modules using Standard
Schema (Zod / Valibot / ArkType — let the user pick). Codegen consumes
those for typed CMS clients, typed admin forms, and runtime validation.
One source of truth, no glob magic, no parallel .d.ts generation.

7. One rich text editor

packages/root-cms/ui/components/RichTextEditor/ carries both EditorJS and
Lexical with conditional loading and unresolved TODOs on both stacks
(EditorJS type issues at EditorJSEditor.tsx:64; Lexical toolbar issues at
ToolbarPlugin.tsx:324, 372).

Rewrite choice: pick Lexical, delete EditorJS. Model the editor's
document as a portable JSON shape that's storage-agnostic (i.e. doesn't
encode Firestore field limitations).

8. Typed RPC instead of postMessage + window events

Admin UI ↔ admin UI communication today leans on window.postMessage and
ad-hoc CustomEvents (SearchPanel.tsx → OPEN_RICHTEXT_BLOCK_EVENT).
Admin UI ↔ server is custom fetch.

Rewrite choice: tRPC (or hono/rpc) for the admin API surface — full
type safety from server to client, no parallel type definitions. Replace
window events with a typed event bus where event names map to payload
types.

9. Pluggable auth and assets

Firebase Auth and GCS are the only first-class options today.

Rewrite choice: AuthProvider and AssetStore interfaces. Ship
adapters for Firebase Auth, Auth.js/Lucia, Clerk; for GCS, S3, R2, local
disk. Built-in image optimization via sharp (or a hosted provider) sits
behind the asset store.

10. Type-safe routes

Today route params are strings discovered at runtime. With TS template
literal types we can extract param types directly from filenames so
useParams() in routes/products/[id].tsx returns {id: string} without
codegen.

11. Test coverage as a first-class concern

packages/root ships 22 test files for 69 source files (~32%); rendering,
routing, and middleware are sparsely covered. The pain-point report flagged
this as a refactor risk.

Rewrite choice: Vitest + Playwright from day one, with the renderer
and router covered by both unit and snapshot tests. CI gate on coverage
delta.

12. Build orchestration: one tool

root-cms currently runs three concurrent build processes (tsup for core,
two raw esbuild invocations for UI/signin) because "tsup doesn't currently
support aliases" (root-cms/package.json:56).

Rewrite choice: single Vite library build per package using current
alias support, or Rolldown when it stabilizes. One pipeline, one cache.

Verification

Since this is a conceptual answer (no code changes), "verification" is
discussion-based:

• Walk through each recommendation against a real failing case in the
  current codebase to confirm the trade-off pays off.
• For any item the user wants to actually pursue, follow up with a
  scoped implementation plan for that single change.

[stevenle]

Codex:

My clean-sheet thesis: I’d make Root a compiler plus small runtime, and Root CMS a server-authoritative content application. The current architecture is pragmatic and productive, but a lot of behavior is spread across Vite plugins, Express handlers, Firestore client writes, generated JSON, and browser globals.

Root Framework

I’d split @blinkk/root into clearer layers:

• compiler: discovers routes, pods, elements, bundles, schemas, i18n, and outputs one typed manifest.
• runtime: renders requests from that manifest.
• dev-server: Vite/HMR integration only.
• adapters: Express, Firebase Functions, maybe future edge adapters.

Right now, build/dev/render concerns are fairly interwoven across files like build.ts, vite.ts, and router.ts. I’d want dev and prod to consume the same manifest shape, so fewer “works in Vite SSR, then serialized to dist JSON for prod” paths.

I’d also make the plugin API less open-ended. Instead of plugins being broad objects with hooks, Vite plugins, pods, SSR inputs, and middleware all in one surface, I’d define typed contribution points: routes, assets, middleware, buildArtifacts, cmsSchemas, serverActions, etc. More ceremony, but much better long-term compatibility.

Root CMS

The biggest change: I would stop letting the browser be a first-class Firestore writer for core content workflows.

Today, the CMS UI writes directly to Firestore in several places, while server-side code also implements overlapping logic in client.ts and api.ts. In a rewrite, the browser would use a generated typed API client. The server would own publishing, scheduling, releases, permissions, validation, audit logs, versioning, and AI actions. Firestore rules would become a defense layer, not the main business boundary.

I’d also introduce a real storage abstraction:

• cms-domain: docs, releases, tasks, translations, assets, versions.
• cms-server: commands and queries.
• cms-store-firestore: Firestore implementation.
• cms-ui: frontend only.
• cms-client: generated browser/server API client.

Firestore could still be the default store, but paths like Projects/{id}/Collections/{collection}/Drafts/{slug} would live behind repositories, not throughout UI and core utilities.

Schemas And Content Model

I’d keep TS-authored schemas because that’s a nice Root-ish strength, but compile them into a versioned schema IR. That IR would drive:

• runtime validation,
• generated TypeScript types,
• CMS field rendering,
• migrations,
• search indexing,
• API contracts.

The current schema model in schema.ts is approachable, but I’d make field IDs genuinely required, make field plugins first-class, and record schema versions so content migrations are not an afterthought.

I’d also turn draft, published, scheduled, version, release, archived, and locked behavior into an explicit state machine or command model. Publishing should be “execute PublishDocs command” with idempotency, validation, permissions, audit logging, and version snapshots in one place.

Frontend

For the CMS UI, I’d choose one UI runtime cleanly. The current Preact plus React-compat plus pinned Mantine setup works, but it creates ecosystem drag. I’d either commit fully to React for the admin app, or commit fully to Preact with a lighter design system built for it.

I’d replace window.__ROOT_CTX and scattered Firebase helpers with an app shell, typed config hydration, feature modules, and a single data-fetching layer. The UI should not know Firestore paths for publishing, releases, tasks, translations, or AI tool actions.

What I’d Keep

I would absolutely keep the spirit: file routes, TSX rendering, web components, Vite, simple project config, and “CMS lives with the site.” That’s the interesting part. I’d mainly change the boundaries so Root feels more like a compiler/runtime platform, and Root CMS feels more like a secure content system than a clever Firestore-backed admin UI.