petal-power/wiki-vault
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
0e6c1dd81c
wiki-vault/Sources/Dev/pbs-hub-scene-management.md

16 KiB
Raw Blame History

created path project tags type
2026-05-17 Sources/Dev pbs-hub-scene-management
pbs
pbs-hub
flask
mysql
video-production
scenes
ui
sortablejs
tablet
project-plan

Goal

Extend pbs-hub (the merged successor to pbs-video-manager + pbs-api) to support the full video production lifecycle — not just the post-shoot/publish work the tool covers today. Add pre-production authoring surfaces (outline, treatment, scenes with per-scene scripts), a structured scene/shot list model, and a tablet-friendly Present Mode for shoot day that solves the specific pain of forgetting shots while shooting.

The original animating idea of pbs-hub was a sidecar to Trello — Trello holds the project board, the Hub holds the depth Trello can't (file management, ffmpeg, description building). This extension stays true to that philosophy: Trello can't model "intro scene has three shots, two done, one not." The Hub adds that depth, in the same pattern.

CLI is untouched. Existing post-shoot surfaces (Overview, Publish Check, Desc Build) are untouched. Project Detail navigation shifts from tabs to a persistent card rail (C2 pattern).

Locked Decisions

Schema (all new tables → pbs_automation database)

Project (extended):

  • outline TEXT, nullable — rough story scratch
  • treatment TEXT, nullable — narrative prose, scene-by-scene

ProjectMetadata (new):

  • id PK, project_id FK → projects.id
  • key VARCHAR, value TEXT, sort_order INT
  • Generic key/value to allow new metadata fields via Settings CRUD without schema migrations

ProjectMetadataField (new, Settings-managed):

  • id PK, key VARCHAR, label VARCHAR, sort_order INT
  • Seeded: logline, working_title, tagline

Scene (new):

  • id PK, project_id FK → projects.id, sort_order INT
  • title, purpose, in_shot, background (text fields, freeform)
  • script TEXT — per-scene script (the narrative lives at scene level, not project level)

SceneItem (new — Path B, separate from ChecklistItem):

  • id PK, scene_id FK → scenes.id, sort_order INT
  • label VARCHAR
  • item_type ENUM: shot, reminder
  • is_complete BOOLEAN, created_at TIMESTAMP

DefaultScene (new):

  • Template scenes seeded on pbs init. Same shape as Scene minus project_id.

DefaultSceneItem (new):

  • Template scene items. default_scene_id FK → default_scenes.id. Same shape as SceneItem minus scene_id and is_complete.

Path B rationale: ChecklistItem.category is workflow-stage-shaped (export/wordpress/youtube/instagram/email). Scene items don't have a workflow-stage equivalent. Forcing them into ChecklistItem would either compromise the category column's clear meaning or create silent-leak bugs (every existing ChecklistItem query becomes a future bug site). The duplication cost is bounded: one new model + ~60-80 LOC service module. The new code lives next door, doesn't touch the working publish-check path, and can't poison it.

ChecklistItem and DefaultChecklistItem are UNCHANGED.

Status workflow

Project.status stays free VARCHAR. Adds:

planned → scripted → raw → editing → exported → final → published → archived

All transitions manual. Coexists with reel-flavored statuses (draft / ready / live-matched / live-needs-review) — disambiguated by project_types.name.

Terminology

  • Scene list — new pre-production surface (scenes + scene items)
  • Checklist — existing publish-pipeline surface (unchanged)
  • Outline / Treatment / Script — industry-standard authoring vocabulary
  • Scene / Shot / Shot list — industry-standard production vocabulary
  • Item types — shot (visual capture) and reminder (non-shot task)

UI: Persistent Card Rail + Canvas (C2 pattern)

Project Detail tabs are replaced by a persistent left rail of live status cards, with the selected surface filling the canvas. Rail collapses on tablet for Present Mode.

Rail card order (lifecycle):

Overview / Outline / Treatment / Scenes / Publish Check / Desc Build

Each rail card shows live status, not just a label:

  • Overview — project title, status badge, last activity
  • Outline — first line preview or "empty"
  • Treatment — paragraph count, last edit timestamp
  • Scenes — scene count + mini completion indicator (color-coded per completion state)
  • Publish Check — X of Y complete with progress bar
  • Desc Build — drafted / not started / complete

Surfaces:

  • Overview — existing, unchanged
  • Outline — single freeform markdown field, standard editor
  • Treatment — split-pane: treatment prose on left, running scene title list on right with "Add scene" button and drag-to-reorder. Right pane is a live view of Scene records; edits sync with the Scenes surface
  • Scenes — two modes:
    • Edit Mode (default): full CRUD on scenes (briefing fields, per-scene script) and scene items (label, type, complete, reorder)
    • Present Mode (shoot day): scene strip across top, color-coded per scene completion (gray = empty, red = none complete, amber = partial, green = all complete); focused scene shows briefing fields (read-only) + shot list split above/below the line + X of Y indicator + inline "Add item"; non-sequential scene navigation; shows project title + date for on-camera recording context
  • Publish Check — existing, unchanged
  • Desc Build — existing, unchanged

