Develop and extend
Concept Available

Web App Architecture and Data Flow

Pages compose shared feature scopes; Template scope controls API paths and navigation. Organization identity stays explicit in URLs and caches, while authenticated Web Chat and log hooks own streaming, cancellation, and recovery.

For
Frontend developers
On this page
  1. Shared Template scopes
  2. Routing and providers
  3. API and query contracts
  4. Loading and errors
  5. UI conventions
  6. Authenticated streaming exceptions
01

Shared Template scopes

Platform and Organization Template pages share ui/src/features/templates/. scope.ts supplies the scope-specific API base paths and navigation links. Shared panels, editors, and published views do not require a separate Platform Templates feature directory.

  1. 01.1

    Template routes: /dashboard/platform/templates; /dashboard/platform/templates/{template_key}; /dashboard/{organization_id}/settings?tab=templates; /dashboard/{organization_id}/settings/templates/{template_key}

02

Routing and providers

The root layout composes URL-state, query, tooltip, and application providers. Public authentication routes bypass protected context. Organization View uses /dashboard/[orgId], while Platform View uses /dashboard/platform with no active Organization.

03

API and query contracts

Use the shared API singleton, feature-local Zod schemas, and centralized query keys. The client sends cookies and transforms snake_case responses to camelCase. New Organization-scoped queries must include Organization identity in their key or join the provider eviction set used during a real Organization switch.

04

Loading and errors

Use route loading and error files for page-blocking router work. Component-owned queries keep their initial loading, retry, search, pagination, and refetch states local. A hook error does not automatically reach an App Router error boundary.

05

UI conventions

Prefer Server Components until client-owned behavior is required. Use branded ConfirmationDialog for confirmation flows and shared shadcn Select primitives for option selectors. Mutations invalidate affected list and detail families; avoid effect chains for user-triggered workflows.

06

Authenticated streaming exceptions

Ordinary application requests use the shared API client. Agent logs and dashboard Web Chat are streaming exceptions with dedicated hooks. Agent logs use the dedicated Next route-handler proxy. Web Chat connects to its authenticated, Organization-scoped SSE endpoint through use-web-chat.ts.

  1. 06.1

    The streaming hooks share SSE connection handling through use-sse-stream.ts. Authentication supplies and refreshes bearer tokens, including recovery after an unauthorized response. Stream ownership includes abort behavior and bounded reconnection; it must not be treated as an unauthenticated bypass of the normal session model.

  2. 06.2

    Web Chat history and updates belong to the Agent's Chat feature. Frames are keyed by message identity, so a delivery-status or cancellation update changes the existing message rather than adding a duplicate. Keep this separate from normal resource-query patterns and the log proxy's transport details.

  3. 06.3

    ui/src/features/templates/scope.ts: Template scope and navigation.

  4. 06.4

    ui/src/features/agents/hooks/use-web-chat.ts: Web Chat requests and stream.

  5. 06.5

    ui/src/features/agents/hooks/use-sse-stream.ts: shared SSE handling.

  6. 06.6

    ui/src/features/agents/hooks/use-agent-log-stream.ts: Agent log stream.

Documentation