modern-cms 1.0.0

package/README.md

@@ -0,0 +1,41 @@
+# modern-cms
+
+A self-hosted, drag-and-drop website CMS — Next.js (App Router) front end, Express + Prisma API, PostgreSQL or MySQL, and pluggable file storage (AWS S3, Azure Blob Storage, or Cloudinary).
+
+## Quick start
+
+```
+npx modern-cms
+```
+
+You'll be asked for:
+
+- Where to create the project
+- Database engine (PostgreSQL or MySQL) — host, database name, username, password
+- File storage provider (AWS S3 / any S3-compatible service, Azure Blob Storage, or Cloudinary) and its credentials
+- Site URLs and an admin login
+
+The installer scaffolds the full project into your target directory and writes working `.env` files for the API and web app. It does **not** run `npm install` or touch your database for you — it prints the exact next commands to run, so nothing happens on your machine without you seeing it first.
+
+## What you get
+
+- A visual, drag-and-drop page builder (containers, grids, 30+ content blocks, responsive breakpoints, animations, dark mode)
+- Collections (blog/news/etc.), full-text search, SEO (sitemap, JSON-LD, redirects), page revisions and templates
+- Role-based auth (Admin / Editor / Author), audit log, form submissions
+- Media library backed by whichever storage provider you chose
+
+## After setup
+
+```
+cd <your-project-dir>
+npm install
+npm run db:migrate   # PostgreSQL
+# or, for MySQL (the bundled migration history is Postgres-specific SQL):
+npx prisma db push --schema apps/api/prisma/schema.prisma
+npm run db:seed
+npm run dev
+```
+
+## License
+
+MIT

package/bin/lib.js

@@ -0,0 +1,97 @@
+import crypto from "node:crypto";
+
+export function randomSecret() {
+  return crypto.randomBytes(48).toString("hex");
+}
+
+export function buildDatabaseUrl(db) {
+  const protocol = db.engine === "mysql" ? "mysql" : "postgresql";
+  return `${protocol}://${encodeURIComponent(db.user)}:${encodeURIComponent(db.password)}@${db.host}:${db.port}/${db.name}`;
+}
+
+export function rewriteSchemaProvider(schemaContent, engine) {
+  return schemaContent.replace(/provider\s*=\s*"postgresql"/, `provider = "${engine}"`);
+}
+
+/** MySQL can't run the bundled migration history — it's raw SQL generated for
+ * PostgreSQL. There's no existing data on a fresh install, so dropping the history and
+ * using `prisma db push` instead of `prisma migrate dev` is the correct, simplest path. */
+export function usesDbPush(engine) {
+  return engine === "mysql";
+}
+
+export function buildStorageEnvLines(provider, values) {
+  if (provider === "s3") {
+    return [
+      `S3_ENDPOINT=${values.endpoint}`,
+      `S3_REGION=${values.region}`,
+      `S3_ACCESS_KEY_ID=${values.accessKeyId}`,
+      `S3_SECRET_ACCESS_KEY=${values.secretAccessKey}`,
+      `S3_BUCKET=${values.bucket}`,
+      `S3_PUBLIC_URL=${values.publicUrl}`,
+      `S3_FORCE_PATH_STYLE=${String(values.forcePathStyle)}`,
+    ];
+  }
+  if (provider === "azure") {
+    return [
+      `AZURE_STORAGE_CONNECTION_STRING=${values.connectionString}`,
+      `AZURE_STORAGE_CONTAINER=${values.container}`,
+      ...(values.publicUrl ? [`AZURE_STORAGE_PUBLIC_URL=${values.publicUrl}`] : []),
+    ];
+  }
+  return [
+    `CLOUDINARY_CLOUD_NAME=${values.cloudName}`,
+    `CLOUDINARY_API_KEY=${values.apiKey}`,
+    `CLOUDINARY_API_SECRET=${values.apiSecret}`,
+    `CLOUDINARY_FOLDER=${values.folder}`,
+  ];
+}
+
+export function buildApiEnv({ databaseUrl, jwtSecret, adminEmail, adminPassword, storageProvider, storageEnvLines, siteUrl, revalidateSecret }) {
+  return [
+    `DATABASE_URL=${databaseUrl}`,
+    "",
+    "# --- Auth ---",
+    `JWT_SECRET=${jwtSecret}`,
+    "JWT_EXPIRES_IN=7d",
+    "COOKIE_NAME=pgcms_token",
+    "",
+    "# --- Seed admin user ---",
+    `SEED_ADMIN_EMAIL=${adminEmail}`,
+    `SEED_ADMIN_PASSWORD=${adminPassword}`,
+    "",
+    `# --- File storage (${storageProvider}) ---`,
+    `STORAGE_PROVIDER=${storageProvider}`,
+    ...storageEnvLines,
+    "",
+    "# --- API ---",
+    "API_PORT=4000",
+    `WEB_ORIGIN=${siteUrl}`,
+    "",
+    "# --- Cache revalidation ---",
+    `REVALIDATE_URL=${siteUrl}`,
+    `REVALIDATE_SECRET=${revalidateSecret}`,
+    "",
+    "# --- Form integrations (optional) ---",
+    "FORMS_WEBHOOK_URL=",
+    "",
+  ].join("\n");
+}
+
+export function buildWebEnv({ apiUrl, siteUrl }) {
+  return [`API_URL=${apiUrl}`, `SITE_URL=${siteUrl}`, ""].join("\n");
+}
+
+export function buildRootEnv({ db, databaseUrl, storageProvider, storageEnvLines }) {
+  const s3Line = (prefix) => storageEnvLines.find((l) => l.startsWith(prefix));
+  return [
+    `POSTGRES_USER=${db.user}`,
+    `POSTGRES_PASSWORD=${db.password}`,
+    `POSTGRES_DB=${db.name}`,
+    `DATABASE_URL=${databaseUrl}`,
+    ...(storageProvider === "s3"
+      ? [s3Line("S3_ACCESS_KEY_ID="), s3Line("S3_SECRET_ACCESS_KEY="), s3Line("S3_BUCKET=")].filter(Boolean)
+      : []),
+    "",
+  ].join("\n");
+}