Drag-drop: SortableJS (CDN, touch-friendly). Used for scene reordering (in Treatment right pane and Scenes Edit Mode) and item reordering (in Scenes Edit Mode).

Pre-shoot handling: Pre-shoot is the first scene of every project, populated with reminder-type items. No separate model or surface. Defaults seeded via DefaultScene + DefaultSceneItem on pbs init.

Scene completion derivation (not stored):

  • Empty scene (no items) → gray
  • Items exist, none complete → red
  • Partial completion → amber
  • All complete → green

Above/below-the-line in the item list driven by is_complete. Single sort_order drives both zones. Un-check pops item back above the line naturally. New items added mid-shoot land at the end of the above-the-line group.

Tests

Bootstrap pytest scaffold (pyproject section, conftest.py, in-memory SQLite fixture) as part of this work. Write tests for the new code: scenes model, scene items, completion derivation, migration smoke tests. Do not backfill tests for existing untested code.

Deploy

Lovebug builds and tests on the dev environment, stops short of deploy. Travis runs deploy via the wordpress-install Ansible repo (wp-i) to staging first, then production. Pre-deployment verification: confirm Phase 5 baseline is live on prod MySQL before this migration runs:

mysql -u pbs_api -p pbs_automation -e 'SHOW TABLES'

If projects, project_types, and platform_posts are present, prod is cut over and this migration adds on top. If not, Phase 5 baseline lands first.

CLI

No CLI changes. No sync_checklist_items() changes — Path B isolates scene items in their own table, so the existing sync mechanism is untouched. Scene-aware sync, if ever needed, is a separate endpoint with its own shape (future enhancement, not v1).

Open Items

These need verification or input before or during implementation:

  • Production MySQL state — confirm Phase 5 baseline tables (projects, project_types, platform_posts) are live on prod before deploying this migration. If not, reconcile first.
  • sql/create_tables.sql cleanup — add a one-line note marking the database housing question (was pbs_automation or pbs_content_hub?) as RESOLVED → pbs_automation. Saves the next reader from hitting the same TBD.
  • Default scene/item seed content — implementation agent picks reasonable defaults for DefaultScene + DefaultSceneItem (e.g., a "Prep" scene with charge-batteries / format-cards reminders). Fully editable via CRUD after init.
  • Migration files location — recommend sql/migrations/NNN_<description>.sql with numbered files since there's no Alembic. This work adds the first such files; future schema changes follow the pattern.

Phases

Phase 1 — Schema migration

One numbered migration file in sql/migrations/ that adds all new tables and columns in a single transaction. Targets pbs_automation database.

  • ALTER TABLE projects ADD COLUMN outline TEXT DEFAULT NULL
  • ALTER TABLE projects ADD COLUMN treatment TEXT DEFAULT NULL
  • CREATE TABLE project_metadata (...)
  • CREATE TABLE project_metadata_fields (...) + seed logline, working_title, tagline
  • CREATE TABLE scenes (...)
  • CREATE TABLE scene_items (...)
  • CREATE TABLE default_scenes (...) + seed reasonable defaults
  • CREATE TABLE default_scene_items (...) + seed reasonable defaults
  • Bootstrap pytest scaffold + first migration smoke test
  • Update sql/create_tables.sql to match (so fresh deploys are consistent)

Phase 2 — Rail framework

Replace the existing 3-tab implementation in project_detail.html with the persistent card rail + canvas pattern. Existing surfaces (Overview, Publish Check, Desc Build) become canvas-rendered with placeholder rail cards.

  • Rail component (Jinja partial), styled with Tailwind
  • Rail card with live-status props (label, status indicator, click handler)
  • Canvas slot in Project Detail layout
  • Wire existing surfaces (Overview / Publish Check / Desc Build) into canvas
  • Active card visual treatment
  • Rail collapse mechanism (for Present Mode later)
  • Verify /pbscontenthub URL prefix awareness in new routes

Phase 3 — Outline surface (end-to-end)

Simplest of the new surfaces. Validates the rail-card live-status pattern with real data.

  • Service method to read/write Project.outline
  • API endpoint
  • Route + template (single textarea, autosave or save button)
  • Rail card shows first-line preview or "empty"
  • Tests

Phase 4 — Treatment surface (end-to-end)

Split-pane layout. Right pane is a live Scene title list with reorder + "Add scene." Requires Scene CRUD basics in place but not the full Scenes Edit Mode.

  • Scene model + basic service (create, read, update title, delete, reorder)
  • API endpoints for scene list management
  • Treatment route + split-pane template
  • SortableJS integration for scene reorder in right pane
  • Rail card shows paragraph count + last edit timestamp
  • Tests

Phase 5 — Scenes surface (Edit Mode first)

