Workshed, Loom & Ribbon Migration Strategy
Overview
This document describes the migration strategy for the program scheduling system from the POC backdoor (React) to the production admin interface (vanilla JS SPA). The system uses a textile metaphor to describe the three architectural layers that transform program definitions into viewable daily schedules.
The Metaphor
The scheduling system follows a weaving metaphor that maps naturally to the data flow:
| Layer | Metaphor | Role | Description |
|---|---|---|---|
| Workshed | Planning | Program Creator & Settings | Where the program is designed — templates, rules, participants, staff, and vehicles |
| Loom | Weaving | Backend Engine | The engine that takes the plan and weaves it into concrete daily instances |
| Ribbon | Viewing | Roster & Schedule | The finished output — viewable, navigable daily rosters and schedules |
Workshed (Design) → Loom (Generate) → Ribbon (View)
Plan the Weave the See the
program instances roster
Architecture Mapping
POC to Production Component Map
| Concept | POC (backdoor) | Target (admin) | Backend Route |
|---|---|---|---|
| Workshed (Wizard) | ProgramTemplateWizard.jsx | page_prog_create.html | templates.js |
| Workshed (Editor) | N/A | prog_dashboard.html | templates.js |
| Command Center (Live) | N/A | prog_timeline.html | instances.js |
| Command Center (Attn) | N/A | prog_cancellations.html | enrollments.js |
| Command Center (Res) | N/A | prog_resources.html | resources.js |
| Loom | /finalize API | page_schedule.html | loom.js, util_syncRethread.js |
| Ribbon | Roster.jsx | page_roster.html | roster.js |
Several target pages (Editor, Command Center views) have no POC equivalent — they are net-new functionality in the admin interface.
Migration Status
Completed Work
| Component | Status | Details |
|---|---|---|
| Database migration | Done | Migrated from rules_* tables to program_templates schema |
| Backend route ports | Done | All routes ported to routes_v1p (API v1 path) |
| Frontend wizard | Done | Full program creation wizard with 6 tabs |
| Command Center layout | Done | Unified layout for Live, Attention, and Resources views |
Wizard Tab Structure
The program creation wizard (page_prog_create.html) contains six configuration tabs:
| Tab | Purpose |
|---|---|
| Details | Program name, description, category, and metadata |
| Venue | Location selection and facility configuration |
| Time Slots | Day-of-week scheduling, start/end times, recurrence |
| Participants | Enrolment rules, capacity limits, participant selection |
| Staff | Staff assignment rules, required qualifications, ratios |
| Vehicles | Vehicle allocation, accessibility requirements, transport rules |
Settings Architecture
The system uses a 3-tier settings hierarchy where each level has a distinct scope and storage location.
| Page | Scope | Storage |
|---|---|---|
page_settings.html | User — individual preferences | admin_profiles.* |
page_app-settings.html | Admin App — application-wide defaults | admin.app_settings |
page_loom-settings.html | Organisation — system-wide scheduling rules | admin.app_settings |
Loom Settings
The Loom settings page (page_loom-settings.html) manages organisation-level scheduling parameters stored in the loom_shift_settings JSON column within admin.app_settings.
Key configuration values:
{
"loom_shift_settings": {
"threshold_staff": 2,
"threshold_vehicle": 1
}
}
| Setting | Type | Description |
|---|---|---|
threshold_staff | integer | Minimum number of staff required before the Loom will generate a shift instance |
threshold_vehicle | integer | Minimum number of vehicles required before the Loom will generate a transport instance |
These thresholds prevent the Loom from generating incomplete or understaffed program instances.
Data Flow
From Design to Roster
1. Workshed: Admin creates program template via wizard
↓
2. Template saved to program_templates with all rules
↓
3. Loom: /finalize API triggered (manual or scheduled)
↓
4. Loom reads template rules + settings thresholds
↓
5. Loom generates concrete daily instances
↓
6. util_syncRethread.js handles conflict resolution
↓
7. Ribbon: page_roster.html renders the woven schedule
Sync and Rethreading
The util_syncRethread.js utility handles:
- Detecting conflicts between generated instances and manual overrides
- Re-weaving affected instances when template rules change
- Maintaining referential integrity between enrollments and instances
Backend Route Files
All scheduling backend routes reside in backend/routes_v1p/:
| File | Responsibility |
|---|---|
templates.js | Program template CRUD and wizard data |
instances.js | Generated instance management (Command Center Live) |
enrollments.js | Participant enrolment and cancellation tracking |
resources.js | Resource allocation and availability |
loom.js | Instance generation engine |
util_syncRethread.js | Conflict resolution and rethreading utility |
roster.js | Roster view data aggregation |
Summary
The Workshed–Loom–Ribbon migration moves program scheduling from the React-based POC into the production admin SPA. The database schema has been migrated, backend routes ported, and the frontend wizard completed with a unified Command Center layout. The 3-tier settings architecture ensures that scheduling thresholds and preferences are configurable at user, application, and organisation levels, with the Loom engine respecting all tiers when weaving program templates into daily roster reality.