switchboard/core
Archived
1
0
Fork 0
Code Issues Pull Requests Actions Releases 9 Wiki Activity

Roadmap restructure v038 v039 (#231)

Browse Source 
Co-authored-by: gobha <jasafpro@gmail.com>
Co-committed-by: gobha <jasafpro@gmail.com>
This commit is contained in:
gobha
2026-03-24 20:35:13 +00:00
committed by xcaliber
parent 3a4afea7f2
commit 54ceeb4299
2 changed files with 269 additions and 108 deletions
Download Patch File Download Diff File Expand all files Collapse all files

238
docs/Workflow/ROADMAP-0.38.md → docs/Workflow/ROADMAP-0.39.md
View File

@@ -1,11 +1,56 @@
# ROADMAP-0.38 — Workflow Product Maturity
# ROADMAP-0.39 — Workflow Product Maturity
Everything deferred from v0.37.15 plus what the MVP gate actually
requires: "Team admins build workflows **visually**."
v0.37.15 delivers the plumbing — cancel, unclaim, reassign, stage CRUD
in the FE, queue views. This series builds the product on top of that
plumbing.
in the FE, queue views. v0.38.x delivers the extension infrastructure
(multi-file Starlark, connections, libraries) that dynamic workflows
depend on. This series builds the product on top of both foundations.
**Two workflow camps:**
- **Simple workflows** — static stages, fixed forms, declarative rules.
Team admins author these visually.
- **Dynamic workflows** — Starlark-driven branching, API-backed
pre-screening, tailored data collection based on customer context.
Developers author these for team admins to deploy.
A single workflow graph can mix simple, dynamic, and automated stages.
---
## Stage Graph Architecture
Three node types in the workflow graph:
| Node Type | UI | Author | Example |
|-----------|-----|--------|---------|
| **Simple** | Declarative form, fixed fields, built-in renderer | Team admin (form builder) | "Collect name, email, issue type" |
| **Dynamic** | Starlark hook returns form config/routing at runtime | Developer | "Check CRM, skip fields we already know, route by customer tier" |
| **Automated** | No UI — Starlark execution only | Developer | "Call external API, transform data, pre-screen eligibility" |
**Branching:** Layered approach — declarative rules for simple cases
(`if customer.type == enterprise → stage A`), optional Starlark hook
for complex branching. Progressive complexity: team admins use rules,
developers add hooks when needed.
**Visitor surface:** Standalone portal (branded URL, no chat chrome).
The portal renders whatever the current stage dictates — it doesn't
care whether the stage config came from static definition or Starlark.
### Example Mixed Workflow
```
[Pre-screen (automated: CRM lookup via Starlark)]
│
[Branch: known customer?]
yes → [Verify Info (simple: pre-filled form)]
no → [Full Intake (dynamic: Starlark picks fields)]
│
[Review (simple stage)]
│
[Provision (automated: external API call)]
```
---
@@ -13,17 +58,21 @@ plumbing.
```
v0.37.15 Workflow Ownership & Lifecycle (plumbing)
v0.37.16 Projects Surface
v0.37.17 Debug / Model Surface
v0.37.16–18 Projects, Workspaces, Debug surfaces
v0.37.19 Tag ("UI Complete")
│
── 0.37 tag ──
v0.38.0–.4 Extension Continuation (Starlark, connections, libraries, git-board)
│
v0.38.0 Form Builder ← team admins stop writing JSON
v0.38.1 Stage Reorder + Bulk Ops ← queue management at scale
v0.38.2 SLA Alerting ← stale queues self-report
v0.38.3 Visitor Experience ← the public face
v0.38.4 Workflow Templates + Clone ← reuse across teams
v0.38.5 Analytics Dashboard ← throughput, bottlenecks, SLA compliance
── 0.38 tag ──
│
v0.39.0 Stage Graph Engine + Form Builder ← graph execution + visual editing
v0.39.1 Stage Reorder + Bulk Ops ← queue management at scale
v0.39.2 SLA Alerting ← stale queues self-report
v0.39.3 Visitor Portal ← standalone branded experience
v0.39.4 Workflow Templates + Clone ← reuse across teams
v0.39.5 Analytics Dashboard ← throughput, bottlenecks, SLA compliance
│
v0.40.x Polish (bug hunt, dead code, stabilize)
│
─ ─ ─ MVP v0.50.0 gate ─ ─ ─
```
@@ -33,23 +82,65 @@ v0.38.5 Analytics Dashboard ← throughput, bottlenecks, SLA compl
| Milestone | Gate | Meaning |
|-----------|------|---------|
| v0.37 tag | **UI Complete** | Every platform capability has a surface; no features require raw API calls |
| v0.38.0 | **Self-service** | A team admin can build a complete workflow without touching JSON or asking a global admin |
| v0.38.2 | **Operational** | Stale work surfaces automatically; team admins can manage queues without monitoring dashboards |
| v0.38.5 | **Measurable** | Team leads can answer "how long does stage X take" and "where are we bottlenecked" |
| v0.38 tag | **Extensible** | Extensions can load modules, manage connections, and compose libraries; git-board proves it |
| v0.39.0 | **Self-service** | Team admins build simple workflows visually; developers can add dynamic stages |
| v0.39.2 | **Operational** | Stale work surfaces automatically; team admins can manage queues without monitoring dashboards |
| v0.39.5 | **Measurable** | Team leads can answer "how long does stage X take" and "where are we bottlenecked" |
---
## v0.38.0 — Form Builder
## v0.39.0 — Stage Graph Engine + Form Builder
**The foundational version.** Two deliverables:
### 1. Stage Graph Engine
The workflow execution engine gains awareness of node types. Each stage
in the workflow definition includes a `stage_type` field:
```go
// Stage model additions:
type StageType string
const (
StageSimple StageType = "simple" // declarative form, built-in renderer
StageDynamic StageType = "dynamic" // Starlark hook returns form/routing
StageAutomated StageType = "automated" // no UI, Starlark only
)
// Branching rule (declarative):
type BranchRule struct {
Field string `json:"field"` // form field key or context var
Op string `json:"op"` // eq, neq, gt, lt, contains, exists
Value any `json:"value"` // comparison value
NextStage string `json:"next_stage"` // stage ID to route to
}
// Stage additions:
type Stage struct {
// ... existing fields ...
StageType StageType `json:"stage_type"`
BranchRules []BranchRule `json:"branch_rules,omitempty"` // declarative
StarlarkHook string `json:"starlark_hook,omitempty"` // package:function
}
```
The engine evaluates branch rules first; if no rule matches and a
Starlark hook is configured, it calls the hook. Default fallback is
next ordinal (existing behavior).
For automated stages, the engine calls the Starlark hook immediately
on entry and auto-advances when it returns.
### 2. Form Builder
**The single biggest gap.** `form_template` is currently raw JSON in a
textarea. The MVP gate says "build workflows visually" — this is the
make-or-break.
### Scope
A visual form builder embedded in the stage editor (E2 from the .15
design). Not a standalone surface — it's a panel that opens when you
click "Edit Form" on a `form_only` or `form_chat` stage.
click "Edit Form" on a `simple` or `form_chat` stage.
### Fields supported (matching existing TypedFormTemplate)
@@ -87,7 +178,6 @@ function FormBuilder({ initial, onSave, onCancel }) {
required: false,
};
if (useFieldsets && targetFieldset !== undefined) {
// Add to specific fieldset
setFieldsets(fs => fs.map((f, i) =>
i === targetFieldset ? { ...f, fields: [...f.fields, field] } : f
));
@@ -209,27 +299,24 @@ function FieldEditor({ field, onChange, onRemove, allFields }) {
}
```
### BE changes
None. The form builder is pure FE — it produces the same
`TypedFormTemplate` JSON that already exists. The BE validation
in `models/workflow.go` is unchanged.
### Deliverables
| File | What |
|------|------|
| `server/models/workflow.go` | `StageType`, `BranchRule` types; stage model additions |
| `server/engine/graph.go` | Graph execution: branch rules → Starlark hook → ordinal fallback |
| `server/engine/automated.go` | Automated stage runner (call hook, auto-advance) |
| `src/js/sw/components/form-builder/index.js` | FormBuilder root |
| `src/js/sw/components/form-builder/field-editor.js` | FieldEditor, type-specific validators |
| `src/js/sw/components/form-builder/fieldset-editor.js` | Fieldset grouping |
| `src/js/sw/components/form-builder/condition-editor.js` | Conditional visibility |
| `src/js/sw/components/form-builder/preview.js` | Live form preview |
| `src/css/form-builder.css` | Styles |
| Integration into StageEditor (E2 from .15) | "Edit Form" button opens builder |
| Integration into StageEditor (E2 from .15) | "Edit Form" button opens builder; stage type picker |
---
## v0.38.1 — Stage Reorder + Bulk Ops
## v0.39.1 — Stage Reorder + Bulk Ops
### Stage drag-and-drop
@@ -297,7 +384,7 @@ patch. YAGNI for now.
---
## v0.38.2 — SLA Alerting
## v0.39.2 — SLA Alerting
The monitor already computes `sla_breached`. This version makes it
proactive instead of requiring someone to check the dashboard.
@@ -340,31 +427,37 @@ The queue items (E1, E4) already render `sla_breached` badges. Add:
---
## v0.38.3 — Visitor Experience
## v0.39.3 — Visitor Portal
The visitor currently gets a raw workflow surface. After .15 they get
a terminal screen (E5) when their stages are done. This version makes
the visitor experience feel like a product.
The visitor currently gets a raw workflow surface embedded in the
app shell. This version delivers a **standalone branded portal** —
a dedicated URL with no chat chrome, optimized for the visitor
experience.
### Scope
1. **Branded entry page** — the workflow landing page already supports
1. **Standalone portal surface** — `/w/:id/:slug` renders a
full-page portal outside the app shell. No sidebar, no user menu,
no chat chrome. The portal renders the current stage's form
(simple or dynamic) and handles stage transitions.
2. **Branded entry page** — the workflow landing page already supports
branding (`accent_color`, `logo_url`, `tagline`). Extend with:
- Custom welcome text (markdown)
- Background image/gradient
- "Powered by" toggle (hide/show Switchboard branding)
2. **Progress indicator** — visitor sees "Step 1 of N" for their
3. **Progress indicator** — visitor sees "Step 1 of N" for their
visible stages only. Internal team stages are invisible. The
progress bar counts only stages where the visitor is the audience.
3. **Email notifications** — optional. When configured on the workflow:
4. **Email notifications** — optional. When configured on the workflow:
- Collect email at stage 0 (or extract from form data)
- Send "request received" confirmation
- Send "your request is complete" when workflow completes
- No notifications for internal stage transitions
4. **Session resume** — visitor who closes the browser can return to
5. **Session resume** — visitor who closes the browser can return to
`/w/:id/:slug` and resume where they left off. Already partially
implemented via `sb_session` cookie. Polish the UX: show "Welcome
back, pick up where you left off" instead of starting fresh.
@@ -401,16 +494,15 @@ the workflow editor with a hint.
/**
* VisitorProgress — step indicator for visitor-facing stages
*
* Mount: workflow surface, above the stage content
* Mount: workflow portal, above the stage content
* Only counts stages where audience = visitor.
*/
function VisitorProgress({ stages, currentStage }) {
// Filter to visitor-facing stages only
const visitorStages = stages.filter(s => !s.assignment_team_id);
const visitorIndex = visitorStages.findIndex(s => s.ordinal === currentStage);
const total = visitorStages.length;
if (total <= 1) return null; // Single stage = no progress bar
if (total <= 1) return null;
return (
<div className="visitor-progress">
@@ -431,7 +523,7 @@ function VisitorProgress({ stages, currentStage }) {
---
## v0.38.4 — Workflow Templates + Clone
## v0.39.4 — Workflow Templates + Clone
Team admins shouldn't rebuild common patterns from scratch. Two
features:
@@ -439,8 +531,9 @@ features:
### Clone workflow
"Duplicate" button on the workflow editor. Creates a new workflow with
the same stages, form templates, and routing rules. New slug, new name
(appended "- Copy"). No versions carried over (must re-publish).
the same stages, form templates, branch rules, and Starlark hooks.
New slug, new name (appended "- Copy"). No versions carried over
(must re-publish).
```
POST /api/v1/teams/:teamId/workflows/:id/clone
@@ -451,15 +544,16 @@ Pure BE operation — deep-copies workflow + stages, generates new IDs.
### Built-in templates
Seed a `workflow_templates` table with 3-5 common patterns:
Seed a `workflow_templates` table with common patterns covering both
simple and mixed workflows:
| Template | Stages | Description |
|----------|--------|-------------|
| Customer Intake | form → review | Public form, team reviews |
| IT Help Desk | LLM chat → triage → resolution | AI-assisted intake |
| Approval Chain | form → approve → approve → notify | Multi-level approval |
| Feedback Survey | form (multi-step) → analytics | Data collection |
| Onboarding | form → team A → team B → team A | Multi-team handoff |
| Template | Stages | Type |
|----------|--------|------|
| Customer Intake | form → review | Simple |
| IT Help Desk | LLM chat → triage → resolution | Simple |
| Approval Chain | form → approve → approve → notify | Simple |
| Smart Intake | automated (CRM lookup) → dynamic (tailored form) → review | Mixed |
| Onboarding | form → team A → team B → automated (provision) | Mixed |
"New from template" in the team-admin workflow creation flow.
Templates are read-only platform data, not user-editable. They
@@ -469,11 +563,11 @@ serve as starting points — clone and customize.
- "Duplicate" button in workflow editor header
- "New from Template" option in workflow creation flow
- Template picker modal with descriptions
- Template picker modal with descriptions and type badges
---
## v0.38.5 — Analytics Dashboard
## v0.39.5 — Analytics Dashboard
Team leads need to answer: how long does each stage take, where are
we bottlenecked, what's our SLA compliance rate.
@@ -555,30 +649,38 @@ too high on large datasets (unlikely at 50-user scale).
| Version | Estimated CS | Heaviest piece |
|---------|-------------|----------------|
| v0.38.0 | 4 | Form builder component tree (5+ files) |
| v0.38.1 | 2 | Drag-and-drop is fiddly but small |
| v0.38.2 | 3 | SLA scanner + notification plumbing |
| v0.38.3 | 4 | Visitor branding + email + progress |
| v0.38.4 | 2 | Clone is one BE endpoint + FE button |
| v0.38.5 | 3 | Analytics query + chart components |
| **Total** | **~18** | |
| v0.39.0 | 5 | Graph engine + form builder (10+ files) |
| v0.39.1 | 2 | Drag-and-drop is fiddly but small |
| v0.39.2 | 3 | SLA scanner + notification plumbing |
| v0.39.3 | 4 | Standalone portal + branding + email + progress |
| v0.39.4 | 2 | Clone is one BE endpoint + FE button |
| v0.39.5 | 3 | Analytics query + chart components |
| **Total** | **~19** | |
---
## Risk Notes
**v0.38.0 (Form Builder) is the long pole.** If this slips, the MVP
gate phrase "build workflows visually" fails. Prioritize this over
everything else in the series. If time is tight, ship a simplified
version (no fieldsets, no conditional visibility) and add those in a
patch.
**v0.39.0 (Graph Engine + Form Builder) is the long pole.** Two
major deliverables in one version. If this slips, the MVP gate phrase
"build workflows visually" fails. Prioritize this over everything
else in the series. If time is tight, ship the graph engine with
simple stages only (dynamic/automated as stubs) and a simplified
form builder (no fieldsets, no conditional visibility), then add
dynamic/automated execution and form builder polish in a patch.
**v0.38.3 (Email) depends on platform SMTP.** If SMTP isn't
**v0.39.3 (Email) depends on platform SMTP.** If SMTP isn't
configured, the feature is invisible. Consider making the email
config a prerequisite admin step with a setup wizard, or defer email
to v0.38.5 and keep .3 focused on branding + progress.
to v0.39.5 and keep .3 focused on the standalone portal + branding
+ progress.
**v0.38.5 (Analytics) can be cut.** If the series is running long,
**v0.39.5 (Analytics) can be cut.** If the series is running long,
analytics is the most deferrable item — it's nice-to-have, not
gate-blocking. The existing monitor + funnel endpoints cover the
critical "is anything stuck" question.
**Dynamic stage authoring DX.** Developers need clear docs and
examples for writing Starlark hooks. The git-board rewrite (v0.38.4)
should establish patterns, but workflow-specific examples are needed.
Consider a "dynamic stage cookbook" as part of v0.39.0.