Frontend (UI)

Last updated: 2026-01-30

Frontend (UI)

This document describes the frontend user interface architecture, technologies used, component structure, state management, and development guidelines.

Technology Stack

The frontend is a modern single-page application (SPA) built with the following technologies:

Project Structure

The main frontend code resides in the frontend/src/ directory:

  • main.tsx: The main entrypoint of the application that renders the App component.
  • App.tsx: The root component that assembles the entire UI and contains the primary application logic.
  • /components: Contains all the reusable UI components (e.g., ChatInput, MessageList, Header).
  • /hooks: Holds custom React hooks that encapsulate complex logic. useChat.ts is the most important one.
  • /services: Contains specific, isolated client-side utilities, such as the image_service.ts for handling pasted images.
  • /types: Defines TypeScript types and interfaces used throughout the application.
  • /utils: Provides miscellaneous helper functions, such as for accessing local storage.
  • config.ts: Manages frontend-specific configuration, like the backend API URL.

State Management & Data Flow

The application’s state management and data flow are handled primarily through custom React hooks, avoiding the need for a larger state management library like Redux.

The useChat Hook

The useChat custom hook (hooks/useChat.ts) is the brain of the frontend. It is responsible for:

  • Managing the entire state of the chat, including the list of messages, the current input text, and loading status.
  • Handling all communication with the backend API via the fetch API. It calls endpoints like /chat/init, /chat, and /chat/emotion.
  • Implementing the user experience logic, such as adding the user’s message to the UI optimistically before the API call completes.
  • Managing file uploads by first sending files to the /files/upload endpoint.

Real-Time Events with SSE

The application uses Server-Sent Events (SSE) to receive real-time updates from the backend.

  • SSEProvider & useSSE: The App component is wrapped in an SSEProvider which establishes and manages the SSE connection to the /chat/{session_id}/events/listen endpoint. The useSSE hook allows components to listen for specific events pushed by the server.

Core Components

  • App.tsx: The top-level component that orchestrates the entire application. It initializes the useChat hook and renders all other major components.
  • MessageList.tsx: Renders the list of chat messages. It also conditionally renders interactive components like EmotionSelector or DropdownSelector when the agent requires user input.
  • ChatInput.tsx: The component for the message composer. It includes the text input, buttons for sending messages and attaching files, and the microphone for audio input.
  • MonsterDisplay.tsx: The component responsible for displaying the monster character animations.

Styling

The UI is styled using Tailwind CSS. The configuration in tailwind.config.js includes:

  • Custom fonts (Bellota, Borel).
  • Complex, variant-specific keyframe animations for UI elements. For example, there is a purple theme (souffleDeactivate) for the youth variant and a red theme (souffleDeactivateRed) for the adult variant. The active variant is determined by the CHATBOT_VARIANT environment variable passed from Vite’s configuration.

Running in Development

To run the frontend for local development:

  1. Navigate to the frontend directory: bash cd frontend
  2. Install the dependencies: bash npm install
  3. Run the development server: bash npm run dev This will start the Vite development server, typically available at http://localhost:5173. The frontend expects the backend API to be running concurrently.