Skip to content

Web Interface

Jump to bottom
github-actions[bot] edited this page Aug 3, 2026 · 3 revisions

Web Interface

Referenced Files in This Document

Table of Contents

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. Conclusion
  10. Appendices

Introduction

This document describes the Kairos MCP web interface, a React-based UI that provides user account management, dashboard and run workflows, protocol editing, skill bundle browsing, and extensible widget integrations. It explains the component architecture, page layouts, theming system, responsive design patterns, accessibility considerations, and the integration between frontend components and backend APIs. It also covers guidelines for developing custom widgets and UI extensions, as well as browser compatibility and performance optimization strategies.

Project Structure

The web interface is organized under src/ui with clear separation of concerns:

  • Pages define top-level routes and compose reusable components
  • Components encapsulate UI logic and presentation
  • Hooks provide stateful behavior and data access
  • Theme tokens define CSS variables for light/dark themes
  • i18n resources support internationalization
  • Utilities include helpers for adapters, markdown rendering, and editor extensions
  • The application entrypoint bootstraps routing, providers, and theme initialization
graph TB
A["App.tsx"] --> B["Layout.tsx"]
A --> C["HomePage.tsx"]
A --> D["RunsPage.tsx"]
A --> E["RunGuidedPage.tsx"]
A --> F["AccountPage.tsx"]
A --> G["ProtocolDetailPage.tsx"]
A --> H["ProtocolEditPage.tsx"]
A --> I["SkillBundlePage.tsx"]
B --> J["components/*"]
C --> K["hooks/*"]
D --> K
E --> K
F --> K
G --> K
H --> K
I --> K
L["theme/tokens*.css"] --> A
M["i18n/*"] --> A
N["lib/api.ts"] --> K
Loading

Diagram sources

Section sources

Core Components

  • Layout: Provides global navigation, header, sidebar, and content shell; integrates authentication context and theme switching.
  • HomePage: Entry point to dashboards, quick actions, and recent runs.
  • RunsPage: Lists and filters runs, supports pagination and status indicators.
  • RunGuidedPage: Orchestrates step-by-step guided flows using hooks for activation and forward steps.
  • AccountPage: Displays current user profile and preferences (e.g., theme).
  • ProtocolDetailPage and ProtocolEditPage: View and edit protocol definitions with rich text and validation.
  • SkillBundlePage: Browse and manage skill bundles with search and filtering.

Reusable components:

  • ChallengeCard: Presents challenge metadata and actions.
  • CopyButton: Copies content to clipboard with feedback.
  • ErrorAlert: Centralized error display with retry options.
  • RenderedMarkdown: Renders Markdown safely with syntax highlighting.
  • RichTextEditor: WYSIWYG editor with custom extensions.
  • SearchResultsSkeleton: Loading placeholders for search results.
  • SpaceSelect: Dropdown to select spaces for scoped operations.
  • StepFlowGraph: Visualizes workflow step transitions.
  • SurfaceCard: Card container with consistent elevation and padding.

Hooks:

  • useAuth: Authentication state, login/logout, and session checks.
  • useThemePreference: Persisted theme selection and toggling.
  • useActivate, useForwardStart, useForwardStep: Orchestrate activation and forward flows.
  • useProtocol: Fetch and mutate protocol data.
  • useReward: Submit rewards and fetch evaluations.
  • useRunSession: Manage active run sessions.
  • useSpaces: List and filter spaces.

API layer:

  • lib/api.ts: Centralized HTTP client configuration, request/response handling, and typed endpoints.

Theming:

  • tokens.css and theme-specific token files define CSS variables for colors, typography, spacing, and breakpoints.

Internationalization:

  • en.json and index.ts provide translation keys and loading utilities.

Utilities:

  • browse-adapters.ts: Helpers for adapter discovery and filtering.
  • confidence.ts: Confidence scoring helpers for UI displays.
  • rich-text-editor-extensions.ts: Editor plugins and behaviors.

Section sources

Architecture Overview

The UI is a single-page application bootstrapped by main.tsx and App.tsx. Routing composes pages within a shared Layout. Data fetching is centralized through lib/api.ts, which wraps HTTP calls and handles auth headers. Authentication integrates with OIDC via backend redirects and callbacks. Widget integrations are injected into the UI through server-side resource registration and JSON-RPC offerings.

