Lesson 16.30: Building Production AI Interfaces

01 Production Reality: Moving Beyond the Simple Chat Bubble

In previous lessons, we established an enterprise-grade backend foundation: clean layered FastAPI architecture (Lesson 27), resilient Celery and Redis distributed task queues (Lesson 28), and Server-Sent Events (SSE) token streaming with cryptographic webhooks (Lesson 29). Now, we must pair that authoritative backend with a production frontend interface designed for mission-critical enterprise workflows.

A widespread engineering misconception is that an AI chat interface consists merely of a text input box and two alternating colored speech bubbles (user on right, assistant on left). In production enterprise software, that naive abstraction instantly collapses:

A production-grade AI interface carries five non-negotiable core responsibilities:

Our goal today is to architect a highly modular, reusable AI chat interface ready to power Byteion Knowledge Assistant, ERP Copilot, and Legal Document Analyzer.

02 End-to-End AI Interface Architecture & Boundary of Authority

In a secure enterprise architecture, boundaries between frontend presentation and backend authority must remain strictly enforced:

03 Part A: Message Anatomy & The Finite State Machine Lifecycle

In traditional messaging apps, a message is simply { role: "user", content: "..." }. In an enterprise AI system, an assistant message is an authoritative, multi-faceted payload:

The most crucial architectural element is the Message Lifecycle State Machine. An assistant message must never be represented by a blunt binary loading: true/false flag. It traverses distinct non-terminal and terminal states:

Why is granular status differentiation critical?

• When a user explicitly halts generation (cancelled), the UI must not flash a red error banner, but smoothly note “Generation stopped by user”.
• When a mobile client experiences cellular handover (interrupted), the partially streamed paragraphs must be preserved, offering a clean “Connection interrupted — Retry” CTA.
• When the backend returns a 429 Rate Limit (failed), a distinct error card with backoff indicators should guide the user.

04 TypeScript Domain Models: types.ts

We establish a strict, type-safe contract in src/features/chat/types.ts:

// src/features/chat/types.ts

export type MessageRole = "user" | "assistant";

export type MessageStatus =
  | "streaming"
  | "complete"
  | "failed"
  | "interrupted"
  | "cancelled";

export type ToolStatus =
  | "queued"
  | "running"
  | "completed"
  | "failed";

export type Citation = {
  id: string;
  title: string;
  url: string;
  excerpt?: string;
};

export type ToolActivity = {
  id: string;
  label: string;
  status: ToolStatus;
};

export type ChatMessage = {
  id: string;
  role: MessageRole;
  content: string;
  status?: MessageStatus;
  citations: Citation[];
  toolActivities: ToolActivity[];
  createdAt: string;
};

export type ChatStatus =
  | "idle"
  | "streaming"
  | "failed"
  | "interrupted"
  | "cancelled";

Notice the key architectural distinction: ChatStatus models the global interaction state of the entire conversation session (Is the composer disabled? Should the Stop button appear?), whereas MessageStatus isolates the lifecycle of a specific individual assistant response. This separation unlocks robust multi-message retries and seamless conversation switching.

05 Part B: Conversation State Management & Reducer Transitions

During active streaming inference, the client can receive 15 to 50 token events every second, alongside concurrent tool activity badges and provenance citations.

Managing this high-frequency stream with fragmented useState variables inevitably produces race conditions, dropped frames, and stale closures. A structured state transition pipeline is required:

The reducer pattern guarantees that incoming wire events pass through deterministic pure functions, making behavior easily verifiable via unit tests and eliminating accidental UI state desynchronization.

06 Production Project Structure: Modular Component Architecture

Rather than piling all state and UI logic into a single monolithic component, we adhere to Byteion's enterprise feature-folder structure:

This modular layout enables independent component unit testing, prevents cross-module leakage, and allows seamless integration into diverse design systems.

07 Part C: Streaming Event Contract Between Backend & Frontend

The foundation of reliable real-time communication is an authoritative, versioned event contract. Provider-specific wire frames are normalized by the backend into stable domain events:

