TUCAN UI — Frontend Surface for the TUCAN Agent Stack

TUCAN UI — Frontend Surface for the TUCAN Agent Stack

The browser surface that turns the TUCAN dispatcher's persisted state, the orchestrator's tool calls, and the Mastra SSE events into a chat + tools + drawers UX inside the doctor (and other clinical) portals.

Path note (2026-07-02): the live implementation is ddx-web/src/features/tucan/ plus the doctor-portal assistant/ + tucan-intelligence/ routes (all present). The ddx-tucan-ui/ design-spec pack referenced throughout the body below was PARKED to _claude-archive/parked-2026-06-14/stale-docs-specs/ddx-tucan-ui/ (superseded by ddx-documentation as the sole docs SoT). The design principles it captured still hold; treat its ddx-tucan-ui/NN-*.md line references as archive-only, not repo-root files.

Business Purpose

TUCAN is the AI core of Dudoxx HMS — the dispatcher, orchestrator, agent types, tool catalog, and RAG pipeline. None of that ships to a customer without a UI. The TUCAN UI surface is where the doctor sees streaming agent output, approves tool calls, watches runtime metrics, pins information into the workspace, and threads voice input through the same approval policy as typed chat.

The investor pitch — "AI-augmented clinic" — lives entirely on this surface. The clinical buyer's first reaction to a demo happens here. And the per-tool unit economics (transparently shown via tucan-consumption-pricing) are the trust mechanism that turns "AI" from a marketing word into a budget line.

Audiences

• Investor: shows how the agent core (W3 dispatcher/orchestrator/tools) becomes a product moment — streaming events, tool calls visible to the clinician, voice operator, runtime cost meter.
• Clinical buyer (doctor/nurse/receptionist): a clinician's view of how AI is invoked, approved, and audited; nothing executes silently — every clinical write goes through approval.
• Developer/partner: explains the chat surface (TUCANEnhancedChat), SSE event consumption, UI-action handlers, the assistant route, and the TUCAN-intelligence dashboard route inside the doctor portal.
• Internal (ops/support): where to look when a tool call doesn't render, when SSE events drop, or when an approval modal doesn't appear.

Architecture

Two product surfaces inside the doctor portal

1. Assistant — portal/doctor/(with-nav)/assistant/ — primary chat list + per-session chat. The session list page is a Server Component (assistant/page.tsx:1-20) that prefetches sessions via backendFetch and delegates rendering to <AssistantListClient>.
2. TUCAN Intelligence — portal/doctor/(with-nav)/tucan-intelligence/ — analytic dashboards over TUCAN usage (dashboard/), per-portfolio context (portfolios/), patient-document chat (patient-docs/), and intelligence search (search/). The layout owns its own breadcrumb (TucanIntelligenceBreadcrumb.tsx), header (TucanIntelligenceHeader.tsx), and sidebar (TucanIntelligenceSidebar.tsx).

Both surfaces are subroutes of the doctor portal's (with-nav)/ route group — they inherit the chrome via createRoleLayout(DOCTOR_CONFIG, DoctorNav) (see [[multi-portal-architecture]]).

features/tucan/ — the UI feature module

ddx-web/src/features/tucan/ is the canonical location for every TUCAN-aware UI component. Subdirectories:

Event model — SSE first

The browser never calls ddx-api directly. The flow is:

backend agent → ddx-api SSE channel → Next.js EventSource bridge →
features/tucan/sse/ consumer → ui-actions handler → component render

The full SSE contract is documented at packages/ddx-sse-contract/ (@ddx/sse-contract, 4.1.0). The seven canonical UI actions (modal, notification, info container, document viewer, highlight, scroll-to, audio feedback) are documented in ddx-tucan-ui/07-tucan-runtime-ui-tools.md.

Voice operator

TUCAN Voice Operator (in features/tucan/voice/) emits transcript fragments that the user can dispatch into the main chat. Every voice-originated message goes through the same approval policy as typed input — there is no voice-bypass for clinical writes. Documented constraint from ddx-tucan-ui/README.md:39-40.

North-Star spec lives alongside

ddx-tucan-ui/ (separate folder at repo root) is the design source of truth:

• 01-ui-north-star.md — product principles and clinical-assistant feel.
• 02-layout-and-navigation.md — shell, sidebar, left voice panel, right info drawer, responsive layout.
• 03-composer-and-controls.md — composer, uploads, voice controls, permissions, model/tool settings.
• 04-agent-streaming-and-clinical-workflows.md — runtime stream, tool calls, workflow process, approvals, safety UX.
• 05-visual-system-and-motion.md — dark clinical visual system, restrained motion.
• 06-implementation-checklist.md — handoff checklist.
• 07-tucan-runtime-ui-tools.md — mapping to existing ddx-web / ddx-api UI action concepts.
• mock/index.html — dependency-free static mock; opens in any browser to demo the composer, drawers, voice operator, and UI-tool handlers without a backend.