package/bin/modern-cms.js

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { fileURLToPath } from "node:url";
+import prompts from "prompts";
+import {
+  randomSecret,
+  buildDatabaseUrl,
+  rewriteSchemaProvider,
+  usesDbPush,
+  buildStorageEnvLines,
+  buildApiEnv,
+  buildWebEnv,
+  buildRootEnv,
+} from "./lib.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const TEMPLATE_DIR = path.join(__dirname, "..", "template");
+
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) copyDir(srcPath, destPath);
+    else fs.copyFileSync(srcPath, destPath);
+  }
+}
+
+function onCancel() {
+  console.log("\nSetup cancelled — nothing was written.");
+  process.exit(1);
+}
+
+async function main() {
+  console.log("\nmodern-cms — self-hosted drag-and-drop website CMS\n");
+
+  const { targetDir } = await prompts(
+    { type: "text", name: "targetDir", message: "Where should the project be created?", initial: "./modern-cms-app" },
+    { onCancel }
+  );
+  const dest = path.resolve(process.cwd(), targetDir);
+  if (fs.existsSync(dest) && fs.readdirSync(dest).length > 0) {
+    console.error(`\n"${dest}" already exists and isn't empty. Choose an empty or new directory.`);
+    process.exit(1);
+  }
+
+  console.log(`\nCopying project files into ${dest} ...`);
+  copyDir(TEMPLATE_DIR, dest);
+
+  // --- Database ---
+  const db = await prompts(
+    [
+      {
+        type: "select",
+        name: "engine",
+        message: "Database",
+        choices: [
+          { title: "PostgreSQL", value: "postgresql" },
+          { title: "MySQL", value: "mysql" },
+        ],
+      },
+      { type: "text", name: "host", message: "Database host", initial: "localhost" },
+      {
+        type: "text",
+        name: "port",
+        message: "Database port",
+        initial: (_, values) => (values.engine === "mysql" ? "3306" : "5432"),
+      },
+      { type: "text", name: "name", message: "Database name", initial: "modern_cms" },
+      { type: "text", name: "user", message: "Database username", initial: (_, values) => (values.engine === "mysql" ? "root" : "postgres") },
+      { type: "password", name: "password", message: "Database password" },
+    ],
+    { onCancel }
+  );
+
+  const databaseUrl = buildDatabaseUrl(db);
+
+  const schemaPath = path.join(dest, "apps/api/prisma/schema.prisma");
+  fs.writeFileSync(schemaPath, rewriteSchemaProvider(fs.readFileSync(schemaPath, "utf8"), db.engine));
+
+  if (usesDbPush(db.engine)) {
+    const migrationsDir = path.join(dest, "apps/api/prisma/migrations");
+    if (fs.existsSync(migrationsDir)) fs.rmSync(migrationsDir, { recursive: true, force: true });
+  }
+
+  // --- Storage ---
+  const { provider } = await prompts(
+    {
+      type: "select",
+      name: "provider",
+      message: "File storage",
+      choices: [
+        { title: "AWS S3 (or any S3-compatible: MinIO, R2, Spaces...)", value: "s3" },
+        { title: "Azure Blob Storage", value: "azure" },
+        { title: "Cloudinary", value: "cloudinary" },
+      ],
+    },
+    { onCancel }
+  );
+
+  let storageValues;
+  if (provider === "s3") {
+    storageValues = await prompts(
+      [
+        { type: "text", name: "endpoint", message: "S3 endpoint", initial: "https://s3.amazonaws.com" },
+        { type: "text", name: "region", message: "S3 region", initial: "us-east-1" },
+        { type: "text", name: "accessKeyId", message: "S3 access key ID" },
+        { type: "password", name: "secretAccessKey", message: "S3 secret access key" },
+        { type: "text", name: "bucket", message: "S3 bucket name" },
+        { type: "text", name: "publicUrl", message: "Public base URL for uploaded files (e.g. https://<bucket>.s3.amazonaws.com)" },
+        {
+          type: "toggle",
+          name: "forcePathStyle",
+          message: "Force path-style URLs? (needed for MinIO/most non-AWS S3-compatible services)",
+          initial: false,
+          active: "yes",
+          inactive: "no",
+        },
+      ],
+      { onCancel }
+    );
+  } else if (provider === "azure") {
+    storageValues = await prompts(
+      [
+        { type: "password", name: "connectionString", message: "Azure Storage connection string" },
+        { type: "text", name: "container", message: "Blob container name", initial: "media" },
+        { type: "text", name: "publicUrl", message: "Public base URL (leave blank to use the storage account's own blob URL)", initial: "" },
+      ],
+      { onCancel }
+    );
+  } else {
+    storageValues = await prompts(
+      [
+        { type: "text", name: "cloudName", message: "Cloudinary cloud name" },
+        { type: "text", name: "apiKey", message: "Cloudinary API key" },
+        { type: "password", name: "apiSecret", message: "Cloudinary API secret" },
+        { type: "text", name: "folder", message: "Upload folder", initial: "pgcms" },
+      ],
+      { onCancel }
+    );
+  }
+  const storageEnvLines = buildStorageEnvLines(provider, storageValues);
+
+  // --- Site / admin ---
+  const site = await prompts(
+    [
+      { type: "text", name: "siteUrl", message: "Public site URL", initial: "http://localhost:3000" },
+      { type: "text", name: "apiUrl", message: "API URL", initial: "http://localhost:4000" },
+      { type: "text", name: "adminEmail", message: "Admin login email", initial: "admin@example.com" },
+      { type: "password", name: "adminPassword", message: "Admin login password (leave blank to generate one)" },
+    ],
+    { onCancel }
+  );
+  const adminPassword = site.adminPassword || crypto.randomBytes(9).toString("base64url");
+
+  const apiEnv = buildApiEnv({
+    databaseUrl,
+    jwtSecret: randomSecret(),
+    adminEmail: site.adminEmail,
+    adminPassword,
+    storageProvider: provider,
+    storageEnvLines,
+    siteUrl: site.siteUrl,
+    revalidateSecret: randomSecret(),
+  });
+  const webEnv = buildWebEnv({ apiUrl: site.apiUrl, siteUrl: site.siteUrl });
+  const rootEnv = buildRootEnv({ db, databaseUrl, storageProvider: provider, storageEnvLines });
+
+  fs.writeFileSync(path.join(dest, "apps/api/.env"), apiEnv);
+  fs.writeFileSync(path.join(dest, "apps/web/.env.local"), webEnv);
+  fs.writeFileSync(path.join(dest, ".env"), rootEnv);
+
+  if (!site.adminPassword) {
+    console.log(`\nGenerated admin password: ${adminPassword}\n(save this — it's only shown once)`);
+  }
+
+  console.log("\nDone! Generated .env files for apps/api and apps/web.\n");
+  console.log("Next steps:");
+  console.log(`  cd ${targetDir}`);
+  console.log("  npm install");
+  if (usesDbPush(db.engine)) {
+    console.log("  npx prisma generate --schema apps/api/prisma/schema.prisma");
+    console.log("  npx prisma db push --schema apps/api/prisma/schema.prisma");
+    console.log("    (MySQL installs use db push instead of migrate — the bundled migration history is Postgres-specific SQL)");
+  } else {
+    console.log("  npm run db:migrate");
+  }
+  console.log("  npm run db:seed");
+  console.log("  npm run dev\n");
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "modern-cms",
+  "version": "1.0.0",
+  "description": "Self-hosted, drag-and-drop website CMS (Next.js + Express + Prisma). Interactive installer scaffolds a full project with your choice of PostgreSQL/MySQL and AWS S3/Azure Blob/Cloudinary storage.",
+  "type": "module",
+  "bin": {
+    "modern-cms": "./bin/modern-cms.js"
+  },
+  "files": [
+    "bin",
+    "template",
+    "README.md"
+  ],
+  "keywords": [
+    "cms",
+    "nextjs",
+    "prisma",
+    "page-builder",
+    "drag-and-drop",
+    "postgresql",
+    "mysql",
+    "s3",
+    "azure",
+    "cloudinary"
+  ],
+  "author": {
+    "name": "Md Isahaq (+880 1852376598)",
+    "email": "hmisahaq01@gmail.com"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "prompts": "^2.4.2"
+  }
+}

