finos / finos/architecture-as-code

Visualize Flow Sequence Diagrams in CalmHub

Open
#2,537 1 comment 0 reactions 1 assignee Claimed by @LeighFinegold View on GitHub
calm-hub-ui
Dominant language
TypeScript
Stars
399
Forks
138
Avg merge
2d 14h
Merged PRs (30d)
37

Description

### Target Project:
`calm-hub-ui` — the React frontend for CALM Hub (`calm-hub-ui/`)

### Description of Feature:
Add a dedicated **Flow Visualization** view to the CALM Hub UI so that users can inspect standalone flow documents stored in the Hub as a rich, structured sequence view rather than raw JSON.

A CALM flow document describes a named business flow as an ordered list of transitions, each referencing a relationship in an architecture by its `relationship-unique-id`. Today these documents are stored in the Hub and listed in the tree navigation under each namespace, but selecting one only renders the raw JSON blob. This feature adds a `FlowSection` component with a **Transitions** tab (a full-page, numbered sequence view of each flow's transitions) and a **JSON** tab (existing behaviour). When the flow document also contains `nodes` and `relationships` (an architecture-with-flows document), a third **Diagram** tab renders the existing ReactFlow visualizer with flow annotations.

Image

### User Stories:
- As an **architect**, I want to view a flow document as a numbered sequence of transitions so that I can quickly understand the business process without reading raw JSON.
- As a **developer**, I want to see each transition's sequence number, relationship ID, description, and direction in a structured list so that I can trace the technical path through the architecture.
- As a **reviewer**, I want to switch between the Transitions view and the raw JSON tab so that I can validate the document content alongside its visual representation.
- As a **Hub user**, I want version navigation on flow documents (consistent with patterns and architectures) so that I can compare flow versions over time.

### Current Limitations:
- Selecting a flow from the tree navigation routes to `DocumentDetailSection`, which renders only a raw `JsonRenderer` with no structural visualization.
- The `isDiagramView` guard in `Hub.tsx` excludes `calmType === 'Flows'`, so flows never reach the ReactFlow visualizer even when the stored document contains `nodes` and `relationships`.
- The existing `FlowCard`, `FlowTransitionItem`, and `FlowsPanel` components (used in the architecture diagram's MetadataPanel) have no full-page equivalent and are not reachable from the flow document view.

### Proposed Implementation:

**Technical design considerations:**

- Create `calm-hub-ui/src/hub/components/flow-section/FlowSection.tsx` — container component modelled after `DiagramSection`. Responsibilities: `SectionHeader` with `IoGitNetworkOutline` icon, version fetching via `CalmService.fetchFlowVersions`, React Router version navigation (`navigate`), and a tab bar.
- Create `calm-hub-ui/src/hub/components/flow-section/FlowSequenceView.tsx` — full-page scrollable view that extracts `flows[]` from the document using the following detection logic:
- If `data.flows` is an array → architecture-with-flows document, use `data.flows`
- If `data['unique-id']` and `data.transitions` are present → standalone `CalmFlowSchema`, wrap in array
- Otherwise → render an empty state
- Renders each flow as a card (name + description header, then numbered transitions) reusing `FlowCard` and `FlowTransitionItem` from `visualizer/components/reactflow/flows-panel/`, adapted with Tailwind/DaisyUI layout for full-page width.
- **Tab bar** on `FlowSection`:
- **Transitions** tab — always shown, renders `FlowSequenceView`
- **JSON** tab — always shown, renders existing `JsonRenderer`
- **Diagram** tab — shown only when the document has `nodes` + `relationships`, renders the existing `Drawer` component
- Modify `calm-hub-ui/src/hub/Hub.tsx` — add `const isFlowView = data?.calmType === 'Flows'` and render `` in the conditional chain before the `DocumentDetailSection` fallback.

**API changes:** None — `CalmService.fetchFlow`, `fetchFlowVersions`, and `fetchFlowSummaries` already exist.

**Data model changes:** None — `CalmFlowSchema` and the `Data` union type in `calm.ts` already cover flows.

**Dependencies:**
- Existing `FlowCard`, `FlowTransitionItem` from `visualizer/components/reactflow/flows-panel/`
- Existing `Drawer` component for optional diagram tab
- Existing `SectionHeader`, `JsonRenderer`, `SectionHeader` hub components
- `CalmService`, React Router `useNavigate`/`useParams`

**Centralise Shared Logic**: Need to think about the fact that the flow definition has to gather details from the architecture where relationship ids are formed. So may need to centralise perhaps the widget stuff.

### Testing Strategy:

- **Unit tests** for `FlowSequenceView`:
- Renders all transitions in sequence-number order for an architecture-with-flows document
- Renders correctly when given a standalone `CalmFlowSchema` document
- Renders an empty state when no flows are detected
- **Unit tests** for `FlowSection`:
- Displays the Transitions tab by default
- Switches to JSON tab and renders `JsonRenderer`
- Shows Diagram tab only when document contains `nodes`
- Fetches and displays available versions; navigates on version change
- **Integration / smoke test** (Cypress if applicable): selecting a flow in the tree navigation renders the `FlowSection` with transitions visible
- All tests run via `npm test --workspace calm-hub-ui` from the repo root; coverage target >80% for new code

### Documentation Requirements:

- Update `calm-hub-ui/AGENTS.md` to describe the `FlowSection` component and its document-shape detection logic.
- Add a short entry to the CALM Hub UI `README.md` noting that flow documents now have a dedicated visualization view.

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

### Additional Context:

**Existing infrastructure that can be reused:**
- `FlowCard`, `FlowTransitionItem`, `FlowsPanel` in `visualizer/components/reactflow/flows-panel/` already render flow transitions; they are currently only used in the collapsible MetadataPanel at the bottom of the architecture diagram view.
- `extractFlowTransitions` in `visualizer/components/reactflow/utils/relationshipParser.ts` annotates ReactFlow edges with flow data from architecture documents.
- `FlowSequenceWidget` in `calm-widgets` (Handlebars-based) performs similar transition rendering for documentation output — useful as a reference implementation.

**Future follow-up (out of scope):**
- Cross-link a flow to its associated architecture so the Diagram tab can highlight the exact path through the graph.
- Timeline/version comparison for flows (parallel to the existing architecture compare mode).
- The fact that in future we may have a flow definition that doesn't necessary require the architecture defined up front
- In Docify we also have a block-architecture diagram for just that flow. Perhaps we should do something similar.

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.