# Advanced CMS Editor - Design Document
**Date:** November 25, 2025
**Feature:** Multi-page CMS with structured content sections for Professional-tier dealers
**Status:** Design Approved for Implementation
---
## Overview & Goals
### What We're Building
An Advanced CMS Editor for Professional-tier AMSOIL dealers to create and manage multi-page websites with structured, reusable content sections.
### Key Requirements
- **Professional tier only** (not Starter/Growth/Enhanced)
- **Multi-page support** (Home, About, Blog posts, custom pages)
- **Structured section-based content** (not freeform HTML)
- **Blog system** with auto-generated index at `/blog`
- **Dynamic navigation** (dealers control which pages appear in nav, support nested menus)
- **Draft/Publish workflow** (safe editing without affecting live site)
- **Publishes to flat HTML files** (same infrastructure as current system)
- **Migration support** for 3500+ existing dealer sites (scraped HTML import)
### MVP Section Types
1. **Rich Text/HTML Block** - Tiptap editor with standard formatting (headings H2-H4, lists, bold, italic, links, strikethrough)
2. **Accordion Section** - Collapsible items with title + rich text content
3. **Tabbed Content Section** - Horizontal tabs with sliding animation, same structure as Accordion
### Out of Scope (Post-MVP)
- 2-column sections (requirements TBD)
- Image uploads (dealers select from AMSOIL library later)
- Drag-and-drop section reordering (using up/down arrows for MVP)
- Inline WYSIWYG editing (using form-based editor for MVP)
- Version history/rollback (can add later via separate versions table)
- Page templates (pre-configured section layouts)
- Subheader nav editor (remains static AMSOIL corporate links)
---
## Database Schema
### New Page Model
```prisma
model Page {
id String @id @default(cuid())
dealerId String
// Core fields
slug String // 'about', 'my-first-post' (no leading slash)
title String // Page title (also used in nav if linked)
type String // 'page' | 'blog'
// Content (dual-mode for migration support)
sections Json? // Structured sections for new pages
rawHtml String? // Legacy HTML for migrated pages (mutually exclusive with sections)
// SEO
metaTitle String? // Override title for tag
metaDescription String? // Meta description
// Blog-specific
featuredImage String? // URL to AMSOIL library image
excerpt String? // Manual excerpt (fallback: first ~300 chars)
author String? // Dealer name or custom
// Publishing
status String @default("draft") // 'draft' | 'published'
publishedAt DateTime?
publishScheduledFor DateTime? // Future: scheduled publishing
// Timestamps
createdAt DateTime @default(now())
updatedAt DateTime @updatedAt
// Relations
dealer Dealer @relation(fields: [dealerId], references: [id], onDelete: Cascade)
navigationItems NavigationItem[]
@@unique([dealerId, slug]) // Slugs must be unique per dealer
@@index([dealerId, type, status]) // Fast queries for dealer's pages/blog
}
```
### New NavigationItem Model
Handles nested navigation with parent/child relationships. Parents can be labels (no link), link to pages, or link to external URLs.
```prisma
model NavigationItem {
id String @id @default(cuid())
dealerId String
// Display
label String // "Products", "About", etc.
// Link target (mutually exclusive - at most one should be set)
pageId String? // Link to dealer's page
externalUrl String? // Link to external URL (AMSOIL corporate, etc.)
// If both null, it's a label-only parent (no link)
// Hierarchy
parentId String? // null = top-level, set = child item
sortOrder Int @default(0) // Order within level
// Metadata
openInNewTab Boolean @default(false) // target="_blank"
// Relations
dealer Dealer @relation(fields: [dealerId], references: [id], onDelete: Cascade)
page Page? @relation(fields: [pageId], references: [id], onDelete: SetNull)
parent NavigationItem? @relation("NavHierarchy", fields: [parentId], references: [id], onDelete: Cascade)
children NavigationItem[] @relation("NavHierarchy")
@@index([dealerId, parentId, sortOrder]) // Fast hierarchy queries
}
```
**Navigation Rules:**
- Max 2 levels deep (parent → child, no grandchildren)
- Top-level items: `parentId = null`, sorted by `sortOrder`
- Child items: `parentId` set, sorted by `sortOrder` within parent
- Editor validates max depth = 2
- Deleting a page sets `pageId = null` (nav item becomes label-only, doesn't break nav)
- Deleting a parent item cascades to children
**Navigation by Tier:**
- **Starter/Growth:** Default nav items seeded on registration, NO editor access (completely fixed)
- **Enhanced/Professional:** Full nav editor access (add/edit/delete/reorder items)
**Default Navigation Items (seeded on registration):**
- Shop Online → External AMSOIL store URL
- Business Opportunities → External AMSOIL corporate URL
- Offers → External AMSOIL preferred customer URL
- Contact Us → `/contact` page (if exists) or anchor link
- About → `/about` page (if exists)
### Update Dealer Model
Add relations:
```prisma
model Dealer {
// ... existing fields ...
pages Page[]
navigationItems NavigationItem[]
}
```
### Key Design Decisions
- `slug` is relative (no leading `/`) - `/blog/` prefix added at publish time for blog posts
- `sections` OR `rawHtml` (mutually exclusive) - migration flexibility
- `@@unique([dealerId, slug])` prevents duplicate URLs per dealer
- Blog posts: `type='blog'` by default
- `showInNav` removed from Page model - navigation now managed via separate NavigationItem model
---
## Section Types & Data Structures
### Sections JSON Structure
The `Page.sections` field stores an array of section objects:
```typescript
type PageSections = Section[];
type Section = {
id: string; // Unique ID (cuid) for React keys and reordering
type: 'richText' | 'accordion' | 'tabs';
sortOrder: number; // Order on page (0, 1, 2, ...)
data: RichTextData | AccordionData | TabsData;
};
```
### 1. Rich Text Block
```typescript
type RichTextData = {
content: string; // Tiptap HTML output (sanitized)
};
// Example:
{
id: "clx123",
type: "richText",
sortOrder: 0,
data: {
content: "<h2>About Us</h2><p>We are a <strong>full-service</strong> AMSOIL dealer...</p>"
}
}
```
**Allowed Formatting:**
- Bold, italic, underline, strikethrough
- Headings (H2, H3, H4)
- Paragraphs
- Bulleted and numbered lists
- Links
- Line breaks
### 2. Accordion Section
```typescript
type AccordionData = {
items: AccordionItem[];
};
type AccordionItem = {
id: string; // Unique ID for each accordion item
title: string; // Plain text title (shown in accordion header)
content: string; // Tiptap HTML for accordion body
};
// Example:
{
id: "clx456",
type: "accordion",
sortOrder: 1,
data: {
items: [
{
id: "clx789",
title: "What products do you carry?",
content: "<p>We carry the full line of <strong>AMSOIL products</strong>...</p>"
},
{
id: "clx012",
title: "Do you offer delivery?",
content: "<p>Yes! We offer free delivery on orders over $100.</p>"
}
]
}
}
```
### 3. Tabbed Content Section
```typescript
type TabsData = {
items: TabItem[];
};
type TabItem = {
id: string; // Unique ID for each tab
title: string; // Tab label (plain text)
content: string; // Tiptap HTML for tab content
};
// Structure identical to Accordion, different display mode
// Example: "Protects Against Wear" and "Applications" tabs
```
**Key Points:**
- Each section has unique `id` for React keys and reordering
- `sortOrder` determines page layout order
- Accordion and Tabs share identical data structure (just different rendering)
- All rich content goes through Tiptap → sanitized HTML
---
## Editor UI & User Experience
### Route Structure
- `/dashboard/editor` - Current Basic Editor (dealer profile info)
- `/dashboard/cms` - **NEW:** Advanced CMS landing page (Professional tier only)
- `/dashboard/cms/pages` - Page list view
- `/dashboard/cms/pages/new` - Create new page
- `/dashboard/cms/pages/[pageId]/edit` - Edit existing page
- `/dashboard/cms/navigation` - Navigation editor (Enhanced/Professional only)
**Tier Gating:**
```typescript
// All /dashboard/cms/* routes check tier
if (dealer.subscriptionTier !== 'professional') {
redirect('/dashboard'); // Or show upgrade prompt
}
// Navigation editor specifically
if (!['enhanced', 'professional'].includes(dealer.subscriptionTier)) {
redirect('/dashboard/cms/pages');
}
```
### Page List View (`/dashboard/cms/pages`)
**Layout:**
- Table showing all dealer's pages
- Columns: Title, Type (Page/Blog), Status (Draft/Published), Last Updated, Actions
- Filter by type (All / Pages / Blog)
- Filter by status (All / Draft / Published)
- "New Page" button → page creation flow
- Actions per row: Edit, Preview, Duplicate, Delete
### Page Editor (`/dashboard/cms/pages/[pageId]/edit`)
**Form-based editor with three main sections:**
#### 1. Page Settings (top form):
- **Title** (text input) - Required
- **Slug** (text input) - Auto-generated from title, editable, validated for uniqueness
- **Type** (dropdown: Page / Blog Post)
- **Meta Title** (optional text input) - SEO override
- **Meta Description** (optional textarea) - SEO description
- **Featured Image** (dropdown/picker from AMSOIL library - future, disabled for MVP)
- **Excerpt** (textarea, optional for blog posts) - Manual excerpt or auto-extract first ~300 chars
#### 2. Content Sections (middle area):
- **List of sections**, each displayed as a card
- **Section card shows:** Type icon, preview snippet, up/down arrows, delete button
- **"Add Section" button** with dropdown (Rich Text / Accordion / Tabs)
- **Click section card** → expands inline form to edit that section
- **For Accordion/Tabs:** nested list of items with add/remove/reorder (up/down arrows)
**Section Reordering:**
- Simple up/down arrow buttons on each section card
- Updates `sortOrder` field
- No drag-and-drop for MVP (can add later)
#### 3. Actions (sticky footer):
- **"Save Draft"** button (saves without publishing)
- **"Publish"** button (saves + publishes to live site)
- **"Preview"** button (opens preview in new tab)
- **"Cancel"** button (back to page list, confirm if unsaved changes)
### Navigation Editor (`/dashboard/cms/navigation`)
**Layout:**
- Hierarchical list showing parent/child structure
- Each item shows: Label, Link Target (Page/External/None), Actions
- **Add Top-Level Item** button
- **Add Child Item** button (only for parents, max 2 levels)
- **Up/Down arrows** to reorder within level
- **Edit/Delete** buttons per item
**Edit Item Form:**
- **Label** (text input) - Required
- **Link Type** (radio: None / Page / External URL)
- If Page: Dropdown of dealer's published pages
- If External: Text input for URL
- **Open in New Tab** (checkbox)
- **Parent** (dropdown: None / select parent item) - Validates max 2 levels
---
## Publishing Flow & Static HTML Generation
### Draft → Published Workflow
1. **Dealer edits page** → Clicks "Save Draft"
- `status = 'draft'`
- `publishedAt = null`
- Changes saved to database only
- Not visible on live site
2. **Dealer clicks "Publish"**
- `status = 'published'`
- `publishedAt = now()`
- Triggers HTML generation
- Deploys to live site (Cloudflare)
### Publishing Process
```typescript
async function publishPage(pageId: string) {
// 1. Fetch page data
const page = await prisma.page.findUnique({
where: { id: pageId },
include: { dealer: true },
});
// 2. Determine output path
const filename = page.type === 'blog' ? `blog/${page.slug}.html` : `${page.slug}.html`;
// 3. Render HTML
const html = page.rawHtml
? renderLegacyPage(page) // Use rawHtml for migrated pages
: renderStructuredPage(page); // Render sections for new pages
// 4. Write to CDN/storage
await writeToCloudflare(dealer.subdomain, filename, html);
// 5. Update page status
await prisma.page.update({
where: { id: pageId },
data: {
status: 'published',
publishedAt: new Date(),
dealer: {
update: {
lastPublishedAt: new Date(),
},
},
},
});
// 6. Regenerate blog index if this was a blog post
if (page.type === 'blog') {
await generateBlogIndex(dealer.id);
}
}
```
### Rendering Structured Pages
```typescript
function renderStructuredPage(page: Page): string {
const sections = page.sections as Section[];
const sectionsHtml = sections
.sort((a, b) => a.sortOrder - b.sortOrder)
.map((section) => {
switch (section.type) {
case 'richText':
return renderRichText(section.data);
case 'accordion':
return renderAccordion(section.data);
case 'tabs':
return renderTabs(section.data);
}
})
.join('\n');
return `
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>${page.metaTitle || page.title}
${renderHeader(page.dealer)}
${sectionsHtml}
${renderFooter(page.dealer)}