PRDs · prds/02-flow-board-companion-prd.md Docs Home

PRD 02: Flows, Boards, Companions, Forms, and Publishing

Problem Statement

The old platform treats flows, boards, companions, forms, sessions, submissions, folders, collections, and protection as connected product concepts. Studio API owns the strongest backend CRUD shape. Picasso FE owns the strongest editor and share surfaces. Zweistein owns board/chat navigation patterns.

The new platform must preserve this product model without carrying forward confusing naming, duplicated listing flags, or weak public upload behavior.

Solution

Create a unified flow/board/companion domain that supports:

creating, listing, editing, cloning, transferring, archiving, and deleting flows;
representing flows as boards, companions, or both;
folders, tags, collections, favorites, recent/popular items;
draft and published versions;
results and session history;
forms and form submissions;
sharing, embedding, protection, and public runtime access.

Legacy Source References

studio-api-reference/src/database/entities/flow.entity.ts
studio-api-reference/src/database/entities/flow-history.entity.ts
studio-api-reference/src/database/entities/flow-protection.entity.ts
studio-api-reference/src/modules/studio/modules/flow/
studio-api-reference/src/modules/studio/modules/form-submission/
studio-api-reference/src/modules/houston/modules/form-submission/
picasso-fe-reference/apps/picasso-editor/src/entities/flow/
picasso-fe-reference/apps/picasso-editor/src/pages/flow-share/
picasso-fe-reference/apps/picasso-editor/src/pages/flow-results/
zweistein-reference/admin/src/pages_chat/boards/
zweistein-reference/admin/src/pages_chat/collections/

User Stories

As a creator, I want to create a new board or companion, so that I can start a new interactive experience.
As a creator, I want to list my boards, org boards, companions, and collections, so that I can find work quickly.
As a creator, I want folders and tags, so that large workspaces stay organized.
As a creator, I want to clone a flow, so that I can reuse a working structure.
As an org admin, I want to transfer ownership, so that flows can move between users or org contexts safely.
As a creator, I want draft and published states, so that I can change a flow without breaking the public version.
As a creator, I want publish history, so that I can inspect previous versions.
As a creator, I want rollback or restore from a previous version, so that mistakes can be corrected.
As a creator, I want flow share settings, so that I can publish as link, embed, or protected companion.
As a creator, I want flow results, so that I can see sessions, submissions, files, and completion data.
As an end user, I want public forms to submit reliably, so that published companions can collect data.
As an end user, I want upload fields to accept supported media safely, so that I can complete rich forms.
As an admin, I want form submissions tenant-scoped, so that one customer cannot access another customer's data.
As a creator, I want reusable node templates, so that common flow structures can be reused.
As an operator, I want soft delete and audit history, so that production mistakes can be recovered.

Functional Requirements

Core Flow Model

Support a durable flow record with title, description, slug, owner, tenant/org, metadata, status, and type.
Replace ambiguous dual listing booleans with a single visibility model.
Support board, companion, and combined board/companion presentation modes.
Keep JSONB-like flexible graph/content data, but define versioned schemas for it.

CRUD and Organization

Create, update, read, delete, archive, restore, clone, move, and transfer flows.
List flows by owner, org, folder, collection, tag, favorite, recent, and popularity.
Support folder hierarchy and collection membership.
Support tags and visual categorization.

Publishing and Versioning

Maintain separate draft and published versions.
Publishing creates immutable version records.
The current published version must be addressable.
Version history must survive soft deletion unless explicitly purged.
Rollback must create a new draft or publish event rather than mutating old history.

Protection and Sharing

Support public, password, external-user, and org-only access.
Support embed links and share links.
Support companion access checks before runtime data loads.
Record access attempts and public session starts.

Forms and Submissions

Support form definitions inside flows.
Support form field types from Houston runtime: text, long text, number, email, phone, checkboxes, dropdown, date, image, file, video, audio, GPS, live capture, barcode where available.
Store submissions with flow, form, session, user/external user, and tenant context.
Support file attachments with safe upload flow.
Support webhook/email/integration actions after submission.

Non-Functional Requirements

Public submission endpoints must be rate-limited and session-scoped.
Uploads must validate size, type, and session ownership server-side.
Deletion must not destroy audit history by default.
Flow slugs must be unique and stable.
Queries must be indexed for tenant, owner, status, slug, and creation/update dates.

Implementation Decisions

Use Studio API flow entities as the product data starting point.
Split core CRUD, publishing, sharing, protection, forms, and admin transfer into separate modules.
Keep flow protection separate from the flow core record.
Add idempotency for form submission and webhook side effects.
Add a migration inventory before any old production data is imported.

Testing Decisions

API-test flow CRUD and tenant scoping.
API-test publish, version history, and rollback.
API-test protected access modes.
Browser-test board/companion create, edit, publish, share, and result views.
Abuse-test public forms and file upload endpoints.

Out of Scope

Choosing final UI design for every editor panel.
Migrating production data before the schema is approved.