08 Part D: Network Chunks vs. SSE Events — The consumeSSE() Stream Reader

A frequent architectural flaw in naive streaming implementations is equating an incoming TCP network chunk directly to an authoritative SSE wire event.

We utilize the battle-tested eventsource-parser library to implement our defensive consumer in src/features/chat/lib/stream.ts:

// src/features/chat/lib/stream.ts
import {
  createParser,
  type EventSourceMessage,
} from "eventsource-parser";

export type ChatStreamEvent = {
  type: string;
  data: Record<string, unknown>;
  id?: string;
};

export async function consumeSSE(
  response: Response,
  onEvent: (event: ChatStreamEvent) => void,
): Promise<void> {
  if (!response.ok) {
    throw new Error(`HTTP request failed with status: ${response.status}`);
  }
  if (!response.body) {
    throw new Error("Streaming response body is unavailable on this platform.");
  }

  const reader = response.body.getReader();
  const decoder = new TextDecoder("utf-8");

  const parser = createParser({
    onEvent(event: EventSourceMessage) {
      let parsedData: unknown;
      try {
        parsedData = JSON.parse(event.data);
      } catch {
        throw new Error("Server emitted non-JSON SSE payload.");
      }

      if (
        typeof parsedData !== "object" ||
        parsedData === null ||
        Array.isArray(parsedData)
      ) {
        throw new Error("Invalid event payload: expected JSON object.");
      }

      onEvent({
        type: event.event || "message",
        data: parsedData as Record<string, unknown>,
        id: event.id,
      });
    },
  });

  try {
    while (true) {
      const { value, done } = await reader.read();
      if (done) {
        parser.feed(decoder.decode()); // Flush trailing bytes
        break;
      }
      parser.feed(decoder.decode(value, { stream: true }));
    }
  } finally {
    reader.releaseLock();
  }
}

The responsibility of consumeSSE() is strictly isolated: it converts raw TCP byte chunks into validated domain events. It maintains zero knowledge of chat states or UI lifecycles, ensuring complete architectural reusability.

09 Part E: Crafting the Reusable useChat() Hook

We now encapsulate all network orchestration, state transitions, and error recovery into an ergonomic custom hook in src/features/chat/hooks/useChat.ts:

// src/features/chat/hooks/useChat.ts
import { useRef, useState } from "react";
import { consumeSSE } from "../lib/stream";
import type {
  ChatMessage,
  ChatStatus,
  Citation,
  ToolActivity,
} from "../types";

function createAssistantMessage(id: string): ChatMessage {
  return {
    id,
    role: "assistant",
    content: "",
    status: "streaming",
    citations: [],
    toolActivities: [],
    createdAt: new Date().toISOString(),
  };
}

