EmboFlow/design/04-ui-ux/information-architecture-and-key-screens.md

EmboFlow Information Architecture And Key Screens

Goal

Define the primary navigation model, main screens, and key interaction patterns for EmboFlow V1.

The UI should feel like a serious data workflow product, not a generic low-code canvas. The most important interaction is the relationship between assets, workflows, runs, and outputs.

Information Architecture

Top-level product areas:

• Workspace switcher
• Project selector
• Projects
• Asset Workspace
• Node Registry Workspace
• Canvas Workspace
• Explore Workspace
• Label Workspace
• Admin Workspace

Navigation Model

Global Header

Recommended global header content:

• workspace switcher
• project switcher
• language switcher for Chinese and English
• search entry
• run notifications
• user menu

Primary Sidebar

Recommended primary navigation:

• Projects
• Assets
• Nodes
• Workflows
• Runs
• Explore
• Labels
• Admin

This keeps the product model explicit:

• assets are inputs
• workflows define transformation logic
• runs represent execution history
• explore is where users inspect outputs and raw inputs

Screen 1: Workspace And Project Entry

Purpose:

• choose personal or team workspace
• choose or create project
• view recent projects and recent workflow runs

V1 should emphasize project-level organization because all major resources are project-scoped.

The current implementation now matches this with:

• a dedicated Projects sidebar entry
• a header-level active project selector
• project cards that let the user open a project directly into workflow authoring

Screen 2: Asset Workspace

Purpose:

• upload or import raw assets
• inspect asset type and status
• review probe summary
• launch preview or workflow entrypoint

Core regions:

• asset list with filters
• import actions
• asset status and source type
• probe summary card
• recommended next actions

Key actions:

• upload file
• upload archive
• import object storage prefix
• register storage path
• open preview
• create workflow from asset

The current V1 runtime extends this screen beyond raw assets and treats project data management as one combined workspace:

• raw asset registration
• storage connection creation for local, minio, s3, bos, and oss
• dataset creation from selected source assets into a selected storage connection

Screen 3: Asset Detail / Explore Entry

Purpose:

• inspect one asset deeply
• browse folder structure
• inspect metadata and detected format
• preview representative files

Suggested panels:

• left: file tree or asset structure
• center: preview surface
• right: metadata, probe report, warnings, recommended nodes

This screen should support both:

• raw asset view
• canonical dataset summary view when available

Screen 4: Canvas Workspace

This is the core authoring surface.

Layout

Recommended layout, aligned with the Xspark reference pattern:

• left: node library and workflow tools
• center: canvas
• right: node configuration panel

Left Panel

Contains:

• source nodes
• transform nodes
• inspect nodes
• annotate nodes
• export nodes
• utility nodes
• search/filter

Center Canvas

Supports:

• drag-and-drop node placement
• edge creation
• zoom and pan
• mini-map
• node badges for validation status
• run-state overlays when viewing an executed version

The current V1 implementation is simpler than the target canvas UX, but it already follows the same persistence model:

• load the latest saved workflow version when the editor opens
• load project assets so the run entrypoint can bind a concrete input asset
• keep an unsaved draft in local editor state
• allow node add and remove operations on the draft
• save the current draft as a new workflow version
• auto-save a dirty draft before triggering a run

The current runtime implementation now also renders the center surface as a real node canvas instead of a static placeholder list:

• free node dragging on the canvas
• left-panel node drag-and-drop into the canvas, in addition to click-to-append
• drag-to-connect edges between node handles
• zoom and pan
• dotted background grid
• mini-map
• canvas controls
• persisted node positions and viewport in visualGraph
• localized inline validation feedback when a connection is rejected

The current V1 authoring rules intentionally keep the graph model constrained so the workflow stays legible and executable:

• source nodes do not accept inbound edges
• export nodes do not emit outbound edges
• duplicate edges are blocked
• self-edges are blocked
• ordinary nodes may only keep one inbound edge
• set-operation utility nodes may accept multiple inbound edges
• cycles are blocked

Custom nodes follow the same rule system, but the decision is contract-driven. When a custom Docker node is added to the canvas, the editor seeds its runtime defaults into the draft immediately; if that contract declares inputMode=multi_asset_set, the node is treated like a multi-input utility node from the first connection attempt.

The current built-in node library also exposes Docker-first runtime defaults in the editor. Most built-ins now render with docker preselected, while still allowing the user to override the executor, image, and optional Python code hook from the right-side configuration panel.

The runtime header also now exposes a visible 中文 / English language toggle and the main shell plus workflow authoring surface are translated through a lightweight i18n layer.

The workflow entry surface that leads into this editor is also now template-aware:

• the Workflows page lists reusable workflow templates for the active project
• the user can create a project workflow from a template
• the user can still create a blank workflow directly

