webapp/frontend/ — React Flow Visual Workflow Builder

What is this & why does it exist?

The frontend lets non-developers compose agent pipelines visually. React Flow provides the canvas where users drag agent nodes from a sidebar, connect them with edges, configure tickers and models, and press “Run”. The most sophisticated part is the SSE integration — as the backend executes agents, the frontend receives progress events and updates individual node visuals in real-time (idle → in-progress → complete/error). Flow configurations are persisted to the backend database so users can save, load, and reuse pipelines.

Why Is It Designed This Way?

React Flow was chosen because it provides a production-ready Orchestration" href="../../core_doc/graph/index.html">graph canvas with built-in drag-and-drop, edge routing, zoom/pan, and minimap — all of which would take months to build from scratch. Custom node types (rather than generic boxes) give each agent a distinct visual identity with status indicators, analysis output, and ticker badges. The extractBaseAgentKey() function exists because React Flow requires globally unique node IDs, but the backend’s ANALYST_CONFIG uses canonical keys — the 6-character random suffix bridges this gap. SSE via fetch + ReadableStream was chosen over EventSource because SSE with POST bodies isn’t supported by the native EventSource API.

SSE Event Handling (services/api.ts)

runHedgeFund: (params: HedgeFundRequest,
               nodeContext: ReturnType<typeof useNodeContext>,
               flowId: string | null = null): (() => void) => {

  const controller = new AbortController();  // WHY: Enables cancellation on unmount

  // WHY: fetch() + ReadableStream because EventSource only supports GET
  fetch(`${API_BASE_URL}/hedge-fund/run`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(params),
    signal: controller.signal,
  })
  .then(response => {
    const reader = response.body?.getReader();
    const decoder = new TextDecoder();
    let buffer = '';

    const processStream = async () => {
      while (true) {
        const { done, value } = await reader.read();
        if (done) break;

        buffer += decoder.decode(value, { stream: true });
        // WHY: SSE events are separated by double newlines
        const events = buffer.split('\n\n');
        buffer = events.pop() || '';  // Keep partial event in buffer

        for (const eventText of events) {
          const eventTypeMatch = eventText.match(/^event: (.+)$/m);
          const dataMatch = eventText.match(/^data: (.+)$/m);

          if (eventTypeMatch && dataMatch) {
            const eventType = eventTypeMatch[1];
            const eventData = JSON.parse(dataMatch[1]);

            switch (eventType) {
              case 'start':
                nodeContext.resetAllNodes(flowId);  // WHY: Clean slate for new run
                break;
              case 'progress':
                // WHY: Backend sends "warren_buffett_agent" but node IDs are
                // "warren_buffett_abc123" - must strip suffix to match
                const baseKey = eventData.agent.replace('_agent', '');
                const nodeId = getAgentIds().find(id =>
                  extractBaseAgentKey(id) === baseKey
                ) || baseKey;

                nodeContext.updateAgentNode(flowId, nodeId, {
                  status: eventData.status === 'Done' ? 'COMPLETE' : 'IN_PROGRESS',
                  ticker: eventData.ticker,
                  analysis: eventData.analysis,
                });
                break;
              case 'complete':
                nodeContext.setOutputNodeData(flowId, eventData.data);
                nodeContext.updateAgentNodes(flowId, getAgentIds(), 'COMPLETE');
                break;
            }
          }
        }
      }
    };
    processStream();
  });

  return () => controller.abort();  // WHY: Cleanup function for React useEffect
};