Build out full scene CRUD with briefing fields, per-scene script, and scene items (the scene list). Edit Mode only — no Present Mode yet.

  • Scene briefing fields editor (purpose, in_shot, background)
  • Per-scene script editor (textarea, autosave)
  • SceneItem service + API endpoints (CRUD, toggle, reorder, set type)
  • Scene Edit Mode template — scene selector, briefing form, script editor, item list with above/below-the-line split
  • Item type indicators (shot vs reminder, visually distinguished)
  • Add/remove items inline
  • SortableJS for item reorder
  • Rail card shows scene count + completion summary
  • Tests

Phase 6 — Scenes surface (Present Mode)

Tablet-optimized shoot-day view. Layered on top of the Edit Mode infrastructure.

  • Mode toggle ("Present" button in Edit Mode, "Edit" button / back in Present Mode)
  • Scene strip component — horizontal banner of color-coded chips (gray/red/amber/green per scene completion state), 44px+ tap targets, horizontal scroll if needed
  • Active chip treatment (border or background accent)
  • Focused scene view — project title + date header, briefing fields (read-only), item list with above/below-the-line, X of Y indicator
  • Inline "Add item" on focused scene
  • Item toggle works directly in Present Mode (taps the action, no mode switch)
  • Rail collapses on Present Mode entry
  • Tests

Phase 7 — Metadata fields

Project metadata key/value system with Settings CRUD for adding new fields.

  • ProjectMetadata service + API
  • ProjectMetadataField management in Settings
  • Metadata display + edit on Overview surface (or wherever fits best — implementation call)
  • Tests

Phase 8 — Status workflow

Small, slots anywhere after schema is live.

  • Add planned and scripted to status options
  • Status dropdown / picker UI on Overview
  • Document status semantics (planned = idea, scripted = ready to shoot, raw = footage exists)

Notes

Cross-references

  • Existing codebase: pbs-video-manager (internally branded "PBS Hub"), at /opt/projects/pbs/pbs-video-manager, git remote git-real-projects-pvm:trucktrav/pbs-video-manager.git, branch master
  • Phase 5 architecture: content-hub-phase5-architecture
  • Phase 5 schema: content-hub-database-schema
  • Phase 5 planning: content-hub-phase5-planning
  • Original master plan: instagram-automation-content-hub-plan

Design philosophy notes

  • Sidecar to Trello philosophy preserved. Trello is the project board, the Hub is where the work lives. New pre-production surfaces (outline, treatment, scenes, scene list) are more work that lives in the Hub — same philosophy, more depth. Not a different pattern grafted on.
  • Custom is appropriate. Off-the-shelf tools can't do "scene strip color-coded by completion across multiple scenes during a tablet-on-the-counter shoot." That's why this exists. The customization solves a specific pain (forgetting shots) that Trello, Notion, etc. can't.
  • Function over polish for v1. Visual polish ("modern and sexy") is deferred to a follow-on project. Tablet-friendly drag-drop is the one place where polish and function overlap — bad drag-drop on a tablet is bad function. SortableJS handles that.

Flagged for plan readers

  • platform_posts n8n lookup chain unaffected. The comment-reply automation path (platform_posts → projects → pbs_recipes) is untouched. Schema additions are purely additive to projects. No risk to existing automation.
  • Status vocabulary coexistence. projects.status holds both reel-flavored values (draft / ready / live-matched / live-needs-review) and video-flavored values (planned → scripted → ... → archived). Disambiguated by project_types.name. The eventual status-as-lookup-table refactor (when Trello integration lands) needs to accommodate both.
  • Rail vs. intra-page filter chips. Project Detail now uses the rail nav. Library/Settings keep their existing filter chip pattern (different metaphor, both stay). Future polish pass may unify them — flagged below.

Out of scope (deferred / future)

  • Auto-generation of scenes from treatment (structured parsing of treatment headings into Scene records). Manual handoff for v1.
  • Take tracking / version notes (the active "clapper" with per-take metadata).
  • Quick-action affordances on rail cards (e.g., one-tap to Present Mode from the Scenes card without entering Edit Mode first).
  • Visual polish pass. Typography, motion, refined cards, dark mode, color-change animations on scene strip chips, progress dots inside chips, etc. Its own future project.
  • Jinja macro extraction. Status pill, card, badge components. Done as part of the polish pass, coherently across old and new surfaces.
  • Rail vs. filter chip pattern unification. Done as part of the polish pass.
  • Inline briefing editing in Present Mode. v1 is read-only in Present Mode; switch to Edit Mode for changes.
  • Scene-aware CLI sync. If push/pull ever needs to round-trip scene data, build a separate endpoint with its own shape. Not v1.
  • Unified "everything checkable" aggregation. If a project-wide progress meter across publish items + scene items is wanted, it's a service-layer UNION aggregator. Not v1; flagged so it doesn't drive premature data-model fusion.
  • From existing out-of-scope list (unchanged): YouTube API integration, thumbnail management, multi-user roles, notification system.