export function useChat(accessToken: string) {
  const [messages, setMessages] = useState<ChatMessage[]>([]);
  const [status, setStatus] = useState<ChatStatus>("idle");
  const [error, setError] = useState<string | null>(null);

  const controllerRef = useRef<AbortController | null>(null);
  const lastPromptRef = useRef<string | null>(null);

  function updateAssistant(
    messageId: string,
    update: (message: ChatMessage) => ChatMessage,
  ) {
    setMessages((prev) =>
      prev.map((msg) => (msg.id === messageId ? update(msg) : msg)),
    );
  }

  async function runPrompt(prompt: string, addUserMessage: boolean): Promise<void> {
    if (controllerRef.current) return; // Prevent concurrent double submissions

    const assistantId = crypto.randomUUID();
    const controller = new AbortController();
    controllerRef.current = controller;
    lastPromptRef.current = prompt;

    if (addUserMessage) {
      const userMessage: ChatMessage = {
        id: crypto.randomUUID(),
        role: "user",
        content: prompt,
        citations: [],
        toolActivities: [],
        createdAt: new Date().toISOString(),
      };
      setMessages((prev) => [...prev, userMessage, createAssistantMessage(assistantId)]);
    } else {
      setMessages((prev) => [...prev, createAssistantMessage(assistantId)]);
    }

    setError(null);
    setStatus("streaming");
    let completed = false;

    try {
      const response = await fetch("/v1/answers/stream", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${accessToken}`,
        },
        body: JSON.stringify({ prompt }),
        signal: controller.signal,
      });

      await consumeSSE(response, (event) => {
        const data = event.data;

        // 1. Token Event: Append text progressively
        if (event.type === "token" && typeof data.text === "string") {
          updateAssistant(assistantId, (msg) => ({
            ...msg,
            content: msg.content + data.text,
          }));
        }

        // 2. Citation Event: Deduplicate and store source metadata
        if (event.type === "citation") {
          if (
            typeof data.id === "string" &&
            typeof data.title === "string" &&
            typeof data.url === "string"
          ) {
            const citation: Citation = {
              id: data.id,
              title: data.title,
              url: data.url,
              excerpt: typeof data.excerpt === "string" ? data.excerpt : undefined,
            };
            updateAssistant(assistantId, (msg) => ({
              ...msg,
              citations: msg.citations.some((c) => c.id === citation.id)
                ? msg.citations
                : [...msg.citations, citation],
            }));
          }
        }

        // 3. Tool Status Event: Upsert intermediate agent stage
        if (event.type === "tool_status") {
          if (
            typeof data.id === "string" &&
            typeof data.label === "string" &&
            typeof data.status === "string"
          ) {
            const activity: ToolActivity = {
              id: data.id,
              label: data.label,
              status: data.status as ToolActivity["status"],
            };
            updateAssistant(assistantId, (msg) => ({
              ...msg,
              toolActivities: [
                ...msg.toolActivities.filter((a) => a.id !== activity.id),
                activity,
              ],
            }));
          }
        }

        // 4. Completed Event: Mark message successful
        if (event.type === "completed") {
          completed = true;
          updateAssistant(assistantId, (msg) => ({ ...msg, status: "complete" }));
          setStatus("idle");
        }

        // 5. Error Event: Surface structured model exception
        if (event.type === "error") {
          throw new Error(
            typeof data.message === "string" ? data.message : "AI model request failed.",
          );
        }
      });

      // Handshake Invariant: If stream closed without completed event, mark interrupted
      if (!completed) {
        updateAssistant(assistantId, (msg) => ({ ...msg, status: "interrupted" }));
        setStatus("interrupted");
      }
    } catch (cause) {
      if (controller.signal.aborted) {
        updateAssistant(assistantId, (msg) => ({ ...msg, status: "cancelled" }));
        setStatus("cancelled");
      } else {
        const errorMsg = cause instanceof Error ? cause.message : "An unexpected failure occurred.";
        updateAssistant(assistantId, (msg) => ({ ...msg, status: "failed" }));
        setError(errorMsg);
        setStatus("failed");
      }
    } finally {
      if (controllerRef.current === controller) {
        controllerRef.current = null;
      }
    }
  }

  function sendMessage(prompt: string) {
    const trimmed = prompt.trim();
    if (!trimmed || controllerRef.current) return;
    void runPrompt(trimmed, true);
  }

  function stopGeneration() {
    controllerRef.current?.abort();
  }

  function retryLastMessage() {
    const prompt = lastPromptRef.current;
    if (!prompt || controllerRef.current) return;

    // Prune the failed/interrupted assistant bubble before retry
    setMessages((prev) =>
      prev.filter(
        (msg) =>
          !(
            msg.role === "assistant" &&
            (msg.status === "failed" ||
              msg.status === "interrupted" ||
              msg.status === "cancelled")
          ),
      ),
    );
    void runPrompt(prompt, false);
  }

  return {
    messages,
    status,
    error,
    sendMessage,
    stopGeneration,
    retryLastMessage,
  };
}

Key architectural achievements of this hook:

• The controllerRef.current guard completely blocks concurrent duplicate submissions even under rapid Enter clicks.
• retryLastMessage() cleanly prunes the failed assistant bubble before re-executing, preserving conversation symmetry without duplicating the user's prompt.
• If the TCP socket closes before an explicit completed event arrives, the status automatically falls back to interrupted, preventing false success states.

10 Part F: Assembling the Chat UI Component (ChatPage.tsx)

We wire our custom hook into a fully responsive, accessible, and polished user interface in src/features/chat/ChatPage.tsx:

// src/features/chat/ChatPage.tsx
import React, { useState } from "react";
import { useChat } from "./hooks/useChat";
import type { ChatMessage } from "./types";

type Props = {
  accessToken: string;
};

export function safeCitationHref(rawUrl: string): string | null {
  // Allow root-relative paths but reject protocol-relative (//) bypasses
  if (rawUrl.startsWith("/") && !rawUrl.startsWith("//")) {
    return rawUrl;
  }
  try {
    const parsed = new URL(rawUrl);
    if (parsed.protocol === "https:" || parsed.protocol === "http:") {
      return parsed.href;
    }
  } catch {
    // Malformed URL string
  }
  return null;
}

function MessageView({ message }: { message: ChatMessage }) {
  const isUser = message.role === "user";

  return (
    <article
      className={`rounded-2xl p-4 my-3 text-xs transition-all ${
        isUser
          ? "bg-cyan-500/10 border border-cyan-500/20 ml-8 text-foreground"
          : "bg-card border border-border mr-8 text-foreground"
      }`}
      aria-label={isUser ? "Your message" : "AI assistant response"}
    >
      <div className="flex items-center justify-between mb-2 pb-1 border-b border-border/50 text-[11px] text-muted-foreground">
        <span className="font-bold flex items-center gap-1.5">
          <i className={isUser ? "ti ti-user" : "ti ti-robot text-cyan-500"} />
          {isUser ? "You" : "Byteion AI Assistant"}
        </span>
        <time className="font-mono">{new Date(message.createdAt).toLocaleTimeString()}</time>
      </div>

      {/* Tool Execution Badges */}
      {message.toolActivities.length > 0 && (
        <ul className="space-y-1 mb-3" aria-label="Tool execution progress">
          {message.toolActivities.map((act) => (
            <li
              key={act.id}
              className="inline-flex items-center gap-1.5 rounded-md px-2 py-0.5 bg-muted/60 text-[11px] font-mono mr-2 text-muted-foreground"
            >
              {act.status === "running" && <i className="ti ti-loader animate-spin text-cyan-500" />}
              {act.status === "completed" && <i className="ti ti-check text-emerald-500" />}
              {act.status === "failed" && <i className="ti ti-x text-rose-500" />}
              <span>{act.label}</span>
            </li>
          ))}
        </ul>
      )}

      {/* Main Text Content */}
      <div className="leading-relaxed whitespace-pre-wrap font-sans">
        {message.content ||
          (message.status === "streaming" && (
            <span className="text-muted-foreground italic flex items-center gap-1">
              <i className="ti ti-cursor-text animate-pulse" /> Generating response...
            </span>
          ))}
      </div>

      {/* Grounded RAG Citations */}
      {message.citations.length > 0 && (
        <section className="mt-4 pt-3 border-t border-border/60" aria-label="Sources">
          <h4 className="text-[11px] font-bold text-muted-foreground uppercase tracking-wider mb-2 flex items-center gap-1">
            <i className="ti ti-files" /> Verified Sources
          </h4>
          <ol className="grid grid-cols-1 sm:grid-cols-2 gap-2">
            {message.citations.map((cite, idx) => {
              const safeHref = safeCitationHref(cite.url);
              return (
                <li
                  key={cite.id}
                  className="rounded-lg border border-border bg-muted/20 p-2 text-[11px] hover:border-cyan-500/40 transition-colors"
                >
                  <div className="font-bold flex items-center gap-1">
                    <span className="text-cyan-500">[{idx + 1}]</span>
                    {safeHref ? (
                      <a
                        href={safeHref}
                        target="_blank"
                        rel="noopener noreferrer"
                        className="hover:underline text-foreground"
                      >
                        {cite.title}
                      </a>
                    ) : (
                      <span className="text-muted-foreground">{cite.title}</span>
                    )}
                  </div>
                  {cite.excerpt && (
                    <p className="text-muted-foreground text-[10px] mt-1 line-clamp-2 italic">
                      &ldquo;{cite.excerpt}&rdquo;
                    </p>
                  )}
                </li>
              );
            })}
          </ol>
        </section>
      )}

      {/* Terminal Status Banners */}
      {message.status === "failed" && (
        <div className="mt-3 p-2 rounded-lg bg-rose-500/10 text-rose-500 text-[11px] flex items-center gap-1.5" role="status">
          <i className="ti ti-alert-circle" /> This response encountered a model failure.
        </div>
      )}
      {message.status === "interrupted" && (
        <div className="mt-3 p-2 rounded-lg bg-amber-500/10 text-amber-500 text-[11px] flex items-center gap-1.5" role="status">
          <i className="ti ti-wifi-off" /> The stream connection was terminated prematurely.
        </div>
      )}
      {message.status === "cancelled" && (
        <div className="mt-3 p-2 rounded-lg bg-muted text-muted-foreground text-[11px] flex items-center gap-1.5" role="status">
          <i className="ti ti-player-stop" /> Generation halted by user.
        </div>
      )}
    </article>
  );
}

export function ChatPage({ accessToken }: Props) {
  const [draft, setDraft] = useState("");
  const { messages, status, error, sendMessage, stopGeneration, retryLastMessage } =
    useChat(accessToken);

  function handleSubmit() {
    const trimmed = draft.trim();
    if (!trimmed || status === "streaming") return;
    sendMessage(trimmed);
    setDraft("");
  }

  return (
    <main className="max-w-3xl mx-auto flex flex-col h-[750px] rounded-2xl border border-border bg-card shadow-sm overflow-hidden">
      {/* Header */}
      <header className="px-5 py-3.5 border-b border-border bg-muted/20 flex items-center justify-between">
        <div>
          <h2 className="text-sm font-bold text-foreground">Byteion Knowledge Assistant</h2>
          <p className="text-[11px] text-muted-foreground">Ask questions grounded in enterprise data.</p>
        </div>
        <div className="flex items-center gap-2">
          <span
            className={`h-2 w-2 rounded-full ${
              status === "streaming" ? "bg-cyan-500 animate-ping" : "bg-emerald-500"
            }`}
          />
          <span className="text-[11px] font-mono capitalize text-muted-foreground">{status}</span>
        </div>
      </header>

      {/* Conversation Transcript */}
      <div className="flex-1 overflow-y-auto p-4 space-y-2" aria-label="Conversation history">
        {messages.length === 0 ? (
          <div className="h-full flex flex-col items-center justify-center text-center text-muted-foreground text-xs p-6">
            <i className="ti ti-message-dots text-3xl mb-2 text-cyan-500/50" />
            <p className="font-semibold text-foreground">No conversation yet</p>
            <p className="text-[11px] max-w-sm mt-1">
              Ask questions regarding company policies, financial reports, or code repositories.
            </p>
          </div>
        ) : (
          messages.map((msg) => <MessageView key={msg.id} message={msg} />)
        )}
      </div>

      {/* Accessible Live Region */}
      <p className="sr-only" role="status" aria-live="polite">
        {status === "streaming"
          ? "AI assistant is generating response."
          : status === "failed"
          ? "AI assistant request failed."
          : status === "interrupted"
          ? "AI response stream was interrupted."
          : status === "cancelled"
          ? "AI response generation was stopped."
          : ""}
      </p>

      {/* Global Error Alert & Retry Action */}
      {error && (
        <div className="mx-4 mb-2 p-2.5 rounded-xl border border-rose-500/30 bg-rose-500/10 flex items-center justify-between text-xs text-rose-500" role="alert">
          <span className="flex items-center gap-1.5">
            <i className="ti ti-alert-triangle" /> {error}
          </span>
          <button
            type="button"
            onClick={retryLastMessage}
            className="px-2.5 py-1 rounded-lg bg-rose-600 text-white font-bold hover:bg-rose-700 transition-colors text-[11px]"
          >
            Retry Question
          </button>
        </div>
      )}

      {/* Composer Input Form */}
      <form
        onSubmit={(e) => {
          e.preventDefault();
          handleSubmit();
        }}
        className="p-3.5 border-t border-border bg-background"
      >
        <div className="relative rounded-xl border border-border bg-card focus-within:border-cyan-500 transition-colors">
          <textarea
            value={draft}
            onChange={(e) => setDraft(e.target.value)}
            onKeyDown={(e) => {
              // Submit on Enter unless Shift is held or IME composition is active (e.g. Bengali typing)
              if (e.key === "Enter" && !e.shiftKey && !e.nativeEvent.isComposing) {
                e.preventDefault();
                handleSubmit();
              }
            }}
            placeholder="Ask a question about your documents... (Press Enter to send)"
            rows={2}
            className="w-full resize-none bg-transparent p-3 text-xs outline-none text-foreground placeholder:text-muted-foreground"
          />
          <div className="flex items-center justify-between px-3 py-2 border-t border-border/40 text-[11px] text-muted-foreground">
            <span>Shift + Enter for new line</span>
            {status === "streaming" ? (
              <button
                type="button"
                onClick={stopGeneration}
                className="inline-flex items-center gap-1 rounded-lg bg-rose-600 px-3 py-1.5 text-xs font-bold text-white hover:bg-rose-700 transition-colors"
              >
                <i className="ti ti-player-stop" /> Stop Generating
              </button>
            ) : (
              <button
                type="submit"
                disabled={!draft.trim()}
                className="inline-flex items-center gap-1 rounded-lg bg-cyan-600 px-3 py-1.5 text-xs font-bold text-white hover:bg-cyan-700 disabled:opacity-50 disabled:cursor-not-allowed transition-colors"
              >
                <span>Send</span> <i className="ti ti-send" />
              </button>
            )}
          </div>
        </div>
      </form>
    </main>
  );
}

12 Part G: Production AI UX — Why Showing Mere “Loading...” Fails

In traditional CRUD software, a generic loading spinner suffices because database round-trips resolve in milliseconds. In enterprise AI workflows, complex agentic reasoning chains can span anywhere from 5 to 60 seconds.

Leaving users staring at an opaque spinner breeds immediate suspicion of system failure. A production interface mandates explicit semantic feedback across every operational phase:

13 Part H: Streaming UX — Smart Scroll, Micro-Batching & Stop Control

Maintaining high-fidelity perceived performance during real-time token delivery requires three architectural implementations:

14 Part I: Citations, Grounding & RAG Transparency

Enterprise decision-makers require verifiable provenance. Suppose the model asserts: “Customers are entitled to cancel within 14 business days.” Compliance auditors demand to verify exactly which legal policy file backs up that assertion.

15 Part J: Model Output Rendering Security & XSS Defense

Raw generative AI completions must be treated as untrusted external user input:

A four-tier defense-in-depth sanitization protocol is mandatory:

1. Strict Markdown Sanitization: Pair react-markdown with rehype-sanitize to strip executable script tags and dangerous event handlers.
2. Scheme Whitelisting: Reject all schemes except verified http: and https:; aggressively neutralize javascript:, vbscript:, and data: URIs.
3. Link Isolation: Enforce target="_blank" alongside rel="noopener noreferrer" to protect window opener contexts.
4. Sandboxed Code Presentation: Render syntax-highlighted code inside inert, pre-formatted read-only containers.

16 Part K: Accessibility (a11y) & Screen Reader Engineering

Without deliberate architectural accommodation, a streaming chat interface is completely unusable for screen reader users.

The enterprise solution is Dual Region Separation:

• Transcript Container: Set to aria-live="off", allowing users to navigate and inspect completed paragraphs at their own reading pace.
• Dedicated Polite Announcer: A hidden <p className="sr-only" role="status" aria-live="polite"> region emitting milestone announcements only (“Generating” → “Completed” → “Stopped”).
• IME Composition Safety: Testing event.nativeEvent.isComposing prevents accidental form submissions during multi-keystroke phonetic scripts (e.g. Bengali typing).

17 Part L: Server-Side Conversation Persistence & PostgreSQL Schemas

Client-side React memory is strictly transient. In a production enterprise ecosystem, conversation threads must seamlessly persist across browser reloads, network reconnects, and cross-device handoffs.

The canonical relational schema implemented in PostgreSQL is defined below:

-- Canonical Database Schema for AI Conversation Management
CREATE TABLE conversations (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    tenant_id UUID NOT NULL,
    user_id UUID NOT NULL,
    title VARCHAR(255) NOT NULL DEFAULT 'New Conversation',
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

CREATE INDEX idx_conversations_tenant_user 
    ON conversations (tenant_id, user_id, updated_at DESC);

CREATE TABLE conversation_messages (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    conversation_id UUID NOT NULL REFERENCES conversations(id) ON DELETE CASCADE,
    role VARCHAR(20) NOT NULL CHECK (role IN ('user', 'assistant', 'system')),
    content TEXT NOT NULL,
    status VARCHAR(30) NOT NULL DEFAULT 'complete' 
        CHECK (status IN ('streaming', 'complete', 'failed', 'interrupted', 'cancelled')),
    sequence_number BIGINT NOT NULL,
    citations_payload JSONB DEFAULT '[]'::jsonb,
    tool_activities_payload JSONB DEFAULT '[]'::jsonb,
    token_usage_prompt INT DEFAULT 0,
    token_usage_completion INT DEFAULT 0,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    CONSTRAINT uq_conversation_sequence UNIQUE (conversation_id, sequence_number)
);

CREATE INDEX idx_messages_conversation 
    ON conversation_messages (conversation_id, sequence_number ASC);

The composite unique constraint on (conversation_id, sequence_number) guarantees absolute chronological determinism even under concurrent retries or duplicate network transmissions.

18 Client ID vs. Server ID Reconciliation Handshake

To preserve zero-latency perceived responsiveness, the client mounts an optimistic message bubble backed by a client-generated crypto.randomUUID() the instant the user presses Enter.

However, the backend authoritative database generates the canonical persistence UUID. How is this transition executed cleanly?

19 Part M: Automated Testing Pyramid — Unit, Integration & Playwright E2E

Testing real-time AI user interfaces differs fundamentally from traditional static forms, as tests must orchestrate asynchronous streaming sockets and state transitions:

A representative integration test using Vitest and React Testing Library:

// src/features/chat/__tests__/useChat.test.ts
import { renderHook, act } from "@testing-library/react";
import { describe, it, expect, vi } from "vitest";
import { useChat } from "../hooks/useChat";

describe("useChat Hook Integration", () => {
  it("should mount optimistic user message and stream tokens into assistant content", async () => {
    // Mock streaming response body emitting SSE frames
    const encoder = new TextEncoder();
    const stream = new ReadableStream({
      start(controller) {
        controller.enqueue(encoder.encode('event: token\ndata: {"text":"Byteion"}\n\n'));
        controller.enqueue(encoder.encode('event: token\ndata: {"text":" AI"}\n\n'));
        controller.enqueue(encoder.encode('event: completed\ndata: {"message_id":"1"}\n\n'));
        controller.close();
      },
    });

    vi.spyOn(global, "fetch").mockResolvedValueOnce(
      new Response(stream, {
        status: 200,
        headers: { "Content-Type": "text/event-stream" },
      }),
    );

    const { result } = renderHook(() => useChat("mock_token"));

    await act(async () => {
      result.current.sendMessage("Hello Byteion");
    });

    expect(result.current.messages).toHaveLength(2);
    expect(result.current.messages[0].role).toBe("user");
    expect(result.current.messages[0].content).toBe("Hello Byteion");
    expect(result.current.messages[1].role).toBe("assistant");
    expect(result.current.messages[1].content).toBe("Byteion AI");
    expect(result.current.messages[1].status).toBe("complete");
    expect(result.current.status).toBe("idle");
  });
});