#Frontend Integration

The SciLaxy web frontend is a React application built with Next.js, Zustand for state management, and TanStack Query for server state.

#Architecture

The frontend follows a layered architecture:

Components (UI only)
    ↓
Hooks (useSciLaxyChat, useChannelSelectors, ...)
    ↓
Core (business logic: chat handlers, auth, session)
    ↓
Service (HTTP/SSE clients) + Store (Zustand)

• Components render UI and dispatch actions via hooks
• Hooks provide fine-grained selectors and actions
• Core contains business logic (streaming handlers, auth flow, channel status)
• Service handles HTTP requests and SSE connections
• Store manages client-side state with Zustand + Immer

#State Management

State is managed with Zustand using the slices pattern:

#Selector Pattern

Always use selectors to avoid unnecessary re-renders:

// Good — only re-renders when isLogged changes
const isLogged = useSciLaxy((s) => s.isLogged)

// Good — useShallow for object destructuring
const { user, token } = useSciLaxy(
  useShallow((s) => ({ user: s.user, token: s.token }))
)

// Bad — subscribes to ALL state changes
const store = useSciLaxy()

#Streaming Handlers

Streaming events from SSE are processed by specialized handlers:

SSE Event → sseClient → connectionActions → handler → Zustand store

#Chunk Buffering

streaming_chunk and thinking_chunk events are buffered and flushed at requestAnimationFrame cadence (~60fps) rather than updating state on every event. This prevents UI jank during fast streaming.

Non-chunk events (like node_start, agent_end) flush any pending chunks synchronously before processing.

#Handler Types

#Internationalization

The frontend supports English (en), Chinese (zh), and Japanese (ja). Translations are organized by module:

Usage in components:

const { t } = useTranslation()
<Button>{t('common.ok')}</Button>

#Theming

SciLaxy supports light and dark themes via next-themes. The design system uses Tailwind CSS with a consistent token palette:

• Surfaces use semi-transparent backgrounds (bg-neutral-100/60, dark:bg-white/[0.04])
• Borders are subtle (border-neutral-200/60, dark:border-neutral-800/60)
• Text uses text-[13px] for body, text-xs for hints
• Radius is rounded-lg for cards, rounded-sm for inputs

All scrollable containers use the custom-scrollbar class for consistent cross-browser styling.