docs: add flow-to-library step sync design doc
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
chihlasm
187
docs/plans/2026-02-25-flow-to-library-sync-design.md
Normal file
187
docs/plans/2026-02-25-flow-to-library-sync-design.md
Normal file
@@ -0,0 +1,187 @@
|
||||
# Flow-to-Library Step Sync Design
|
||||
|
||||
> **Date:** 2026-02-25
|
||||
> **Feature:** Automatically sync steps from published flows into the step library
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
When a flow is published, its steps are extracted and written into the `step_library` table so engineers can discover and reuse them when building new flows or inserting ad-hoc steps during a live session. Library entries are flow-owned and read-only — forking creates a personal copy for customization.
|
||||
|
||||
**What gets synced:**
|
||||
- `procedural` / `maintenance` flows → each `procedure_step` node → `step_type: 'action'`
|
||||
- `troubleshooting` flows → each `action` node → `step_type: 'action'`; each `solution` node → `step_type: 'solution'`
|
||||
- `section_header` and `procedure_end` nodes are NOT synced as library entries
|
||||
|
||||
**Sync trigger:** `PUT /trees/{tree_id}` when `status` transitions to `'published'`
|
||||
|
||||
**Sync model:** Upsert keyed on `(source_tree_id, source_node_id)` — subsequent publishes update existing entries without losing usage counts or ratings.
|
||||
|
||||
---
|
||||
|
||||
## Section 1: Data Model
|
||||
|
||||
### New columns on `step_library` (one migration)
|
||||
|
||||
| Column | Type | Default | Notes |
|
||||
|--------|------|---------|-------|
|
||||
| `source_tree_id` | UUID FK → `trees.id` | NULL | SET NULL on tree delete |
|
||||
| `source_node_id` | String(255) | NULL | Node `id` within `tree_structure` JSONB |
|
||||
| `is_flow_synced` | Boolean | `false` | Distinguishes synced from manually created entries |
|
||||
| `last_synced_at` | DateTime(timezone=True) | NULL | Timestamp of last sync |
|
||||
|
||||
### New optional field on `StepContent` schema
|
||||
|
||||
Add `group_label: Optional[str] = None` to `StepContent` in `backend/app/schemas/step_library.py`. For procedural steps that belong to a section, this stores the section header title so steps are browsable/filterable by section in the library.
|
||||
|
||||
### Per-step visibility override on procedural step nodes
|
||||
|
||||
Add optional `library_visibility` field to individual step nodes in `tree_structure` JSONB:
|
||||
- Type: `'team' | 'public'` (no `'private'` — synced steps are always at minimum team-visible)
|
||||
- If absent: inherits visibility from the flow (default behavior)
|
||||
- Stored directly on the step node in `tree_structure` — no schema migration needed (JSONB is flexible)
|
||||
|
||||
### Visibility inheritance mapping
|
||||
|
||||
| Flow state | Resolved step visibility |
|
||||
|-----------|--------------------------|
|
||||
| `is_public=True` | `'public'` |
|
||||
| `is_public=False`, has `account_id` | `'team'` |
|
||||
| `is_public=False`, no `account_id` | `'team'` |
|
||||
| Step has `library_visibility` set | Use that value (overrides above) |
|
||||
|
||||
### On flow deactivation / deletion
|
||||
|
||||
When `is_active` is set to `False` on a tree, or the tree is deleted, soft-delete all synced library entries for that tree: `UPDATE step_library SET is_active=False WHERE source_tree_id=:tree_id AND is_flow_synced=True`.
|
||||
|
||||
Forked copies (`is_flow_synced=False`, different `created_by`) are unaffected.
|
||||
|
||||
---
|
||||
|
||||
## Section 2: Sync Logic (Backend)
|
||||
|
||||
### Trigger location
|
||||
|
||||
`backend/app/api/endpoints/trees.py` — `update_tree()` function, after the block at line ~587 where `status` is confirmed to be transitioning to `'published'`.
|
||||
|
||||
### Extraction logic
|
||||
|
||||
**For procedural/maintenance flows:**
|
||||
```
|
||||
steps = tree_structure.get('steps', [])
|
||||
for node in steps:
|
||||
if node['type'] != 'procedure_step':
|
||||
continue
|
||||
# find the most recent section_header preceding this step
|
||||
group_label = last_seen_section_header_title
|
||||
yield StepLibraryUpsert(
|
||||
title=node['title'],
|
||||
step_type='action',
|
||||
content=StepContent(
|
||||
instructions=node.get('description') or node['title'],
|
||||
help_text=node.get('expected_outcome'),
|
||||
commands=[StepCommand(label=c.get('label',''), command=c['code'], command_type=c.get('language'))
|
||||
for c in normalize_commands(node.get('commands'))],
|
||||
group_label=group_label,
|
||||
),
|
||||
visibility=node.get('library_visibility') or resolve_visibility(tree),
|
||||
source_tree_id=tree.id,
|
||||
source_node_id=node['id'],
|
||||
)
|
||||
```
|
||||
|
||||
**For troubleshooting flows:**
|
||||
```
|
||||
walk all nodes recursively
|
||||
for node with type in ('action', 'solution'):
|
||||
yield StepLibraryUpsert(
|
||||
title=node['title'],
|
||||
step_type='action' if node['type']=='action' else 'solution',
|
||||
content=StepContent(
|
||||
instructions=node.get('description') or node['title'],
|
||||
),
|
||||
visibility=resolve_visibility(tree),
|
||||
source_tree_id=tree.id,
|
||||
source_node_id=node['id'],
|
||||
)
|
||||
```
|
||||
|
||||
**Command normalization:** `node.commands` can be a plain string or an array of `{language, code, label}` objects. Normalize both into `StepCommand` list.
|
||||
|
||||
### Upsert query
|
||||
|
||||
```sql
|
||||
INSERT INTO step_library (id, title, step_type, content, visibility, created_by,
|
||||
account_id, is_flow_synced, source_tree_id, source_node_id, last_synced_at, ...)
|
||||
VALUES (...)
|
||||
ON CONFLICT (source_tree_id, source_node_id)
|
||||
DO UPDATE SET
|
||||
title = EXCLUDED.title,
|
||||
content = EXCLUDED.content,
|
||||
visibility = EXCLUDED.visibility,
|
||||
last_synced_at = EXCLUDED.last_synced_at,
|
||||
is_active = true -- re-activate if previously soft-deleted
|
||||
```
|
||||
|
||||
Requires a unique constraint on `(source_tree_id, source_node_id)`.
|
||||
|
||||
### `created_by` for synced entries
|
||||
|
||||
Set to the tree's `author_id`. This gives the flow author "ownership" of the entry, consistent with the flow-owned model. Permissions in `core/permissions.py` already allow the creator to see their own private steps — no change needed.
|
||||
|
||||
---
|
||||
|
||||
## Section 3: Per-Step Visibility Override (Editor)
|
||||
|
||||
### Where
|
||||
|
||||
`frontend/src/components/procedural-editor/StepEditor.tsx` — inside the existing "More Options" collapsible section.
|
||||
|
||||
### What
|
||||
|
||||
A **"Library Visibility"** select field, shown only for `procedure_step` nodes (not section headers, not end nodes):
|
||||
|
||||
```
|
||||
Library Visibility
|
||||
[ Inherit from flow ▼ ] (options: Inherit from flow / Team only / Public)
|
||||
```
|
||||
|
||||
- Default (no `library_visibility` on node): renders as "Inherit from flow"
|
||||
- Selecting "Team only" or "Public" writes `library_visibility: 'team'` or `library_visibility: 'public'` to the node
|
||||
- Selecting "Inherit from flow" removes the `library_visibility` key from the node
|
||||
|
||||
Only rendered when `tree_type` is `'procedural'` or `'maintenance'`. Troubleshooting flows have no per-node override (they inherit the flow visibility always).
|
||||
|
||||
---
|
||||
|
||||
## Section 4: Frontend — Step Library Browser
|
||||
|
||||
### Changes to `StepLibraryBrowser` / step list
|
||||
|
||||
- **"From Flow" badge** on synced entries (`is_flow_synced: true`): small chip — same style as existing type badges. Shows source flow name.
|
||||
- **Step detail/preview panel**: add "Sourced from: [Flow Name]" line with a link to the flow's navigate/edit page.
|
||||
- **Read-only indicator**: for `is_flow_synced` entries, replace the Edit button with a lock icon + tooltip: "Managed by source flow — fork to customize."
|
||||
- **Fork behavior**: existing "Save to Library" copy mechanism unchanged. Forked copy gets `is_flow_synced=false`, `source_tree_id=null`, `created_by=current_user`.
|
||||
|
||||
### API response changes
|
||||
|
||||
`StepLibraryResponse` needs two new fields:
|
||||
- `is_flow_synced: bool`
|
||||
- `source_tree_name: Optional[str]` — joined from `trees.name` at query time
|
||||
|
||||
---
|
||||
|
||||
## Files Changed
|
||||
|
||||
| File | Change |
|
||||
|------|--------|
|
||||
| `backend/alembic/versions/030_add_step_library_sync_fields.py` | New migration — add 4 columns + unique constraint |
|
||||
| `backend/app/models/step_library.py` | Add 4 new columns + FK relationship to Tree |
|
||||
| `backend/app/schemas/step_library.py` | Add `group_label` to `StepContent`; add `is_flow_synced` + `source_tree_name` to response schema |
|
||||
| `backend/app/api/endpoints/trees.py` | Add sync logic after publish transition |
|
||||
| `backend/app/core/step_sync.py` | New module — extraction + upsert logic (keeps trees.py clean) |
|
||||
| `backend/tests/test_step_sync.py` | New test file |
|
||||
| `frontend/src/types/step.ts` | Add `is_flow_synced`, `source_tree_name` to `Step` type |
|
||||
| `frontend/src/components/procedural-editor/StepEditor.tsx` | Add Library Visibility select in More Options |
|
||||
| `frontend/src/components/step-library/StepLibraryBrowser.tsx` | From Flow badge, read-only indicator, source flow link |
|
||||
Reference in New Issue
Block a user