Files
webb/docs/superpowers/plans/2026-11-04-webb-editor-admin-suite.md

13 KiB

WEBB Editor — Dedicated Admin Control Suite Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Build a completely independent, modern visual Admin Control Suite in /home/creserver/Desktop/WEBB_EDITOR running on port 3001, allowing visual live editing of the main website (/home/creserver/Desktop/WEBB on port 3000) — including text, media uploads, section toggles, horizontal scroll animation controls, and full tool creation (frontend UI + backend multipart API configuration) directly backed by JSON and the management/ folder.

Architecture: A standalone Next.js 14 web application in /home/creserver/Desktop/WEBB_EDITOR with Tailwind CSS, Lucide icons, and server-side API endpoints that read and write directly to ../WEBB/management/ and ../WEBB/content/. The main website on port 3000 has zero links, buttons, or access to the editor, ensuring complete isolation. Changes saved in the editor immediately persist to JSON on disk and reflect instantly on the main site.

Tech Stack: Next.js 14 (App Router), React 18, TypeScript, Tailwind CSS, Lucide React, Node.js fs/promises file manipulation, Native Form-Data upload handling.

Spec: User request dated 2026-11-04 specifying a dedicated admin control suite in a new folder, independent on another port, with no access from the main site, supporting text editing, photo upload/removal, feature toggles, horizontal scroll animation removal/toggling, full tool creation with frontend and backend multipart/form-data configuration, and instant dynamic JSON persistence.

Global Constraints

  • Location: The editor project MUST live at /home/creserver/Desktop/WEBB_EDITOR.
  • Port: The editor MUST run on port 3001 (or separate from main site port 3000).
  • Isolation: The main site (WEBB) MUST NOT contain any admin buttons, admin links, or administrative leakage.
  • Data Source of Truth: Edits must write directly to management/pages/.../page.config.json, management/pages/.../media/, content/collections/tools/*.json, content/api.catalog.json, and content/site.config.json.
  • Python Venv Rule: If python scripts are run, always use /home/creserver/extras/local_venv/bin/python.

Review Focus

  1. Path Resolution: Relative paths to ../WEBB must reliably resolve regardless of process working directory.
  2. File Permissions & Upload Safety: Uploaded images must be written atomically to ../WEBB/management/.../media/ and sanitized to prevent directory traversal.
  3. JSON Schema Integrity: Written JSON files must preserve valid JSON formatting with proper whitespace and typed schema fields.
  4. Instant Dynamic Reflection: Main site WEBB on port 3000 must load updated JSON content immediately without requiring a full manual rebuild.
  5. Form-Data Backend Config: Tool creation must support full backend specifications: API endpoint URL, HTTP method, multipart/form-data field names (e.g. image), parameters, and header options.

Task 1: Initialize Standalone WEBB_EDITOR Project & Scaffolding

Files:

  • Create: /home/creserver/Desktop/WEBB_EDITOR/package.json

  • Create: /home/creserver/Desktop/WEBB_EDITOR/tsconfig.json

  • Create: /home/creserver/Desktop/WEBB_EDITOR/tailwind.config.js

  • Create: /home/creserver/Desktop/WEBB_EDITOR/postcss.config.js

  • Create: /home/creserver/Desktop/WEBB_EDITOR/next.config.js

  • Create: /home/creserver/Desktop/WEBB_EDITOR/src/app/globals.css

  • Create: /home/creserver/Desktop/WEBB_EDITOR/src/app/layout.tsx

  • Step 1.1: Create directory /home/creserver/Desktop/WEBB_EDITOR with Next.js 14, Tailwind CSS, Lucide React dependencies.

  • Step 1.2: Configure next.config.js with port 3001 defaults and image domains.

  • Step 1.3: Configure tailwind.config.js with admin studio color palette (slate/indigo/amber luxury dark/light theme).

  • Step 1.4: Install dependencies using npm install inside /home/creserver/Desktop/WEBB_EDITOR.

  • Step 1.5: Verify project builds with npm run build.


Task 2: Core File System Bridge & Backend Service Library

Files:

  • Create: /home/creserver/Desktop/WEBB_EDITOR/src/lib/bridge.ts

  • Create: /home/creserver/Desktop/WEBB_EDITOR/src/lib/types.ts

  • Test: /home/creserver/Desktop/WEBB_EDITOR/src/lib/bridge.test.ts

  • Step 2.1: Define TypeScript schemas for HomePageConfig, ToolItem, ApiEndpoint, ShowcaseItem, and SectionToggle.

  • Step 2.2: Implement getWebbPath(subpath: string) with absolute resolution targeting /home/creserver/Desktop/WEBB.

  • Step 2.3: Implement safe JSON reader and writer functions with backup snapshot creation.

  • Step 2.4: Implement media file scanner that lists all images in ../WEBB/management/pages/home/media/ and ../WEBB/management/pages/tools/*/media/.

  • Step 2.5: Write unit tests verifying read/write integrity against test JSON structures.


