BrewCMS: Open-Source Content Control Plane & Agent Operating System
“When traditional CMS architectures force false choices between fragile headless SaaS subscription bills and bloated legacy monolithic platforms, architect content as a governed, database-agnostic control plane with bounded agent autonomy and zero SaaS lock-in.”
Engineering a database-agnostic, local-first content platform for Next.js 15 with deterministic Content IR, immutable SHA-256 revision trees, native Model Context Protocol (MCP) tooling, and pluggable storage providers (in-process SQLite, PostgreSQL, MySQL).
100% elimination of third-party headless CMS SaaS subscription costs across all reference applications.
What Made the Problem Difficult
As digital platforms scale, content management systems have bifurcated into two undesirable extremes: monolithic legacy platforms with excessive memory and plugin overhead, or API-first SaaS headless platforms that separate content from presentation at the cost of high monthly bills, external network latency, and brittle third-party dependencies. Furthermore, with the rise of autonomous AI coding assistants (Cursor, Claude Desktop, Antigravity), engineering teams need AI agents to inspect, draft, and propose content modifications directly. However, giving AI agents unconstrained write access to databases creates severe risks of hallucinations and brand drift. A new architecture was needed: a local-first, zero-dependency Content Operating System that combines sub-millisecond in-process performance with formal, human-gated AI autonomy.
Core Platform Constraint
Systemic Friction- !Zero native C++ build dependencies: Must run on Node.js 22 native node:sqlite without node-gyp.
- !Sub-millisecond read latency: Public document queries must execute in <0.2ms directly from disk B-trees.
- !Bounded AI agent autonomy: Autonomous operations must be subject to policy gates (ALLOW, DENY, REQUIRE_APPROVAL).
- !Dual-topology flexibility: Must run embedded inside existing Next.js apps or standalone as a headless REST server.
- !Zero SaaS subscription fees: 100% self-hosted on commodity disk without external database infrastructure.
What System Was Designed
BrewCMS implements a strict Hexagonal / Ports & Adapters architecture. At the center is @brew-cms/core, containing pure TypeScript domain entities, business logic, and application services with zero framework dependencies. The content layer (@brew-cms/content) tokenizes Markdown and Frontmatter into a versioned Abstract Syntax Tree / Content IR, computing a deterministic SHA-256 hash for every revision. Storage (@brew-cms/db) is abstracted via repository interfaces implemented on top of Node.js 22 native node:sqlite with Write-Ahead Logging (WAL) and 5000ms busy timeouts for high-concurrency read/write operations. AI agents interact through a native Model Context Protocol server (@brew-cms/mcp) that maps agent tool calls (brew_create_draft, brew_request_publish) to core application services, evaluating every mutation against a declarative policy engine (@brew-cms/policy) before execution. In consumer applications, BrewCMS embeds directly inside the Next.js App Router, enabling Server Components to query documents in-process with zero network overhead while exposing the full Editorial Studio at /admin/cms.
Pivotal Architectural Choices
Key Architectural Decisions
Native node:sqlite with WAL Mode over external database or native addons
Traditional embedded SQLite in Node.js required better-sqlite3, which requires native C++ compilation tools (python, make, gcc) that frequently break in containerized or shared hosting environments.
- PostgreSQL
- better-sqlite3
- Supabase
- Cloudflare D1
Zero npm build scripts, zero native C++ compilation requirements, ~15MB LRU memory cache footprint, and sub-0.2ms read latency directly on NVMe disk. Fits within any standard Node hosting quota without managing a separate database daemon.
Deterministic Content IR with SHA-256 Hashing over raw Markdown storage
Storing raw markdown strings causes parsing ambiguities, unverified HTML injection risks, and makes detecting exact semantic content modifications difficult across revision histories.
- Raw markdown text
- HTML string blobs
- ProseMirror JSON
Decouples storage from rendering, allows safe client and server rendering without dangerouslySetInnerHTML hazards, and computes exact cryptographic content hashes for immutable revision tracking.
Embedded In-Process Engine over Mandatory Remote Headless Server
Deploying a separate CMS server requires dedicated ports, subdomain registration (cms.domain.com), cross-origin CORS handling, and extra webapp slots on hosting platforms like Hostinger.
- Mandatory Headless API
- Microservices container
- Third-party SaaS
Allows Next.js applications like CoffeeDiscussions and this portfolio to run the entire CMS natively inside /admin/cms using 0 extra webapp slots, 0 subdomains, and zero HTTP network round-trips.
Native Model Context Protocol (MCP) with Human Approval Policy Gates
AI agents need structured access to query documents, propose drafts, and update taxonomies without being given unfettered write or publish permissions.
- Custom OpenAI function calling
- Unrestricted REST API tokens
- LangChain agent tools
Provides universal compatibility with Cursor, Claude Desktop, and autonomous agent loops. Low-risk operations (reading, drafting) are allowed automatically, while high-risk operations (publishing, unpublishing) generate approval requests for human editors.
What Was Actually Built
13 Modular TypeScript Packages: Built as a strict pnpm monorepo using TypeScript project references (tsc -b), ensuring clean dependency graphs and zero circular imports.
High-Concurrency WAL Concurrency: SQLite configured with PRAGMA journal_mode = WAL, synchronous = NORMAL, and busy_timeout = 5000, allowing concurrent readers alongside write operations without database locking errors.
Full Next.js 15 App Router Editorial Studio: Responsive studio featuring split-pane live markdown editing, real-time HTML preview, revision rollback history, media library asset browser, taxonomy governance, and agent approval queues.
Zero-Latency Server Component Hydration: In embedded mode, Next.js Server Components call repository methods directly in-process, bypassing the HTTP network stack entirely.
Cryptographic Audit Trail: Every state transition, human editorial decision, and AI agent execution emits an immutable audit event recording actor identity, before/after snapshots, and timestamps.
Deliberate Architectural Compromises
Trade-offs & Mitigations
⚖Database Storage
Zero external server cost, zero connection latency, and instant local-first execution via node:sqlite.
Multiple applications maintain independent SQLite database files on disk rather than a single unified database.
Supported through BrewCMS REST API export/import pipelines and optional standalone headless deployment topology.
⚖AI Agent Autonomy
Guaranteed editorial integrity and zero unauthorized content publishing or hallucinations.
AI agents cannot publish documents to live production without a human editor approving the action run.
Integrated one-click human approval queue in the Studio UI and automated notification hooks.
Verified Outcomes
100% elimination of third-party headless CMS SaaS subscription costs across all reference applications.
Reduced content retrieval latency from ~30ms HTTP round-trips down to sub-0.2ms in-process SQLite B-tree queries.
Consumes only 2 out of 5 allowed webapp slots on Hostinger, leaving 3 slots completely free for future applications.
Full test suite passing: 12 test suites, 45/45 tests passing with 100% clean typecheck (0 errors).
Full production adoption across CoffeeDiscussions (magazine) and VictorKuldeep developer portfolio.
System Schematic & Data Flow
Hexagonal pipeline showing human editorial studio, bounded AI agents via MCP, deterministic Content IR compiler, and in-process SQLite storage.
Text alternative for screen readers: Architecture flow: Human Editor / AI Agent (MCP) to Policy Engine Gate via RBAC & Autonomy Boundaries; Policy Engine Gate to Application Services via Approved Content Operations; Application Services to Content IR Compiler via Markdown Parsing & SHA-256 Hashing; Content IR Compiler to Immutable Revision Tree via Append-Only Historical Snapshots; Immutable Revision Tree to In-Process SQLite (WAL) via <0.2ms B-Tree Storage; In-Process SQLite (WAL) to Next.js Server Components via Zero-Latency Page Hydration
Architectural Conclusion
“The future of web software is not static CMS databases or unmonitored AI agents, but governed content operating systems where human editorial intent and machine autonomy coexist safely with local-first performance and zero SaaS vendor tax.”
- •Local-first SQLite with WAL mode is vastly superior to remote headless APIs for single-server and shared-hosting Next.js architectures.
- •AI agents in production need formal policy boundaries and approval queues rather than direct database write permissions.
- •Deterministic Content IR with cryptographic hashing eliminates content drift and makes revision rollbacks completely predictable.