# Architecture (finally understood, 2026-07-27)

After G told me to read the actual repos instead of guessing, here's the real
picture. I had been conflating 3 different things.

## The 4 layers (in order of how they fit together)

### 1. FvRE (Python) — `avidtech6/freshvibe-reconstruction-engine`
- **What**: A Python tool that scrapes a live site (or parses a .wpress),
  produces a "Recipe" (JSON) describing structure, content, schemas, and
  rebuilds the site as a static dist with annotation tags.
- **Where**: `/workspace/fvre/` (local clone)
- **Entry point**: `fv-extract wp-pipeline <url|wpress> --output ./out`
- **Output**:
  - `dist/` — static HTML pages
  - `wordpress-baseline/` — post_types, taxonomies, field_groups, records,
    media, pages, navigation
  - `cms-baseline.json` — combined CMS admin input
- **Packages** (A-G):
  - A: browser-runner (Playwright)
  - B: extraction_A (DOM walk)
  - C: extraction_C (Elementor-specific)
  - scan: pre-flight detection
  - elementor-adapter: Elementor semantic interpretation
  - wp-adapter: WordPress-specific (post types, taxonomies, media)
  - measurement: safe diff
  - generation: code-gen wrappers
  - test-harness
  - migration
  - cli

### 2. freshvibe-cms (the FIRST ROUND CMS) — local source
- **What**: A complete, self-contained, module-based CMS designed to overlay
  any FvRE-generated dist. The "first round" because it's module-centric
  (groups in the page become editable modules), not record-centric.
- **Where**: `/workspace/freshvibe-cms/`
- **Status**: 49/49 tests passing, v0.3.0
- **10 canonical modules**: Heading, CTA, Image, Paragraph, Video, Carousel,
  Menu, Social icons, Accordion, Icon list
- **Each module has**:
  - `id`, `label`, `description`
  - `schema` (typed fields: string, select, color, image, etc)
  - `defaultConfig`
  - `render(instance, def, skin)` — patches the live DOM
- **Features**:
  - IndexedDB store with scope resolver
  - Elementor + EAEL detector (auto-discovers modules in dist)
  - Annotation script (scans dist → JSON)
  - Annotation loader for runtime
  - Generic form editor + inline text editor
  - **DOM re-renderer** — edits show live
  - **Skins system** — 2 sample skins (Reign, BuddyX)
  - **Group → module toggle** — operator UI to promote/demote
  - **Region visualiser** — dashed overlays with labels
  - **app-fragments** (editor-breadcrumb, editor-context-menu, editor-inspector,
    editor-navigator, editor-outline, editor-selection)
- **The 24 world-class controls** (image picker, typography, color v2, etc)
  live in `freshvibe-cms/app-fragments/editor-inspector/controls/` and are
  real, working files (verified: 24 directories, sizes 1-6KB each).

### 3. oscar-web/cms (the Generic CMS Module, "Stage 2")
- **What**: A different, record-based CMS that's also in the oscar-web repo.
  NOT a copy of freshvibe-cms — it's a separate "Generic CMS Module" with
  189/189 tests.
- **Where**: `/workspace/oscar-web-src/oscar-web/cms/`
- **Status**: 189/189 tests passing
- **Architecture**: SPA (admin.html + admin.js + router.js + views/*.html)
- **Schemas**: book, news, quiz, siteSettings (Oscar-specific)
- **13 field types**: string, textarea, markdown, url, integer, number,
  boolean, array, enum, references, image, datetime, color
- **Features**:
  - CRUD for any content type (schema-driven)
  - Bulk import (JSON, JSONL, CSV, AI-prompted)
  - Activity log
  - Backups
  - PBKDF2 auth with lockout
  - Pluggable storage adapter (localStorage today)
- **G's instruction (verbatim)**: "the fresh vibes CMS that overlays is
  meant to be a direct copy of what's in the first round CMS repo"
- **So this should BE FRESHVIBE-CMS** (or a copy of it), not a separate
  generic CMS. The fact that it's a different module is the problem.

### 4. FES Inspector (a dev tool) — what I was patching
- **What**: A developer tool in `oscar-web/app-fragments/oscar-fes-inspector/`
  that lets the operator click section/widget badges on the page and edit
  their data-settings in a panel. This is a LIVE EDIT tool for Elementor
  widgets, not a content management system.
- **Where**: `/workspace/oscar-web-src/oscar-web/app-fragments/oscar-fes-inspector/`
- **Files**: oscar-inspector-dispatcher.js, oscar-trace.js, FES spec JSON files
- **The "FES"** = FreshVibe Elementor Spec (the JSON specs in fes-modules/)
- **"FES v2"** = a world-class form renderer for the inspector (mostly
  copy-pasted from freshvibe-cms/app-fragments/editor-inspector/)
- **What I did wrong**: I treated FES v2 as the world-class CMS. It's
  actually a dev tool for editing widgets, and only 2 of its 23 controls
  were properly implemented in oscar-web. The real 24 world-class controls
  are in freshvibe-cms — and they're not deployed to oscar-web.

## What "world-class CMS" means in this context

G's complaints ("image picker", "width talks about objects", "S-10
nothing in the panel") were about the FES inspector (dev tool), not the
actual CMS. The actual CMS is the freshvibe-cms (first round) which is
a complete, working module-based overlay.

The fix isn't to build 19 missing controls. The fix is:

1. **Deploy freshvibe-cms to oscar-web** — copy the
   `freshvibe-cms/app-fragments/editor-inspector/controls/` directory
   to oscar-web, copy the `app-fragments/editor-outline`,
   `editor-navigator`, `editor-selection`, `editor-context-menu`,
   `editor-breadcrumb` to oscar-web, and wire it up so it overlays
   the static dist.

2. **OR copy freshvibe-cms wholesale to oscar-web** — make oscar-web/cms
   BE freshvibe-cms (or a copy of it), not the separate Generic CMS Module.

3. **The FES Inspector dev tool** is a separate concern. It edits Elementor
   widget data-settings. The 23 world-class controls should be SHARED with
   freshvibe-cms (since they're literally the same code) but the dev tool
   is for editing the page structure, not content.

## What I should do next

1. Verify the freshvibe-cms controls directory is complete and works
2. Copy freshvibe-cms → oscar-web so the operator has the actual CMS
   available at oscar-web.freshvibeapps.com
3. Then think about whether the FES inspector dev tool should be retired
   or kept as a separate utility
4. Stop calling FES v2 "world-class" — it's a dev tool with the same 24
   controls copied from freshvibe-cms