UI Response System — Architecture¶

This content was migrated from Documentation/UI_NODE_SYSTEM.md and restructured into audience sections. Review for accuracy against the current codebase.

Context and Purpose¶

The UI Response System was refactored from a single monolithic user_interface_node into a set of specialized response nodes. The original node handled all response variants (simple, complex, voice, HITL, disambiguation) in one function, making it difficult to maintain and test.

The driving requirements behind the current architecture are:

• Separation of concerns — Each response variant has its own node with a focused responsibility, making changes to one variant independent of others
• Fragment-based prompts — Prompt content lives in editable markdown files, not Python strings, allowing non-developers to tune Swisper's voice
• Streaming-first — Responses stream word-by-word to minimize perceived latency, with card placeholder replacement handled during the stream
• Content authority — An explicit authority chain prevents the LLM from hallucinating when agent results are available

Architecture Overview¶

The UI Response System consists of six specialized nodes, a shared context extractor, a prompt assembly pipeline, and a streaming layer.

flowchart TB
    subgraph Input["From Global Supervisor"]
        STATE[GlobalSupervisorState]
    end

    subgraph Router["UI Router (routing.py)"]
        STATE --> UR{Response Type?}
    end

    subgraph Nodes["Specialized Response Nodes"]
        UR -->|simple chat| ST[Simple Text Node]
        UR -->|complex chat| CT[Complex Text Node]
        UR -->|HITL question| HT[HITL Text Node]
        UR -->|non-blocking disambig| DST[Disambiguation Simple]
        UR -->|blocking disambig| DCT[Disambiguation Complex]
        UR -->|BTW resolved| DA[Disambiguation Ack]
    end

    subgraph Shared["Shared Infrastructure"]
        SC[Shared Context Extractor]
        PA[Prompt Assembly]
        RS[Response Streaming]
    end

    ST --> SC
    CT --> SC
    DST --> SC
    DCT --> SC
    SC --> PA
    PA --> LLM[LLM Call]
    LLM --> RS

    HT -->|no LLM| RS
    DA -->|no LLM| RS

    RS --> EVT[SupervisorResponseChunkEvent]
    EVT --> FE[Frontend / Voice]

Flow summary: The UI Router selects a specialized node based on conversation context. Most nodes extract shared context, assemble a prompt from markdown fragments, call the LLM with streaming, and publish response chunks via the event bus. HITL and Acknowledgment nodes bypass the LLM entirely.

Component Responsibilities¶

Data Model¶

Content Authority Chain¶

The system uses a three-level authority hierarchy to determine what the LLM should prioritize:

Prompt Fragment System¶

Prompt Placeholders¶

Key Design Decisions¶

1. Specialized Nodes Over Monolithic UI Node¶

• Chosen: Six separate node files, each handling one response variant
• Rejected: Single user_interface_node with conditional branching
• Rationale: The original monolithic node grew to handle simple, complex, voice, HITL, and disambiguation variants with deeply nested conditionals. Splitting into focused nodes makes each variant independently testable and modifiable. The old user_interface.py still exists but is deprecated

2. Fragment-Based Prompts Over Hard-Coded Strings¶

• Chosen: Prompt content stored in .md files, assembled at runtime
• Rejected: Python string templates, Jinja2 templates
• Rationale: Non-technical stakeholders (product owners, content designers) can review and edit prompt files directly. Version control shows exact prompt text changes. Markdown is more readable than Python strings for long-form content

3. Streaming With Card Buffering¶

• Chosen: Buffer a small window (30–150 chars) during streaming to detect and replace card placeholders inline
• Rejected: Post-processing the full response after generation; sending cards as separate events
• Rationale: Users expect immediate streaming. Post-processing would add seconds of perceived latency. The small buffer window is a compromise — most text streams instantly while card placeholders get replaced before the user sees them

Interfaces and Contracts¶

Known Trade-offs and Debt¶