package/template/.env.example

@@ -0,0 +1,48 @@
+# --- Postgres ---
+POSTGRES_USER=pgcms
+POSTGRES_PASSWORD=pgcms_dev_password
+POSTGRES_DB=pgcms
+# Note: mapped to host port 5434 (not 5432) to avoid clashing with any locally installed
+# Postgres or other projects' containers — check `docker ps` for conflicts before reusing 5433.
+DATABASE_URL=postgresql://pgcms:pgcms_dev_password@localhost:5434/pgcms
+
+# --- Auth ---
+JWT_SECRET=change_me_to_a_long_random_string
+JWT_EXPIRES_IN=7d
+COOKIE_NAME=pgcms_token
+
+# --- Seed admin user ---
+SEED_ADMIN_EMAIL=admin@example.com
+SEED_ADMIN_PASSWORD=change_me_admin_password
+
+# --- MinIO / S3 ---
+# Mapped to host ports 9010/9011 (not the MinIO defaults 9000/9001) to avoid clashing
+# with other projects' containers — check `docker ps` for conflicts before reusing 9000.
+S3_ENDPOINT=http://localhost:9010
+S3_REGION=us-east-1
+S3_ACCESS_KEY_ID=pgcms_minio
+S3_SECRET_ACCESS_KEY=pgcms_minio_secret
+S3_BUCKET=pgcms-media
+S3_FORCE_PATH_STYLE=true
+# Public base URL used to build media URLs served back to the browser
+S3_PUBLIC_URL=http://localhost:9010/pgcms-media
+
+# --- API ---
+API_PORT=4000
+WEB_ORIGIN=http://localhost:3000
+
+# --- Web (Next.js) ---
+# Server-side only: used by next.config.mjs (API proxy/rewrites) and server components.
+# Not prefixed with NEXT_PUBLIC_ on purpose — the browser always calls the relative /api
+# path, which Next.js proxies to this URL, keeping the auth cookie first-party.
+API_URL=http://localhost:4000
+SITE_URL=http://localhost:3000
+
+# --- Cache revalidation (production) ---
+# API calls POST {REVALIDATE_URL}/api/revalidate after publish to bust ISR cache.
+REVALIDATE_URL=http://localhost:3000
+REVALIDATE_SECRET=change_me_revalidate_secret
+
+# --- Form integrations (optional) ---
+# POST JSON payload on every form submission: { event, id, formName, pageSlug, data, createdAt }
+FORMS_WEBHOOK_URL=

