finos / finos/architecture-as-code

CALM Studio: flow builder, behaviour panel, and draft rendering

Open
#2,624 0 comments 0 reactions 0 assignees View on GitHub
bdd
Dominant language
TypeScript
Stars
399
Forks
138
Avg merge
2d 6h
Merged PRs (30d)
38

Description

## Feature Proposal

### Target Project:

`calm-suite/calm-studio`

### Description of Feature:

Make Studio the visual authoring surface for the behaviour-driven architecture workflow. Four capabilities, layered on the existing canvas:

1. **Flow builder** — a sequence panel over the existing node canvas for authoring flows: order transitions along drawn relationships, reorder by drag, and record a flow by clicking a path of relationships on the canvas. Builds on the existing read-only flow overlay (`packages/web-component/src/render/flowOverlay.ts`), which already animates transitions with sequence badges.
2. **Behaviour panel** — select a flow, transition, or node and author Given/When/Then scenarios with data-example tables, following the existing properties-panel pattern. Output is a behaviour document plus the behaviour decorator (#2621); anchoring a scenario step to a transition is drag-and-drop.
3. **Draft rendering** — constructs with `status: draft` (#2620) render visually distinct (dashed outlines); a burn-down view lists remaining draft constructs blocking promotion.
4. **"Propose architecture" action** — invokes the shared `calm derive` engine (#2622) against a behaviour document, placing the derived draft nodes, relationships, and flows on the canvas for refinement. An actor/business pack in `@calmstudio/extensions` provides the palette entries (actor and system node types with appropriate icons).

### User Stories:

As a business analyst, I want to describe scenarios in a panel and see a proposed architecture appear on the canvas, so that I can participate in design without writing JSON.

As an architect, I want to refine a derived draft architecture on the canvas — decomposing draft systems, firming up types — and watch the draft burn-down shrink, so that promotion readiness is visible at a glance.

As an architect, I want to anchor scenario steps to flow transitions by drag-and-drop, so that behavioural traceability doesn't require hand-editing identifier glue.

### Current Limitations:

- Flow visualisation is read-only; flows are authored via JSON or AI prompts only.
- Decorators exist in the data model and MCP server but have no canvas UI.
- There is no rendering distinction for draft constructs and no behaviour authoring surface anywhere in the toolchain.

### Proposed Implementation:

- Sequence panel as a new canvas mode in `apps/studio` (Svelte Flow); transition ordering UI writes standard flow documents with transition `unique-id`s (#1875).
- Behaviour panel follows the existing NodeProperties/EdgeProperties pattern; writes behaviour documents and decorators conforming to the published schemas — **Studio is a view, not the source of truth**: everything it produces must validate with `calm validate` and render in calm-widgets with Studio absent.
- Draft styling in the web-component renderers (`nodeRenderer.ts`, `edgeRenderer.ts`); burn-down list in a side panel.
- "Propose architecture" calls the shared derivation engine (same code as the CLI); ambiguity resolution uses Studio dialogs in place of CLI prompts, producing the same mapping artefact.
- **No test execution in Studio**: evidence status from decorator evidence pointers renders as badges; running tests stays in CI.
- MCP server tools extended so AI-chat authoring and the visual editor share the same document CRUD path — a scenario authored in chat appears live on the canvas.

### Alternatives Considered:

- **A dedicated lane/lifeline canvas for flows** — rejected: with actors modelled as nodes (#1875), the existing node canvas plus a sequence panel covers the need with far less new surface.
- **Studio-native behaviour format** — rejected: schemas are owned by `calm/`; Studio consumes the standard so CLI, widgets, VSCode, and Hub interoperate.

### Testing Strategy:

- Vitest component tests for the sequence panel, behaviour panel, and draft rendering.
- Engine integration tests reuse the shared derive engine's fixtures.
- Round-trip tests: documents authored in Studio validate via `calm validate` and re-open identically.

### Documentation Requirements:

- Studio user guide sections for the flow builder, behaviour panel, and propose-architecture action.
- Update calm-suite/calm-studio AGENTS.md with the new canvas mode and panels.

### Implementation Checklist:

- [ ] Design reviewed and approved
- [ ] Implementation completed
- [ ] Tests written and passing
- [ ] Documentation updated
- [ ] Relevant workflows updated (if needed)
- [ ] Performance impact assessed

### Additional Context:

Depends on the draft `2026-03` schema changes (lifecycle status, behaviour documents, transition `unique-id`) and the shared derive engine; develops against the drafts. Part of the behaviour-driven architecture work — see the tracking issue finos/architecture-as-code#2627.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.