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
• Asset Workspace
• Canvas Workspace
• Explore Workspace
• Label Workspace
• Admin Workspace

Navigation Model

Global Header

Recommended global header content:

• workspace switcher
• project switcher
• search entry
• run notifications
• user menu

Primary Sidebar

Recommended primary navigation:

• Assets
• 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.

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

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
• 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

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.

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
• center: workflow graph with execution overlays
• bottom or side drawer: logs and artifacts for selected node

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
• Run detail
• Explore artifact detail

The current implementation uses direct API-driven page loads and lightweight route handling 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, and version-save / run-trigger controls against the live API.

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:

• 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