sequenceDiagram
participant Browser as "Browser"
participant UI as "React UI"
participant API as "lib/api.ts"
participant Server as "HTTP Server"
participant Auth as "OIDC Provider"
Browser->>UI : Load app
UI->>Server : GET /api/me
Server-->>UI : User profile or redirect
UI->>Auth : Redirect to login if unauthenticated
Auth-->>Server : Callback with code
Server-->>UI : Session established
UI->>API : Request protected resource
API->>Server : HTTP call with bearer token
Server-->>API : Response payload
API-->>UI : Typed result
Loading

Diagram sources

Detailed Component Analysis

Application Shell and Routing

  • App.tsx configures routes and composes pages.
  • Layout.tsx provides global navigation, breadcrumbs, and content area.
  • kairos-page-sections.tsx organizes page sections and layout fragments.
classDiagram
class App {
+routes()
+providers()
}
class Layout {
+header()
+sidebar()
+content()
}
class HomePage
class RunsPage
class RunGuidedPage
class AccountPage
class ProtocolDetailPage
class ProtocolEditPage
class SkillBundlePage
App --> Layout : "wraps"
App --> HomePage
App --> RunsPage
App --> RunGuidedPage
App --> AccountPage
App --> ProtocolDetailPage
App --> ProtocolEditPage
App --> SkillBundlePage
Loading

Diagram sources

Section sources

Guided Run Flow

RunGuidedPage orchestrates activation and forward steps using dedicated hooks.

sequenceDiagram
participant Page as "RunGuidedPage"
participant HookA as "useActivate"
participant HookFS as "useForwardStart"
participant HookF as "useForwardStep"
participant API as "lib/api.ts"
participant Server as "HTTP Server"
Page->>HookA : Initialize activation
HookA->>API : POST /api/activate
API->>Server : Activate request
Server-->>API : Activation result
API-->>HookA : State update
Page->>HookFS : Start forward flow
HookFS->>API : POST /api/forward/start
API->>Server : Forward start
Server-->>API : Next step info
API-->>HookFS : Step state
Page->>HookF : Execute next step
HookF->>API : POST /api/forward/step
API->>Server : Step execution
Server-->>API : Step result
API-->>HookF : Update UI state
Loading

Diagram sources

Section sources

Account Management

AccountPage displays user profile and allows preference changes such as theme selection.

flowchart TD
Start(["Open AccountPage"]) --> FetchProfile["Fetch profile via API"]
FetchProfile --> ProfileLoaded{"Profile loaded?"}
ProfileLoaded --> |No| ShowError["Show ErrorAlert"]
ProfileLoaded --> |Yes| RenderUI["Render profile fields"]
RenderUI --> ChangeTheme["Toggle theme"]
ChangeTheme --> SavePrefs["Persist theme preference"]
SavePrefs --> End(["Done"])
ShowError --> Retry["Retry action"]
Retry --> FetchProfile
Loading

Diagram sources

Section sources

Dashboard and Runs

HomePage provides quick actions and overview metrics. RunsPage lists runs with filtering and pagination.

classDiagram
class HomePage {
+quickActions()
+recentRuns()
}
class RunsPage {
+filters()
+pagination()
+statusIndicators()
}
class ChallengeCard
class SearchResultsSkeleton
class SpaceSelect
HomePage --> ChallengeCard : "displays"
HomePage --> SearchResultsSkeleton : "loading states"
RunsPage --> SpaceSelect : "scope selection"
RunsPage --> ChallengeCard : "run cards"
Loading

Diagram sources

Section sources

Protocol Editing

ProtocolDetailPage shows protocol details; ProtocolEditPage enables editing with rich text and validation.

sequenceDiagram
participant Detail as "ProtocolDetailPage"
participant Edit as "ProtocolEditPage"
participant HookP as "useProtocol"
participant API as "lib/api.ts"
participant Server as "HTTP Server"
Detail->>HookP : Read protocol
HookP->>API : GET /api/protocol/ : slug
API->>Server : Fetch protocol
Server-->>API : Protocol data
API-->>HookP : State update
Detail->>Edit : Navigate to edit
Edit->>HookP : Update protocol
HookP->>API : PUT /api/protocol/ : slug
API->>Server : Save changes
Server-->>API : Success response
API-->>Edit : Confirm saved
Loading

Diagram sources

Section sources

Skill Bundle Browsing

SkillBundlePage provides search, filtering, and viewing of skill bundles.

