Builder: Comprehensive Architecture Audit

Source: This page is based on docs/BUILDER_AUDIT.md

Last Updated: January 20, 2026
Status: 🟢 Production Ready - Excellent Architecture & Performance
Entry Point: pages/workspaces/[groupId]/workflows/[workflowId]/index.tsx

Executive Summary

The Builder is Eddy's "Level Editor" - the visual environment where users design and configure workflows.

Current State Assessment

Area	Grade	Status
Data Fetching	A-	✅ Optimized with lazy loading
State Management	A-	✅ Consolidated into single store
Performance	A-	✅ 98% reduction in operations
Code Organization	A	✅ Modular with extracted hooks
Maintainability	A-	✅ Clean patterns with testing
Separation of Concerns	A-	✅ Clear boundaries defined

Overall Grade: A-/A (Excellent - Production Ready)

Architecture Overview

Component Hierarchy

┌──────────────────────────────────────────────────────────┐
│  pages/workspaces/[groupId]/workflows/[workflowId]/      │
│  index.tsx (Entry Point - 457 lines)                     │
│                                                           │
│  ┌────────────────────────────────────────────────────┐  │
│  │ Data Fetching Layer                                │  │
│  │ • useGetWorkflow()                                 │  │
│  │ • useGetGroupMemberships()                         │  │
│  │ • useGetWorkflowRunPreviewByWorkflow()             │  │
│  │ • useGetSheetDataByWorkflowId() (lazy)             │  │
│  │ • useChannel() (Ably real-time)                    │  │
│  └────────────────────────────────────────────────────┘  │
│                                                           │
│  ┌────────────────────────────────────────────────────┐  │
│  │ State Management                                   │  │
│  │ • useWorkflowBuilderStore (builder-specific)       │  │
│  │ • useCommonStore (shared with sessions)            │  │
│  │ • useUIStore (device type)                         │  │
│  │ • useStageRoleAssignmentsModalStore                │  │
│  └────────────────────────────────────────────────────┘  │
│                                                           │
│  ┌────────────────────────────────────────────────────┐  │
│  │ Main UI Components                                 │  │
│  │ • BuilderTopBar (modals, publish, validation)      │  │
│  │ • BuilderStageGraph (visual graph editor)          │  │
│  │ • BuilderPanels (page/section/block editors)       │  │
│  │ • EdgeEditor (connection rule editor)              │  │
│  │ • Modals (Settings, Activity, Data, Sessions)      │  │
│  └────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────┐
│  components/builder/BuilderStageGraph.tsx                │
│  (Graph Editor - 685 lines, down from 1,007)             │
│                                                           │
│  ┌────────────────────────────────────────────────────┐  │
│  │ Custom Hooks (Extracted)                           │  │
│  │ • useGraphMutations (180 lines) - CRUD operations  │  │
│  │ • useGraphLayout (260 lines) - Dagre & animations  │  │
│  └────────────────────────────────────────────────────┘  │
│                                                           │
│  ┌────────────────────────────────────────────────────┐  │
│  │ UI Components (Extracted)                          │  │
│  │ • GraphContextMenu (59 lines) - Right-click menu   │  │
│  │ • GraphControlPanels (86 lines) - Layout/zoom      │  │
│  └────────────────────────────────────────────────────┘  │
│                                                           │
│  ┌────────────────────────────────────────────────────┐  │
│  │ Node Types                                         │  │
│  │ • BuilderGraphNode - Stage node with preview       │  │
│  │ • Custom edge types (smoothstep, looping)          │  │
│  └────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────┘

Key Responsibilities

Entry Point (index.tsx):

Data orchestration (fetch workflow, group, preview)
Permission management (CASL abilities)
Validation coordination (debounced)
Modal state management
Real-time updates (Ably)
Cleanup on unmount

BuilderStageGraph:

Visual graph rendering (ReactFlow)
Node/edge creation and deletion
Drag-and-drop positioning
Layout algorithms (Dagre)
Connection validation
Animation coordination

BuilderTopBar:

Workflow metadata display
Modal triggers (Data, Activity, Settings, Sessions)
Publish toggle
Validation error display
Start menu & options

BuilderPanels:

Page content editor
Section editor
Block editor
Responsive layout (desktop/mobile)

Data Fetching Strategy

Primary Workflow Data

// Always loaded
const { data: workflow } = useGetWorkflow(workflowId)
const { data: group } = useGetGroupMemberships(groupId)
const { data: preview } = useGetWorkflowRunPreviewByWorkflow(workflowId)

// Lazy loaded (only when needed)
const { data: sheetData } = useGetSheetDataByWorkflowId(workflowId, {
  enabled: isDataModalOpen
})

Benefits:

Minimal initial load
Sheet data loaded only when Data modal opens
Preview data for session count display

State Management

Zustand Stores

useWorkflowBuilderStore - Builder-specific state:

Selected page, section, block
Edge editor state
Validation errors
Modal open/closed states

useCommonStore - Shared with sessions:

User preferences
UI settings

useUIStore - Device detection:

Mobile/desktop detection
Responsive layout decisions

State Organization

// ✅ GOOD: Clear state boundaries
const {
  selectedPageId,
  selectedSectionId,
  selectedBlockId,
  setSelectedPageId
} = useWorkflowBuilderStore()

// ❌ BAD: Mixing concerns
const [selectedPageId, setSelectedPageId] = useState()
const [validationErrors, setValidationErrors] = useState()
// ... scattered across component

Performance Optimizations

Graph Computation

Before Optimization:

Multiple passes over nodes/edges
O(N²) operations for styling
Redundant filtering

After Optimization:

Single-pass computation
Pre-computed maps for O(1) lookups
98% reduction in operations

Lazy Loading

Sheet Data:

Only loaded when Data modal opens
Prevents unnecessary API calls
Reduces initial bundle size

Validation:

Debounced validation (500ms)
Only runs when workflow changes
Prevents excessive computation

Code Organization

Extracted Hooks

useGraphMutations.ts (180 lines):

createPage()
deletePage()
createTransition()
deleteTransition()
Mutation logic separated from UI

useGraphLayout.ts (260 lines):

Dagre layout algorithm
Animation coordination
Position calculations
Layout logic separated from rendering

Extracted Components

GraphContextMenu.tsx (59 lines):

Right-click menu
Context-aware actions
Reusable across graph types

GraphControlPanels.tsx (86 lines):

Layout controls
Zoom controls
Fit view buttons

Testing

Unit Tests

Coverage:

Graph mutations
Validation logic
State management

Example:

describe('useGraphMutations', () => {
  it('creates page with correct defaults', () => {
    const { result } = renderHook(() => useGraphMutations())
    const newPage = result.current.createPage()
    expect(newPage.title).toBe('New Stage')
    expect(newPage.sections).toEqual([])
  })
})