MDCMS is an open-source headless CMS that treats a PostgreSQL database as the source of truth for structured Markdown and MDX content. This page describes the design principles, deployment topology, technology choices, and monorepo structure that underpin the system.Documentation Index
Fetch the complete documentation index at: https://docs.mdcms.ai/llms.txt
Use this file to discover all available pages before exploring further.
Design Principles
MDCMS follows a small set of architectural invariants that inform every subsystem.| Principle | What it means |
|---|---|
| Database is source of truth | Content lives in PostgreSQL, not the filesystem. The CLI syncs files to and from the database via mdcms push / mdcms pull. |
| Schema-driven UI | Content types are defined in TypeScript with Zod. The schema drives form generation, validation, API behavior, and Studio rendering automatically. |
| Explicit target routing | Every API request carries a project and environment context via X-MDCMS-Project and X-MDCMS-Environment headers. There is no implicit “current” tenant. |
| Code-first configuration | All configuration lives in mdcms.config.ts — a TypeScript file that is type-checked and version-controlled alongside application code. |
| CQRS-lite | Writes flow through command handlers that enforce validation, authorization, and versioning. Reads flow through query handlers that project data for specific consumers. The same database backs both paths. |
Deployment Topology
A production MDCMS deployment consists of the server process, a PostgreSQL database, a Redis instance for session caching and rate limiting, and S3-compatible object storage for media assets. Clients interact through the TypeScript SDK or the embedded Studio component.In local development,
docker-compose.dev.yml starts PostgreSQL, Redis, and
MinIO automatically. The server, Studio, and studio-example app run via bun run dev.Technology Stack
Every technology choice has a specific justification. The table below documents the role and rationale for each dependency.| Technology | Version | Role | Why |
|---|---|---|---|
| Bun | 1.3+ | Runtime | Fast startup, native TypeScript execution, built-in test runner. |
| TypeScript | 5.9 | Language | End-to-end type safety across server, CLI, SDK, and Studio. |
| Nx | 22.5 | Monorepo orchestration | Task caching, dependency graph, parallel builds. |
| Elysia | 1.4 | HTTP framework | End-to-end type safety with Bun-native performance. |
| PostgreSQL | 15+ | Primary database | JSONB for frontmatter, full-text search, append-only versioning via documentVersions. |
| Drizzle ORM | 0.45 | Database access | Schema-as-code migrations, type-safe query builder. |
| better-auth | 1.5 | Authentication | Session management, OIDC/SAML SSO, CSRF protection. |
| Redis | 7 | Cache / rate limiting | Session cache, login backoff tracking. |
| S3 (MinIO dev) | — | Media storage | Stores uploaded images and files. MinIO provides local S3-compatible development. |
| React | 19 | Studio UI | Component model for the embeddable CMS editor. |
| Next.js | 15.2 | Studio host | Server-rendered Studio example app and review environment. |
| TailwindCSS | 4.2 | Styling | Utility-first CSS for consistent Studio design. |
| TipTap | 3.7 | Rich text editor | Extensible, ProseMirror-based MDX editing with custom node support. |
| Radix UI | — | Accessible primitives | Headless UI components for dialogs, menus, popovers, and form controls. |
| Zod | 4.3 | Validation | Schema definition with Standard Schema interface for cross-boundary validation. |
Monorepo Structure
MDCMS is an Nx-managed Bun workspace. The repository is organized intoapps/ (deployable applications) and packages/ (shared libraries).
Package Dependency Graph
The packages and apps form a directed dependency graph. Core contracts flow fromshared outward; higher-level packages never depend on apps.