Skip to main content

Phase 14: Studio Enhancements

Objective: Add advanced features to Studio for improved developer experience, including live preview, sandbox mode, and hot reload.

Prerequisites: Phase 07 (Studio core) must be complete.

1. Live Preview & Sandbox Mode​

1.1 Sandbox Architecture​

[!IMPORTANT] Sandbox = Local Development Environment The Sandbox runs on the same machine where Studio is running. It is NOT a separate cloud environment. This enables citizen developers to design, test, and iterate locally before committing to Git.

Citizen Developer Workflow:

┌─────────────────────────────────────────────────────────────────────┐
│  LOCAL MACHINE (Developer or Citizen)                               │
│                                                                     │
│   1. Studio UI          2. Sandbox              3. Git              │
│   ┌──────────────┐     ┌──────────────┐       ┌──────────────┐      │
│   │ Design       │ ──► │ Test with    │ ──►   │ Commit &     │      │
│   │ DocType      │     │ mock data    │       │ Push         │      │
│   └──────────────┘     └──────────────┘       └──────────────┘      │
│                                                      │              │
└──────────────────────────────────────────────────────│──────────────┘
                                                       ▼
                                              CI/CD → Production

[!WARNING] Collaborative Environments: Conflict Risk When multiple citizens work on the same repo/branch, local sandboxes can cause Git conflicts. The sandbox is best suited for solo work or feature branches.

Alternatives for Collaborative Teams:

ApproachHow It WorksBest For
Feature BranchesEach citizen works on their own branch → PR to mergeSmall teams (2-5)
Gitpod/CodespacesEach citizen gets isolated cloud dev environmentLarger teams
Assigned ModulesCitizens own specific modules/apps, no overlapEnterprise
Trunk-Based + Fast CIAll push to main, CI deploys in <2 minMature teams
Studio Cloud ModeHosted Studio with workspace isolationSaaS offering

1.2 Branch Selector​

  • Add branch selector to Studio UI
  • Allow switching between branches
  • Show current branch in header
  • Warn before switching with unsaved changes

1.3 Preview Tab Implementation​

  • Add "Preview" tab to DocType editor
  • Toggle between "Schema Editor" and "Sandbox"
  • Preserve editor state when switching tabs

1.4 Mock Data Generation​

  • Install @faker-js/faker for mock data
  • Create mock data generator service:
    • Generate data based on field types:
      • String → faker.lorem.words()
      • Number → faker.number.int()
      • Date → faker.date.recent()
      • Email → faker.internet.email()
      • Link → Random ID from related DocType
    • Respect field constraints (min, max, required)
    • Generate 5-100 mock records

1.5 Form Preview​

  • Render AutoForm component with mock document
  • Show validation errors for required fields
  • Allow editing mock data
  • Show save/cancel buttons (non-functional)

1.6 List Preview​

  • Render AutoTable component with mock rows
  • Show 5-10 rows by default
  • Add pagination controls
  • Show filters and search (non-functional)

1.7 In-Memory Schema Source​

  • Use in-memory schema (not saved file)
  • Allow instant preview without saving
  • Update preview on field changes
  • Debounce preview updates (500ms)

2. Interactive Sandbox (CRUD Simulation)​

[!NOTE] Why Mock Data? Sandbox uses mock data so citizens can test the full UX (forms, lists, validation) without needing a database setup. Once satisfied, they commit the code and deploy to an environment with real data.

2.1 In-Memory Data Store​

  • Create in-memory store for mock documents
  • Store per DocType (isolated)
  • Reset on page reload
  • Support up to 1000 mock records

2.2 CRUD Operations​

  • Create: Add new mock document
    • Validate required fields
    • Show validation errors
    • Add to in-memory store
    • Show success message
  • Read: View mock document details
    • Render form in read-only mode
    • Show all field values
  • Update: Edit existing mock document
    • Validate changes
    • Update in-memory store
    • Show success message
  • Delete: Remove mock document
    • Show confirmation dialog
    • Remove from in-memory store
    • Show success message

2.3 List Operations​

  • List (Few): Show 5 rows
    • Test basic list rendering
    • Test row actions (edit, delete)
  • List (Many): Generate 100+ rows
    • Test pagination
    • Test performance
    • Test scroll behavior

2.4 Filter & Search​

  • Implement client-side filtering
  • Implement client-side search
  • Show filtered results count
  • Test filter combinations

2.5 Validation Testing​

  • Submit form with missing required fields
  • Show field-level error messages
  • Show form-level error summary
  • Test custom validation rules

3. Local Hot Reload (Advanced)​

[!NOTE] Optional Enhancement For users who want to test with a real local database instead of mock data.

3.1 Prerequisites​

  • Local Postgres/SQLite running
  • m start running on localhost
  • Database connection configured

3.2 File Watcher Setup​

  • Install chokidar for file watching
  • Watch DocType files for changes
  • Debounce file change events (1s)
  • Ignore temporary files (.swp, .tmp)

3.3 Schema Sync Trigger​

  • Detect DocType file changes
  • Parse updated DocType
  • Generate schema diff
  • Send sync request to backend