Tech Stack & Choices

Rejected: client-side polling for runtime state (would race with SSE), per-tool SDK exposed to the browser (would let the client invoke arbitrary tools without backend authorization), embedding TUCAN UI in a separate iframe (would break i18n, RBAC, and the design system).

Data Flow

1. Doctor opens /<locale>/portal/doctor/assistant → Server Component fetches sessions via backendFetch<AgentSession[]>('agent/sessions?…') (assistant/page.tsx:1-20).
2. Doctor selects a session → routes to /assistant/sessions/<id> (under same (with-nav)/assistant/ group) → TUCANEnhancedChat mounts.
3. Composer submit → server action posts to ddx-api → dispatcher routes (see [[tucan-dispatcher]] — agent type is persisted state, not an LLM choice).
4. Backend agent emits ui:action SSE events (modal, notification, etc.) and tool trace events. The Next.js SSE bridge forwards to the browser.
5. features/tucan/sse/ consumer parses events → dispatches to features/tucan/ui-actions/ handler → handler invokes a component (modal/notification/info-card/viewer/etc.).
6. Tool calls render as cards in the message list (e.g. DifferentialEvidenceCard.tsx); approval-required tools render an approval prompt; the user accepts or rejects.
7. Runtime metrics (tokens, cost) stream into the Usage drawer (features/tucan/usage/).

Implicated Code

• ddx-tucan-ui/README.md:1-40 — design pack overview and production-boundary reminders (the browser must talk to TUCAN through Next.js + SSE; never directly to ddx-api:6100).
• ddx-tucan-ui/01-ui-north-star.md — product principles.
• ddx-tucan-ui/04-agent-streaming-and-clinical-workflows.md — runtime stream + tool calls + approvals.
• ddx-tucan-ui/07-tucan-runtime-ui-tools.md — canonical UI-action vocabulary.
• ddx-web/src/features/tucan/chat/TUCANEnhancedChat.tsx:1-50 — chat shell composer + pinned items (877 LOC; module-level Client Component).
• ddx-web/src/features/tucan/chat/TUCANEnhancedMessageList.tsx:1-50 — message list + tool-call render (1415 LOC).
• ddx-web/src/app/[locale]/portal/doctor/(with-nav)/assistant/page.tsx:1-20 — server prefetch of agent/sessions + delegation to AssistantListClient.
• ddx-web/src/app/[locale]/portal/doctor/(with-nav)/tucan-intelligence/layout.tsx — intelligence dashboard chrome (its own breadcrumb/header/sidebar).
• ddx-web/src/features/tucan/index.ts — feature barrel for the TUCAN UI module.
• packages/ddx-sse-contract/ — canonical SSE contract (@ddx/sse-contract, 4.1.0) the UI subscribes to.

Operational Notes

• Browser must never call ddx-api directly — every backend round-trip is via Next.js (BFF for REST, Next.js SSE bridge for events). Reaffirmed in ddx-tucan-ui/README.md:37-38 and enforced in ddx-web/CLAUDE.md:20-41.
• useDebugAttrs for TUCAN components — TUCAN components are NOT yet auto-mapped in CATEGORY_BY_NAME (ddx-web/CLAUDE.md:253). Pass category: 'content' explicitly when adding a new TUCAN component so the Debug Inspector tree groups it correctly.
• ddxId convention — tucan-<role>-<surface> (e.g. tucan-enhanced-chat, tucan-chat-header, flowagent-send-btn). Naming guidance in ddx-web/CLAUDE.md:237.
• Voice never bypasses approval — clinical writes from voice transcripts go through the same approval policy as typed input (ddx-tucan-ui/README.md:39-40).
• UI-action vocabulary is bounded — adding a new action category requires updates in both features/tucan/ui-actions/ (frontend) and the backend ui:action emitter, and a contract bump in packages/ddx-sse-contract/.
• Two surfaces, one design system — Assistant and TUCAN Intelligence are sibling surfaces inside (with-nav)/; they share the doctor chrome but each owns its own internal navigation. Do not cross-import internal sidebars/headers — those are surface-specific.
• Mock is intentionally backend-free — ddx-tucan-ui/mock/index.html is for design iteration; it never reaches the API and must remain safe to open locally.

Related Topics

• TUCAN Dispatcher — backend state machine that the UI mirrors.
• TUCAN Context Builder — what the UI sees as "current patient/visit" context.
• TUCAN Orchestrator — backend tool execution that drives message-list render.
• TUCAN Assistant — the canonical agent surfaced under portal/doctor/assistant/.
• TUCAN RAG Tools — RAG-backed evidence cards (e.g. DifferentialEvidenceCard.tsx).
• AI Assistant ↔ Visit Wiring — how TUCAN UI binds to the current visit (W4).
• Doctor Portal — host portal for both TUCAN surfaces.
• Nurse Portal — also hosts a TUCAN entry (portal/nurse/ai/).