flowchart TD
Start(["Open SkillBundlePage"]) --> Query["Build query params"]
Query --> Fetch["GET /api/skills/bundles"]
Fetch --> Results{"Results available?"}
Results --> |No| EmptyState["Show empty state"]
Results --> |Yes| RenderList["Render list with cards"]
RenderList --> Filter["Apply filters"]
Filter --> Pagination["Navigate pages"]
Pagination --> End(["Done"])
Loading

Diagram sources

Section sources

Widget System and Extensibility

The server registers UI resources and offers for specific flows (spaces, activate, forward). Widgets can inject HTML, CSS, and scripts into the UI.

sequenceDiagram
participant Client as "Browser"
participant UI as "React UI"
participant Server as "HTTP Server"
participant MCP as "MCP Offerings"
Client->>UI : Load page
UI->>Server : GET /mcp/ui/offers
Server->>MCP : list-offerings-for-ui
MCP-->>Server : Offers list
Server-->>UI : Offers JSON
UI->>Server : GET /mcp/ui/resources
Server-->>UI : Injected HTML/CSS/JS
UI->>UI : Render widget content
Loading

Diagram sources

Section sources

Dependency Analysis

Frontend dependencies:

  • React components depend on hooks for state and side effects.
  • Hooks rely on lib/api.ts for HTTP requests.
  • Theming tokens are consumed across components via CSS variables.
  • i18n resources are loaded at startup and used by components.

Backend integration points:

  • Authentication uses OIDC redirect and callback endpoints.
  • Protected routes require bearer tokens set by middleware.
  • Static UI assets are served by the HTTP server.
  • MCP UI offerings and resources are exposed via JSON-RPC and resource endpoints.
graph TB
subgraph "Frontend"
UI["React Components"]
Hooks["Custom Hooks"]
API["lib/api.ts"]
Theme["tokens.css + theme tokens"]
I18N["i18n resources"]
end
subgraph "Backend"
HTTP["HTTP Routes"]
Auth["OIDC Auth"]
MCP["MCP Handlers"]
Static["Static UI Assets"]
end
UI --> Hooks
Hooks --> API
UI --> Theme
UI --> I18N
API --> HTTP
HTTP --> Auth
HTTP --> MCP
HTTP --> Static
Loading

Diagram sources

Section sources

Performance Considerations

  • Prefer memoization and stable references in hooks to avoid unnecessary re-renders.
  • Use skeleton loaders for heavy lists and search results to improve perceived performance.
  • Defer non-critical widget injections until after initial render.
  • Minimize network requests by batching where possible and leveraging caching headers from the server.
  • Optimize images and assets; consider lazy-loading off-screen components.
  • Keep theme token updates minimal; prefer CSS variable switches over inline styles.

[No sources needed since this section provides general guidance]

Troubleshooting Guide

Common issues and resolutions:

  • Authentication failures: Verify OIDC redirect and callback endpoints; ensure bearer token propagation via middleware.
  • Widget injection errors: Check MCP offerings endpoint and resource registration; validate HTML/CSS/JS payloads.
  • API errors: Inspect lib/api.ts error handling paths and server route responses.
  • Theme not applying: Confirm tokens.css and theme token files are loaded and CSS variables are correctly scoped.
  • i18n missing keys: Ensure en.json includes required keys and index.ts loads translations before rendering.

Section sources

Conclusion

The Kairos MCP web interface combines a modular React architecture with robust backend integrations for authentication, MCP offerings, and static asset serving. Its theming system, internationalization, and reusable components enable a consistent and accessible user experience. The widget system facilitates extensibility by injecting UI resources into key flows. Following the guidelines here will help maintain performance, responsiveness, and accessibility while extending functionality through custom widgets and UI enhancements.

[No sources needed since this section summarizes without analyzing specific files]

Appendices

Guidelines for Developing Custom Widgets and UI Extensions

  • Register UI resources via server-side registration modules to expose HTML, CSS, and JS.
  • Implement MCP offerings listing to inform the UI about available widgets.
  • Follow security best practices: sanitize injected content and restrict script execution scope.
  • Test widget rendering across browsers and devices; ensure keyboard navigation and screen reader support.
  • Use existing hooks and API layer to interact with backend services consistently.

Section sources

Browser Compatibility and Mobile Responsiveness

  • Leverage CSS variables for theming and responsive breakpoints defined in tokens files.
  • Validate layout on common mobile viewports; ensure touch-friendly interactions.
  • Avoid deprecated APIs; test on latest stable versions of major browsers.
  • Use progressive enhancement for advanced features; degrade gracefully when unsupported.

Section sources

KAIROS MCP

Clone this wiki locally