← Back
← Back
# Gallery / FvW Architectural Audit
**Date:** 2026-08-12 | **Author:** fv-gallery-mavis (id 8) | **Ref:** b1046-b1049
**Repos:** fv-module-gallery @ 8a34d53, fv-cms-vendored @ v1.2.0 (b1c4dafb), fv-gallery-ui @ e4e2497
---
## 1. Component map (3-layer doctrine)
| Layer | Repo | Shape | FvW v8 compliance |
|---|---|---|---|
| **Doctrine** | `gallery-pact/fvw/freshvibe-way-v8/` | 53 .md files (§00-§35) | The source of truth |
| **Registry** | `cms-widgets/` + `modules/` + `bundles/` + `apps/` | 26 widgets + 28 modules + 1 bundle + 4 apps | 12/26 widgets at 11/11 (FES) |
| **CMS** | `fv-cms-vendored/` (v1.2.0) | 311 files, 24 inspector controls, 40+ app-fragments | 8-artefact + 9-folder shape |
| **Discovery** | `fv-gallery-ui` | 27 React components, 22 pages, dynamic `preview.html` | Reads /feed/, renders registry |
The 24 inspector controls are **shared chrome** — they read the `schema` field in each widget's `module.json` and auto-render the form.
Recipe Book shape (FvW v8 §11 + §17): 10 §11 files + 1 §17 file = **11 per module**. Gallery adds 1 affordance (`preview.html` at gallery root) = 12 total per-module check.
---
## 2. Integration map
[FvW doctrine] → [Gallery registry] → [FvCMS vendored]
↙ ↘
[fv-gallery-ui] [Consumer apps]
(discovery) (Oscar, FreshCards, etc.)
- fv-gallery-ui fetches `/feed/registry.json` + `/feed/recipe/:id/:item` (auto-built by `.github/workflows/build-feed.yml`)
- Consumer apps mirror `cms-widgets/<id>/` per FvW v8 §17.5.2 (gallery-mirror kind)
- FES worker lives in vendored FvCMS at `docs/_code-references/fes_worker_deterministic.py`
**Module kinds (`_module_kind`):** gallery-original 33, gallery-mirror 25, app-pointer 4, original/borrowed/app-fork 0.
---
## 3. Fragmentation points
### 3a. Recipe Book incompleteness (14/26 widgets < 11/11)
- **0/11 (no FES run):** fv-recipe-book-checklist, fv-source-link, fv-theme-toggle, theme-presets, tools (the 5 sub-tools), and `index.js` (a misplaced loader file)
- **2/11 (partial):** accordion, blog-post-card, blog-post-list, button, info-box, listing-grid, recipe-detail, video
### 3b. Tool duplication
The 5 tools exist in 2 places: `cms-widgets/tools/<name>/` (gallery, 0/11) and `fv-cms-vendored/.../editor-inspector/controls/<name>/` (CMS, full FES). Different module.json structures in each.
### 3c. Inspector ownership
The 12 migrated modules' inspectors live in the **shared chrome**, not per-module. The doctrine says "every module has a buildable inspector" (§17.8.5 step 5) — true via shared-chrome + per-module `schema`, but no per-module `inspector.js` exists.
### 3d. /feed/ stale on VPS
The auto-deploy cron handles `dist/` but not `/feed/`. Verified: 12 migrated modules show 0/11 on the live site (SPA fallback). Bulletin b1021 filed.
---
## 4. Consolidation recommendations
- **R1.** Run FES on 14 remaining widgets (~2.5h with GLM-4.5-flash). Target: 26/26 at 11/11.
- **R2.** Resolve tool duplication: promote 5 tools to `cms-widgets/tools/<name>/` at 11/11, have vendored FvCMS **import** from gallery (gallery is canonical per §17.5.2).
- **R3.** Amend §17.8.5 step 5 to clarify: "inspector is builtable via shared chrome + per-module schema" — not per-module file. Avoids R3a (adding 11th Recipe Book item).
- **R4.** Move misplaced `cms-widgets/index.js` → `scripts/gallery-loader.js`. It's a loader, not a module.
- **R5.** Fix auto-deploy cron: add `scripts/build-feed.py` + rsync `/feed/` step.
---
## 5. Unified editing workflow
[Operator] → [App's modules/<name>/]
│ (FES rebuild or git push to mirror)
▼
[fv-module-gallery/cms-widgets/<name>/] ← canonical
│ (auto: GitHub Action on push to main)
▼
[/feed/registry.json + /feed/recipe/<name>/*.md]
│ (live: fv-gallery-ui fetches)
▼
[gallery.freshvibeapps.com /modules/<name>] ← visual + Recipe Book + preview
│ (operator sees it, decides to use)
▼
[Consumer apps via /api/agent/cms-widgets or hard-import]
**Single source of truth:** `cms-widgets/<name>/module.json` + `src/widget.js`. The schema drives the inspector UI in 4 places (gallery detail, gallery preview, vendored FvCMS chrome, consumer apps).
**Single editing tool:** FES worker. Per §17.8.1: "Hand-coding module changes is forbidden."
**Single publish path:** push to main → GitHub Action → /feed/ → gallery → consumers.
---
## TL;DR
Gallery is a **healthy 3-layer system** (doctrine → registry → rendering) with **one consolidation gap** (14 widgets need FES runs) and **one operational gap** (/feed/ deploy step missing in the cron). Doctrine is constitutionally clear; runtime is mostly working. After R1 (14 FES runs) + R5 (fix cron) + R3 (amend §17.8.5), the gallery is at 100% FvW v8 §17.8 compliance.
**Word count:** ~600