Task 3: API Endpoints for Pages, Sections, Media, and Tools

Files:

  • Create: /home/creserver/Desktop/WEBB_EDITOR/src/app/api/pages/home/route.ts

  • Create: /home/creserver/Desktop/WEBB_EDITOR/src/app/api/tools/route.ts

  • Create: /home/creserver/Desktop/WEBB_EDITOR/src/app/api/tools/[slug]/route.ts

  • Create: /home/creserver/Desktop/WEBB_EDITOR/src/app/api/media/upload/route.ts

  • Create: /home/creserver/Desktop/WEBB_EDITOR/src/app/api/media/delete/route.ts

  • Create: /home/creserver/Desktop/WEBB_EDITOR/src/app/api/sections/toggle/route.ts

  • Step 3.1: Build GET and POST for /api/pages/home to fetch and update management/pages/home/page.config.json.

  • Step 3.2: Build /api/sections/toggle to toggle section visibility or change layout settings (e.g. toggle horizontal scroll animation vs vertical stack).

  • Step 3.3: Build POST for /api/media/upload accepting multipart/form-data and writing files directly into ../WEBB/management/pages/.../media/.

  • Step 3.4: Build POST for /api/media/delete to safely remove unused images.

  • Step 3.5: Build GET, POST, PUT, DELETE for /api/tools to manage content/collections/tools/*.json and content/api.catalog.json.


Task 4: Admin Studio Navigation, Layout & Dashboard Overview

Files:

  • Create: /home/creserver/Desktop/WEBB_EDITOR/src/components/layout/AdminSidebar.tsx

  • Create: /home/creserver/Desktop/WEBB_EDITOR/src/components/layout/AdminHeader.tsx

  • Create: /home/creserver/Desktop/WEBB_EDITOR/src/app/page.tsx (Dashboard Overview)

  • Step 4.1: Build AdminSidebar with navigation links: Overview, Homepage Editor, Showcase Models, Tool Studio (Frontend + Backend), Media Asset Manager, and Settings.

  • Step 4.2: Build AdminHeader showing live server status badge (Main Site: http://localhost:3000 status indicator, Editor: port 3001, quick Save & Sync button).

  • Step 4.3: Build Dashboard Overview page displaying active tools counter, active categories, total images managed, and quick actions.


Task 5: Visual Homepage & Sections Manager (With Animation Toggles)

Files:

  • Create: /home/creserver/Desktop/WEBB_EDITOR/src/app/pages/home/page.tsx

  • Create: /home/creserver/Desktop/WEBB_EDITOR/src/components/editor/SectionCard.tsx

  • Create: /home/creserver/Desktop/WEBB_EDITOR/src/components/editor/HeroEditorModal.tsx

  • Create: /home/creserver/Desktop/WEBB_EDITOR/src/components/editor/AnimationControlsModal.tsx

  • Step 5.1: Build Section Manager list displaying all 10 homepage sections with drag/reorder and toggle switches (enabled / disabled).

  • Step 5.2: Implement Horizontal Scrolling Animation Toggle: - Option A: Pinned Sticky Cinematic Runway (horizontal scroll translation). - Option B: Clean Fluid Vertical Stack (horizontal animation completely disabled). - Option C: Completely Remove Flagship Showcase Section.

  • Step 5.3: Build in-place text editor for Hero title, subtitle, badges, and trust indicators.

  • Step 5.4: Implement instant save handler that writes to ../WEBB/management/pages/home/page.config.json.


Task 6: Interactive Model Showcase Manager

Files:

  • Create: /home/creserver/Desktop/WEBB_EDITOR/src/app/showcase/page.tsx

  • Create: /home/creserver/Desktop/WEBB_EDITOR/src/components/showcase/ShowcaseCardEditor.tsx

  • Step 6.1: Build visual card list for all flagship showcase models.

  • Step 6.2: Add card creation and deletion controls.

  • Step 6.3: Implement variant selector (comparison slider vs banner).

  • Step 6.4: Add direct image uploader for Before / After / Banner images with instant thumbnail preview.

  • Step 6.5: Add inputs for model name, latency chip, category, specs checklist, and tool link.


Task 7: Full Tool Studio Creator (Frontend UI + Backend Multipart API)

Files:

  • Create: /home/creserver/Desktop/WEBB_EDITOR/src/app/tools/page.tsx

  • Create: /home/creserver/Desktop/WEBB_EDITOR/src/app/tools/new/page.tsx

  • Create: /home/creserver/Desktop/WEBB_EDITOR/src/app/tools/[slug]/page.tsx

  • Create: /home/creserver/Desktop/WEBB_EDITOR/src/components/tools/ToolFrontendForm.tsx

  • Create: /home/creserver/Desktop/WEBB_EDITOR/src/components/tools/ToolBackendApiForm.tsx

  • Step 7.1: Build Tool listing page showing all tools with search, category filtering, and status badges.

  • Step 7.2: Build ToolFrontendForm for frontend presentation: - Tool Name, Slug, Summary, Category, Associated App (homeApp), Badges, Limits (MB), and Sample Presets. - Before/After demonstration image uploader that saves directly into ../WEBB/management/pages/tools/[slug]/media/.

  • Step 7.3: Build ToolBackendApiForm for backend execution: - API Endpoint URL (e.g. http://127.0.0.1:8000/api/v1/process), HTTP Method (POST / GET). - Multipart/form-data configuration: Upload file field name (e.g. image or file), optional fields, parameter bindings. - Custom headers (e.g. Bearer token, API keys), timeout settings.

  • Step 7.4: Build atomic save routine that writes: - Tool JSON -> /home/creserver/Desktop/WEBB/content/collections/tools/[slug].json - API Endpoint -> /home/creserver/Desktop/WEBB/content/api.catalog.json & /content/api.overlay.json

  • Step 7.5: Build tool deletion routine that removes tool definitions safely.


Files:

  • Create: /home/creserver/Desktop/WEBB_EDITOR/src/app/media/page.tsx

  • Create: /home/creserver/Desktop/WEBB_EDITOR/src/components/media/MediaUploadZone.tsx

  • Create: /home/creserver/Desktop/WEBB_EDITOR/src/components/media/MediaCard.tsx

  • Step 8.1: Build visual gallery showing all media files in ../WEBB/management/.

  • Step 8.2: Implement drag-and-drop file uploader supporting JPG, PNG, WEBP, and MP4.

  • Step 8.3: Add copy image path button (/management/...) for easy insertion into configs.

  • Step 8.4: Add delete asset modal with confirmation.


Task 9: Enable Dynamic Revalidation in Main Site (WEBB)

Files:

  • Modify: /home/creserver/Desktop/WEBB/src/app/page.tsx

  • Modify: /home/creserver/Desktop/WEBB/src/app/tools/[slug]/page.tsx

  • Step 9.1: Add export const dynamic = 'force-dynamic' and export const revalidate = 0 to src/app/page.tsx in WEBB.

  • Step 9.2: Add export const dynamic = 'force-dynamic' and export const revalidate = 0 to src/app/tools/[slug]/page.tsx in WEBB.

  • Step 9.3: Verify that modifying management/pages/home/page.config.json immediately updates the live page on http://localhost:3000 without rebuilding.


Task 10: End-to-End Verification, Server Startup & Health Audit

Files:

  • Verify: Port 3000 (WEBB) running without any admin links.

  • Verify: Port 3001 (WEBB_EDITOR) running cleanly as standalone admin suite.

  • Test script: /home/creserver/Desktop/WEBB_EDITOR/tests/e2e-sync.test.ts

  • Step 10.1: Run npm run build inside /home/creserver/Desktop/WEBB_EDITOR with zero errors.

  • Step 10.2: Start WEBB_EDITOR on port 3001 (npm run start -- -p 3001 or daemon).

  • Step 10.3: Execute test: Edit homepage badge via WEBB_EDITOR API / UI -> Verify updated text on http://localhost:3000.

  • Step 10.4: Execute test: Add new tool with frontend and backend multipart config -> Verify new tool appears in /tools and /tools/[slug].

  • Step 10.5: Execute test: Upload image via Media Asset Manager -> Verify image exists in management/ and renders on http://localhost:3000.

  • Step 10.6: Puppeteer in-browser verification of admin suite UI and live sync confirmation.