3.4 Backend Schema Sync Endpoint​

  • Create POST /studio/api/sync-schema
  • Accept DocType schema
  • Generate SQLAlchemy table
  • Run ALTER TABLE if table exists
  • Create table if new
  • Return sync status

3.5 Real CRUD Operations​

  • Switch from mock data to real API calls
  • Use Framework M API (/api/v1/{doctype})
  • Show real validation errors
  • Persist data to local database

3.6 Hot Reload UI​

  • Add "Hot Reload" toggle in Studio settings
  • Show connection status indicator
  • Show sync progress
  • Show sync errors

4. Advanced Preview Features​

4.1 Responsive Preview​

  • Add device size selector:
    • Desktop (1920px)
    • Tablet (768px)
    • Mobile (375px)
  • Resize preview iframe
  • Test responsive layouts

4.2 Dark Mode Preview​

  • Add dark mode toggle in preview
  • Test components in both modes
  • Ensure contrast compliance

4.3 Accessibility Preview​

  • Add accessibility checker
  • Show WCAG violations
  • Highlight problematic elements
  • Suggest fixes

4.4 Performance Preview​

  • Show render time
  • Show component count
  • Show bundle size estimate
  • Warn on performance issues

5. Collaboration Features​

5.1 Real-Time Collaboration (Optional)​

  • Add WebSocket support
  • Show other users editing same DocType
  • Show cursor positions
  • Implement operational transformation (OT)

5.2 Change Tracking​

  • Show unsaved changes indicator
  • Show diff view (before/after)
  • Allow reverting changes
  • Show change history

5.3 Comments & Annotations​

  • Add comment threads on fields
  • Show unresolved comments count
  • Allow @mentions
  • Integrate with Git PR comments

6. Schema Change Detection (Developer Guardrails)​

[!NOTE] RFC: Schema Change Detection & Developer Guardrails

This feature lives in Studio (devtools), NOT in framework-m runtime. Production containers stay minimal.

  • Implement SchemaAnalyzer class:

    • Compare Pydantic models with current DB schema
    • Classify changes: SAFE, WARNING, DANGEROUS
    • Generate actionable messages with docs links

  • CLI integration (m migrate:create):

    • Show analysis before generating migration
    • Block on DANGEROUS changes (cannot auto-generate)
    • Warn on WARNING changes (require --force)
    • Link to migration pattern documentation

  • Studio UI integration:

    • Show warnings when saving DocType
    • Recommend safer alternatives (nullable, defaults)
    • "Save Anyway" escape hatch

7. DocType Discovery & Scanning​

[!NOTE] RFC: DocType Discovery & Scanning

Deterministic, fast AST-based scanning. No caching. Handles 1000s of DocTypes in <1s.

  • Optimize DocType scanning performance
  • Implement AST-based parsing
  • Handle large codebases (1000+ DocTypes)
  • Add caching strategy for development mode

9. Desk View Configuration​

  • Workspace Configurator:

    • UI to creating/managing workspaces (Sidebar items)
    • Assign DocTypes to workspaces
    • Define workspace shortcuts and charts
    • Configure sidebar ordering and visibility
    • Role-based workspace access permissions

  • View Builders:

    • Kanban View configurator (columns, cards)
    • Calendar View configurator (start/end fields)
    • Gantt View configurator (dependencies)
    • Map View configurator (geo fields)

10. Portal Builder (Puck Integration)​

[!NOTE] Puck Integration Instead of building a custom visual builder, we will integrate Puck directly into Studio. Puck is a React-native, open-source visual editor perfect for this use case.

  • Puck Integration:

    • Create PuckEditor wrapper component in Studio
    • Implement StorageAdapter to save pages as WebPage DocType
    • Implement ViewAdapter to render published pages

  • Component Bridge (The "Design System"):

    • Map Framework M UI components to Puck Config
    • Create Hero component (Title, Subtitle, Image, CTA)
    • Create CardGrid component (Dynamic List)
    • Create Form component (Connect to DocType)
    • Create Login component

  • Data Binding (Advanced):

    • Create FrameworkMDataProvider for Puck "Root"
    • Fetch data from /api/v1/content/:slug
    • Pass data into Puck zones/components

11. Testing​

11.1 Unit Tests​

  • Test mock data generator
  • Test in-memory CRUD operations
  • Test file watcher
  • Test schema sync logic

11.2 Integration Tests​

  • Test full sandbox workflow
  • Test hot reload with real database
  • Test preview rendering
  • Test collaboration features

12. Validation Checklist​

Before considering Phase 14 complete, verify:

  • Sandbox preview works for all field types
  • Mock data generation is realistic
  • CRUD operations work in sandbox
  • Hot reload syncs schema correctly
  • Preview is responsive and accessible
  • File watcher is reliable

Success Metrics​

Before (Phase 07)​

  • Static code generation
  • No preview capability
  • Manual testing required

After (Phase 14)​

  • Live preview with mock data
  • Interactive sandbox for UX testing
  • Hot reload for rapid iteration
  • Collaboration features for teams
  • Citizen developers can build without coding

Notes​

  • Mock data is sufficient for most use cases
  • Hot reload is optional - adds complexity
  • Collaboration is advanced - defer if not needed
  • Focus on preview quality - make it feel real