Screen 4A: Node Registry Workspace

Purpose:

• create project-level custom nodes
• choose Docker image or Dockerfile source
• declare input and output contract
• publish the node into the workflow editor node library

Core regions:

• top: contract summary and authoring guidance
• left/top: creation form
• bottom/right: existing custom node list for the active project

The current V1 direction treats custom nodes as project-scoped runtime extensions, not global plugins. That keeps tenancy and lifecycle simpler while still giving teams a controlled way to bring containerized processing into the canvas.

Right Configuration Panel

The right panel is schema-driven.

It should render:

• node title
• node description
• config fields
• input/output schema summary
• executor selection
• runtime policy
• code hook editor if supported
• validation errors

This panel is critical. It should feel like a structured system console, not a generic form dump.

The current right panel also includes a workflow-level Save As Template section so an edited graph can be published back into the project template library.

Screen 5: Workflow Run Detail

Purpose:

• inspect execution state
• view DAG progress
• open task logs
• inspect task outputs
• retry failed nodes

Recommended layout:

• top: run summary and status
• top: bound asset summary and links back to input assets
• center: workflow graph with execution overlays
• bottom or side drawer: logs and artifacts for selected node

V1 run detail should render the selected task as a stable operations panel, not just a raw document dump. The panel should show:

• task status and executor
• task duration and timestamps
• a concise execution summary
• separated stdout and stderr sections
• appended log lines
• artifact links into Explore
• a lightweight result preview for quick inspection

The run header itself should also show an aggregated summary:

• run duration
• run-level task counts
• total stdout/stderr line counts
• failed task ids when present

V1 run detail should expose direct operator actions:

• Cancel Run while queued or running
• Retry Run after a run reaches a terminal state
• Retry Task on a selected failed or cancelled task

Screen 6: Explore Workspace

Purpose:

• inspect raw or processed outputs outside the canvas authoring context
• compare source and transformed outputs
• validate whether a run produced expected results

V1 renderer set:

• directory tree renderer
• JSON renderer
• video renderer
• dataset summary renderer
• quality report renderer

This workspace should open from:

• asset detail
• workflow node output
• artifact detail

Screen 7: Label Workspace

Purpose:

• process annotation tasks
• review results
• attach annotations to data outputs

V1 should keep this lightweight:

• frame labels
• clip labels
• temporal segment labels
• quality tags

The label workspace should be able to open from an artifact or dataset version, not only from a workflow node.

Screen 8: Admin Workspace

Purpose:

• manage members
• manage storage connections
• manage plugin enablement
• inspect audit and runtime settings

Suggested sections:

• members and roles
• workspace settings
• storage connections
• plugin registry
• executor policies
• audit log viewer

Key UX Principles

1. Separate authoring from inspection

Do not overload the canvas with deep preview or annotation workflows. The canvas configures process. Explore and Label workspaces handle dense interaction.

2. Keep lineage visible

Users should be able to move across:

• asset
• workflow
• run
• task
• artifact
• annotation

without losing context.

3. Prefer explicit system terminology

Use consistent object names in the UI:

• Asset
• Dataset
• Workflow
• Run
• Task
• Artifact

Current Runtime Implementation Notes

The current local runtime now exposes these surfaces as a real React application:

• Assets list and asset detail
• Workflows list and workflow editor
• Runs list with project-scoped history
• Run detail
• Explore artifact detail

The current implementation uses direct API-driven page loads, lightweight route handling, and incremental polling for active run detail views instead of a deeper client-side state framework.

The workflow editor surface now reflects persisted workflow versions instead of a hardcoded sample graph. It exposes draft status, node add and remove actions, reload-latest behavior, asset selection for run binding, and version-save / run-trigger controls against the live API. The right panel also now includes the first writable runtime controls for executor override, runtime target, artifact title, and Python code-hook source. The Runs workspace now exposes project-scoped run history, selected-task artifact links into Explore, and the frozen executor/code-hook snapshot for the selected task.

Do not rename the same concept differently across pages.

4. Make validation obvious before execution

Before users run a workflow, the editor should visibly show:

• which project asset is currently selected as the run input
• missing config
• invalid schema connections
• unsupported executor choices
• permission or plugin issues

5. Keep the product usable on standard screens

The canvas and right configuration panel must work on laptop-sized displays. On narrower screens, the right panel may collapse into a drawer.

V1 Visual Direction

The UI should communicate:

• precision
• observability
• traceability
• strong operator control

It should feel closer to a workflow control console than a consumer productivity app.

V1 Non-Goals

V1 UI does not need:

• real-time multi-user cursor collaboration
• advanced canvas commenting systems
• highly customized renderer marketplace UX
• heavy design polish ahead of workflow clarity