package/template/README.md

@@ -0,0 +1,210 @@
+# pg-cms
+
+A self-hosted, drag-and-drop website CMS. Build every page of a site visually — drag sections onto a canvas, edit their content and style in an inspector panel, animate them, and publish. The public site and the builder canvas render through the same React components, so what you see while editing is exactly what visitors get.
+
+Built as an npm-workspaces monorepo:
+
+| Workspace | What it is |
+|---|---|
+| `apps/web` | Next.js 14 (App Router) — the public site **and** the `/admin` builder UI |
+| `apps/api` | Express + Prisma + PostgreSQL — auth, pages, media, theme, forms |
+| `packages/shared` | Zod schemas, the component registry, and page-tree helpers shared by both |
+
+---
+
+## Quick start
+
+### Prerequisites
+
+- Node.js 18+
+- Docker Desktop (for PostgreSQL + MinIO)
+
+### 1. Start the databases
+
+```bash
+npm run docker:up
+```
+
+This starts:
+
+| Service | Host port | Notes |
+|---|---|---|
+| PostgreSQL 16 | **5434** | container port 5432; 5434 chosen to avoid clashing with other local Postgres instances |
+| MinIO (S3 API) | **9010** | media file storage |
+| MinIO console | **9011** | web UI for browsing the bucket |
+
+A one-shot init container creates the `pgcms-media` bucket automatically.
+
+> **Port conflicts:** if `docker compose up` fails with "port is already allocated", another container or service owns that port — run `docker ps` to find it, then either stop it or change the host-side port in `docker-compose.yml` **and** the matching URLs in `apps/api/.env`.
+
+### 2. Environment files
+
+Two env files are used:
+
+- **Repo root `.env`** — read by `docker-compose.yml` (Postgres user/password/db name, MinIO keys).
+- **`apps/api/.env`** — read by the API and Prisma (`DATABASE_URL`, JWT, S3, seed admin).
+
+Copy the example and adjust if needed:
+
+```bash
+cp .env.example .env
+cp .env.example apps/api/.env   # then trim to the API-relevant keys, or keep all
+```
+
+**Important:** the password inside `DATABASE_URL` in `apps/api/.env` must match `POSTGRES_PASSWORD` in the root `.env`. Postgres sets its password the *first* time its data volume is created — changing `.env` later does not change the database password.
+
+### 3. Install, migrate, seed
+
+```bash
+npm install
+npm run db:migrate     # applies Prisma migrations
+npm run db:seed        # creates the admin user, default theme, and a sample home page
+```
+
+Optional demo content (a full multi-section homepage and an extra page):
+
+```bash
+cd apps/api
+npx tsx prisma/seed-homepage.ts
+npx tsx prisma/seed-our-charities.ts
+```
+
+### 4. Run the dev servers
+
+```bash
+npm run dev            # API (port 4000) + web (port 3000) together
+# or separately:
+npm run dev:api
+npm run dev:web
+```
+
+### 5. Log in
+
+| URL | What |
+|---|---|
+| http://localhost:3000 | Public site |
+| http://localhost:3000/admin/login | Admin builder |
+
+**Default example credentials** (from `SEED_ADMIN_EMAIL` / `SEED_ADMIN_PASSWORD` in `apps/api/.env`):
+
+```
+Email:    admin@example.com
+Password: ChangeMe123!
+```
+
+> Change these before deploying anywhere real. The seed only sets the password when the user is first created — to change it later, update the env values, delete the user row, and re-run `npm run db:seed` (or update the password through the admin Users page).
+
+---
+
+## Features
+
+### Page builder
+
+- **Drag & drop** — drag components from the palette onto the canvas, reorder by dragging, nest inside containers/columns.
+- **Live canvas** — pages render with the same components as the public site; select any section to edit it.
+- **Inspector panel** — per-component **Content** tab (fields auto-generated from the component registry) and **Style** tab organized into collapsible groups: Basics, Border, Shadow & Opacity, Animation, Modern Effects, Advanced.
+- **Drag-to-resize** — pull the right/bottom edge handles of a selected section to set its width/height; columns resize their real CSS Grid tracks.
+- **Breadcrumb selection** — when a container is fully covered by its children, use the breadcrumb at the top of the Inspector to select the parent.
+- **Undo / redo** — Ctrl+Z / Ctrl+Y, with rapid edits coalesced into single history steps.
+- **Autosave & draft recovery** — periodic local backup with a restore prompt if the browser closes mid-edit.
+- **Revisions** — every save snapshots the previous version (last 30 kept); restore from Page Settings → History.
+- **Scheduled publishing** — set a future publish date; the page stays hidden until then.
+- **Show/hide** — non-destructively hide any section from the live site while keeping it in the builder.
+- **Developer mode** — the `</>` toggle in the Inspector reveals a raw JSON tab for editing any node's props/style directly.
+
+### Components (22+)
+
+Layout: Header (3-zone with logo/nav/buttons), Footer (link columns, contact info, socials), Columns/Container.
+Content: Hero, Rich Text (full toolbar: headings, lists, alignment, colors, links, quotes), Card Grid (image or icon tiles), Accordion/FAQ, Tabs (animated switching), Stats (count-up numbers), CTA, Countdown, Marquee/Ticker.
+Media: Image, Image Slider, Image/Video Background sections, 3D Background, Gallery.
+Interactive: Buttons, Map, Contact Form (submissions stored and viewable in the admin).
+
+### Animation system (GSAP)
+
+Every section of any type can animate — configured entirely in the Inspector:
+
+- **12 entrance effects** — fade, slide (4 directions), zoom, rotate, pulse, scroll-reveal, blur, flip, bounce.
+- **5 triggers** — on load, on scroll into view, on hover (reverses on leave), on focus, on click (plays a full tap gesture).
+- **Customization** — duration, delay, easing presets (smooth / overshoot / elastic / bounce / custom GSAP string), continuous loop.
+- **Stagger** — reveal a section's inner items (cards, paragraphs, buttons) one after another.
+- **Parallax** — sections drift against the scroll at a configurable speed.
+
+### Modern effects
+
+- **Hover effects** — lift, 3D tilt (follows the pointer), glow, scale.
+- **Glassmorphism** — one-click frosted-glass panels.
+- **Gradient headings** — fill a section's headings with a two-color gradient.
+- **Animated gradients** — hero backgrounds that slowly sweep their colors.
+
+### 3D backgrounds (Three.js)
+
+Six scene presets usable in the Hero or the dedicated 3D Background component: **Particles, Waves, Floating Shapes, Starfield, Network/Constellation, Orbit Rings** — each with two colors, density, speed, opacity, an on/off switch, and optional pointer-follow camera parallax. Three.js is lazy-loaded only on pages that actually use it, and all motion respects `prefers-reduced-motion`.
+
+### Site-wide
+
+- **Theme settings** — brand colors, fonts, logo applied via CSS variables everywhere.
+- **Navigation editor** — menu items with dropdown submenus.
+- **Media library** — uploads stored in MinIO/S3; image/video pickers throughout the builder.
+- **Form submissions** — public forms POST to the API; view/delete entries in the admin.
+- **SEO** — per-page title, description, and OG image.
+- **Escape hatches** — arbitrary custom CSS properties and HTML attributes (`data-*`, `aria-*`, `id`) on any section.
+
+---
+
+## Scripts reference
+
+| Command | What it does |
+|---|---|
+| `npm run dev` | API + web dev servers together |
+| `npm run dev:api` / `npm run dev:web` | Each dev server alone |
+| `npm run build` | Build shared → api → web for production |
+| `npm run docker:up` / `npm run docker:down` | Start / stop Postgres + MinIO |
+| `npm run db:migrate` | Apply Prisma migrations (`prisma migrate dev`) |
+| `npm run db:seed` | Seed admin user, theme, sample page |
+
+---
+
+## Project structure
+
+```
+pg-cms/
+  docker-compose.yml          # Postgres (5434) + MinIO (9010/9011)
+  .env / .env.example         # compose-level env
+  packages/shared/src/
+    schema/                   # Zod schemas: PageNode, NodeStyle, User, Theme, fields
+    components.ts             # THE component registry — one entry per block type
+    tree.ts                   # pure page-tree helpers (insert/move/remove/create)
+  apps/api/
+    .env                      # DATABASE_URL, JWT, S3, seed admin credentials
+    prisma/                   # schema, migrations, seed scripts
+    src/routes/               # auth, pages, media, theme, users, forms
+  apps/web/
+    app/[[...slug]]/          # public site — renders published pages
+    app/admin/                # login, dashboard, builder, media, settings
+    components/renderer/      # Renderer + one component per block type
+    components/builder/       # Palette, Canvas, Inspector, field editors
+    lib/                      # style mapping, GSAP hooks, Three.js scenes
+```
+
+### Adding a new component type
+
+1. Add a `ComponentDefinition` to `packages/shared/src/components.ts` (type, label, icon, default props/style, Inspector fields).
+2. Create the React component in `apps/web/components/renderer/sections/`.
+3. Register it in `apps/web/components/renderer/registry.tsx`.
+
+No builder-chrome changes needed — the palette, inspector, and drag-and-drop pick it up from the registry.
+
+---
+
+## Troubleshooting
+
+**`P1010: User was denied access` on migrate** — the `DATABASE_URL` password doesn't match what Postgres was initialized with, *or* you're accidentally connecting to a different Postgres on the same port (check `docker ps` for other projects' containers).
+
+**`port is already allocated` from Docker** — another container owns the host port. `docker ps`, then stop it or change the port mapping in `docker-compose.yml` + the URLs in `apps/api/.env`.
+
+**"Invalid email or password"** — credentials are case-sensitive; watch for browser autofill inserting a stale saved password. The current values live in `apps/api/.env`.
+
+**Prisma `EPERM ... query_engine ... .dll.node` on Windows** — the running API dev server is holding the engine file. Stop it (`netstat -ano | findstr :4000`, then kill that PID), run the migration, restart.
+
+**Dev server "running" but serving stale code** — an orphaned process may still own the port. Verify with `netstat -ano | findstr :3000` (or `:4000`) and kill the listed PID before restarting.
+"# Modern-CMS" 

package/template/apps/api/Dockerfile

@@ -0,0 +1,26 @@
+FROM node:24-alpine AS base
+WORKDIR /app
+
+FROM base AS deps
+COPY package.json package-lock.json ./
+COPY packages/shared/package.json ./packages/shared/
+COPY apps/api/package.json ./apps/api/
+RUN npm ci --workspace=apps/api --workspace=packages/shared --include-workspace-root
+
+FROM base AS build
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+RUN npm run db:generate -w apps/api
+RUN npm run build -w packages/shared && npm run build -w apps/api
+
+FROM base AS runner
+ENV NODE_ENV=production
+WORKDIR /app
+COPY --from=build /app/node_modules ./node_modules
+COPY --from=build /app/package.json ./
+COPY --from=build /app/packages/shared ./packages/shared
+COPY --from=build /app/apps/api/package.json ./apps/api/
+COPY --from=build /app/apps/api/dist ./apps/api/dist
+COPY --from=build /app/apps/api/prisma ./apps/api/prisma
+EXPOSE 4000
+CMD ["node", "apps/api/dist/index.js"]