decocms · vibegui · Dec 3, 2025
diff --git a/apps/cms/PLAN.md b/apps/cms/PLAN.md
@@ -0,0 +1,124 @@
+# DecoCMS - Content Management System
+
+> Port of admin-cx (admin.deco.cx) to the new React/Vite stack
+
+## Overview
+
+This app provides the **Content Management System** for deco sites, complementing the **Context Management System** (mesh/MCP). It enables visual editing of pages, sections, loaders, actions, and other blocks that power deco-based websites.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      apps/cms                               │
+├─────────────────────────────────────────────────────────────┤
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
+│  │   Shell     │  │   Spaces    │  │    Editor           │  │
+│  │  (Layout)   │  │  (Views)    │  │  (Form + Preview)   │  │
+│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
+│                         │                    │              │
+│                         ▼                    ▼              │
+│  ┌─────────────────────────────────────────────────────┐    │
+│  │              packages/cms-sdk                       │    │
+│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌───────────┐  │    │
+│  │  │ Daemon  │ │ Blocks  │ │ Schema  │ │  Preview  │  │    │
+│  │  │ Client  │ │  CRUD   │ │ Fetcher │ │   URLs    │  │    │
+│  │  └─────────┘ └─────────┘ └─────────┘ └───────────┘  │    │
+│  └─────────────────────────────────────────────────────┘    │
+└─────────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+              ┌─────────────────────────┐
+              │    deco site runtime    │
+              │  /.deco/blocks/*.json   │
+              │      /live/_meta        │
+              │    /live/previews/*     │
+              └─────────────────────────┘
+```
+
+## Key Dependencies
+
+- **@deco/ui** - Shared UI components (buttons, inputs, tables, etc.)
+- **@deco/sdk** - Auth, API client, React Query hooks
+- **packages/cms-sdk** - NEW: CMS-specific SDK (daemon, blocks, schema)
+- **react-router** - Client-side routing
+- **react-hook-form** - Form state management
+- **ajv** - JSON Schema validation
+
+## Features to Port from admin-cx
+
+### P0 - MVP (Must Have)
+- [ ] Pages list and editor
+- [ ] Sections list and editor
+- [ ] JSON Schema form with core widgets
+- [ ] Preview iframe with viewport controls
+- [ ] Real-time daemon sync
+- [ ] Block CRUD operations
+
+### P1 - Core Features
+- [ ] Loaders list and editor
+- [ ] Actions list and editor
+- [ ] Apps management (install/uninstall)
+- [ ] Assets upload and management
+- [ ] Releases and git operations
+- [ ] Analytics integration (Plausible)
+- [ ] Logs viewer (HyperDX)
+- [ ] SEO settings
+- [ ] Redirects management
+
+### P2 - Advanced Features
+- [ ] Themes editor
+- [ ] Segments and experiments
+- [ ] Blog management
+- [ ] Records (Drizzle Studio)
+
+## Implementation Phases
+
+### Phase 1: Foundation (Week 1-2)
+1. Create packages/cms-sdk with daemon client
+2. Setup apps/cms with basic routing
+3. Implement site connection flow
+
+### Phase 2: Core Editor (Week 2-3)
+1. Port JSON Schema form system
+2. Implement preview iframe
+3. Create block editor component
+
+### Phase 3: Spaces (Week 4-6)
+1. Pages space
+2. Sections space
+3. Loaders/Actions spaces
+4. Apps space
+5. Assets space
+
+### Phase 4: Operations (Week 6-7)
+1. Releases and git operations
+2. Settings (domains, team)
+3. Navigation between mesh and cms
+
+### Phase 5: Analytics & Observability (Week 8)
+1. Analytics integration
+2. Logs viewer
+3. Error monitoring
+
+## File Structure
+
+See individual `PLAN.md` files in each subdirectory for detailed implementation plans.
+
+## Running Locally
+
+```bash
+# From repo root
+npm run dev:cms
+
+# Or directly
+cd apps/cms && npm run dev
+```
+
+## Environment Variables
+
+```env
+VITE_API_URL=http://localhost:3000
+VITE_SITE_DOMAIN=.deco.site
+```
+
diff --git a/apps/cms/index.html b/apps/cms/index.html
@@ -0,0 +1,15 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Deco CMS</title>
+    <meta name="description" content="Content Management System for deco sites" />
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
+
diff --git a/apps/cms/package.json b/apps/cms/package.json
@@ -0,0 +1,40 @@
+{
+  "name": "@deco/cms",
+  "version": "0.0.1",
+  "private": true,
+  "description": "Deco Content Management System",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "preview": "vite preview",
+    "lint": "biome lint src/",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@deco/cms-sdk": "workspace:*",
+    "@deco/sdk": "workspace:*",
+    "@deco/ui": "workspace:*",
+    "@dnd-kit/core": "^6.1.0",
+    "@dnd-kit/sortable": "^8.0.0",
+    "@hookform/resolvers": "^3.3.0",
+    "@tanstack/react-query": "^5.0.0",
+    "ajv": "^8.12.0",
+    "ajv-formats": "^2.1.1",
+    "react": "^18.3.0",
+    "react-dom": "^18.3.0",
+    "react-hook-form": "^7.50.0",
+    "react-router": "^7.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.0",
+    "@types/react-dom": "^18.3.0",
+    "@vitejs/plugin-react": "^4.2.0",
+    "autoprefixer": "^10.4.0",
+    "postcss": "^8.4.0",
+    "tailwindcss": "^3.4.0",
+    "typescript": "^5.4.0",
+    "vite": "^5.2.0"
+  }
+}
+
diff --git a/apps/cms/src/PLAN.md b/apps/cms/src/PLAN.md
@@ -0,0 +1,79 @@
+# apps/cms/src - Source Structure
+
+## Directory Layout
+
+```
+src/
+├── main.tsx              # App entry point
+├── routes/               # Route components
+├── components/           # React components
+│   ├── shell/           # Layout components
+│   ├── spaces/          # Space views (pages, sections, etc.)
+│   ├── editor/          # Form and preview
+│   └── common/          # Shared components
+├── hooks/               # React hooks
+├── providers/           # Context providers
+├── stores/              # Zustand stores (if needed)
+└── utils/               # Utility functions
+```
+
+## Entry Point (main.tsx)
+
+```tsx
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { RouterProvider } from "react-router";
+import { DecoQueryClientProvider } from "@deco/sdk";
+import { router } from "./routes";
+
+import "@deco/ui/styles/global.css";
+import "./styles.css";
+
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <DecoQueryClientProvider>
+      <RouterProvider router={router} />
+    </DecoQueryClientProvider>
+  </StrictMode>
+);
+```
+
+## Routing Structure
+
+The CMS will be accessible at `/:org/:project/cms/*` or as a standalone app.
+
+Routes:
+- `/:org/:site` - Site dashboard
+- `/:org/:site/pages` - Pages list
+- `/:org/:site/pages/:pageId` - Page editor
+- `/:org/:site/sections` - Sections list
+- `/:org/:site/sections/:sectionId` - Section editor
+- `/:org/:site/loaders` - Loaders list
+- `/:org/:site/actions` - Actions list
+- `/:org/:site/apps` - Apps management
+- `/:org/:site/assets` - Asset library
+- `/:org/:site/releases` - Release management
+- `/:org/:site/analytics` - Analytics dashboard
+- `/:org/:site/logs` - Logs viewer
+- `/:org/:site/settings` - Site settings
+
+## Key Patterns
+
+### 1. Site Context Provider
+All routes under `/:org/:site` will be wrapped with `SiteProvider` that:
+- Establishes daemon connection
+- Fetches site metadata (`/live/_meta`)
+- Provides block access via React Query
+
+### 2. Space Pattern
+Each "space" (pages, sections, etc.) follows the same pattern:
+- List view with table/grid
+- Detail/edit view with form + preview
+- Uses shared `BlockEditor` component
+
+### 3. Real-time Updates
+The daemon connection provides real-time file system updates:
+- File changes trigger query invalidation
+- Optimistic updates for better UX
+- Conflict resolution for concurrent edits
+
diff --git a/apps/cms/src/components/PLAN.md b/apps/cms/src/components/PLAN.md
@@ -0,0 +1,79 @@
+# Components Structure
+
+## Overview
+
+Components are organized by function:
+
+```
+components/
+├── shell/          # App shell and navigation
+├── spaces/         # Main content areas (pages, sections, etc.)
+├── editor/         # Block editing (form + preview)
+└── common/         # Shared/reusable components
+```
+
+## Component Guidelines
+
+### 1. Use @deco/ui Components
+Always prefer `@deco/ui` components over creating new ones:
+- `Button`, `Input`, `Select` from `@deco/ui/components`
+- `ResourceTable` for data lists
+- `Dialog`, `Sheet` for modals
+- `Tabs`, `Accordion` for organization
+
+### 2. Colocation
+Keep related files together:
+```
+components/spaces/pages/
+├── index.tsx           # Main export
+├── PagesList.tsx       # List component
+├── PageEditor.tsx      # Editor component
+├── use-pages.ts        # Page-specific hooks
+└── types.ts            # Type definitions
+```
+
+### 3. Props Pattern
+Use explicit prop interfaces:
+```tsx
+interface PageEditorProps {
+  pageId: string;
+  onSave?: (page: Page) => void;
+  onCancel?: () => void;
+}
+
+export function PageEditor({ pageId, onSave, onCancel }: PageEditorProps) {
+  // ...
+}
+```
+
+## Key Components to Implement
+
+### Shell Components
+- `CMSLayout` - Main app shell with sidebar + topbar
+- `Sidebar` - Navigation between spaces
+- `Topbar` - Breadcrumbs, site selector, user menu
+- `SpaceContainer` - Container for space content
+
+### Space Components
+- `PagesSpace` - Pages list and management
+- `SectionsSpace` - Sections list and management
+- `LoadersSpace` - Loaders list
+- `ActionsSpace` - Actions list
+- `AppsSpace` - App installation
+- `AssetsSpace` - Asset library
+- `ReleasesSpace` - Git releases
+- `SettingsSpace` - Site configuration
+
+### Editor Components
+- `BlockEditor` - Combined form + preview layout
+- `JSONSchemaForm` - Form rendered from JSON Schema
+- `Preview` - iframe preview with controls
+- `Addressbar` - URL input with viewport switcher
+
+### Common Components
+- `BlockCard` - Card displaying block info
+- `BlockSelector` - Modal for selecting blocks
+- `AssetPicker` - Modal for selecting/uploading assets
+- `ColorPicker` - Color input with picker
+- `CodeEditor` - Monaco-based code editor
+