Frontend Architecture

frontend/src/
├── main.tsx                      # React 19 entry (Admin SPA)
├── App.tsx                       # ConfigProvider + AuthProvider + ThemeProvider + StreamProvider + Router
├── router/index.tsx              # BrowserRouter + three-layer ErrorBoundary
├── layouts/AppLayout.tsx         # Main layout (sidebar + content area + file panel trigger)
│
├── stores/
│   ├── authContext.tsx           # Authentication state
│   ├── streamContext.tsx         # SSE stream state (admin)
│   ├── fileWorkspaceContext.tsx  # File panel state
│   └── themeContext.tsx          # Multi-theme switching + Antd ThemeConfig
│
├── services/api.ts               # Unified API client
│
├── types/index.ts                # Shared types (Message / MessageBlock / Subagent / etc.)
│
├── styles/
│   ├── global.css                # Global styles / scrollbars / markdown
│   ├── themes.css                # Multi-theme CSS variable definitions
│   └── theme.ts                  # Fallback JS constants (CSS variables take precedence)
│
├── utils/
│   ├── csvParse.ts               # CSV/TSV state machine parser
│   ├── fileKind.ts               # Extension → kind classification
│   └── timezone.ts               # Timezone utilities
│
├── pages/
│   ├── Login.tsx                 # Split-panel login/register page
│   ├── AdminServices/index.tsx   # Service management (4 tabs)
│   ├── Scheduler/index.tsx       # Scheduled tasks (Admin / Service dual tabs)
│   ├── WeChat/index.tsx          # Admin WeChat onboarding
│   ├── Settings/
│   │   ├── index.tsx             # SettingsLayout (sidebar menu)
│   │   ├── PromptPage.tsx        # System Prompt + Memory & Soul + Capability Prompts
│   │   ├── SubagentPage.tsx
│   │   ├── PackagesPage.tsx      # Per-user venv
│   │   ├── InboxPage.tsx
│   │   └── GeneralPage.tsx       # API Keys + timezone + theme + Advanced switches + BatchRunner embedded
│   └── Chat/
│       ├── index.tsx             # Main chat page
│       ├── chat.module.css       # CSS Modules (--jf-* variables)
│       ├── markdown.ts           # Sole rendering pipeline (including <<FILE:>> handling)
│       ├── useSmartScroll.ts     # Smart scroll hook
│       ├── types.ts              # StreamBlock union types
│       └── components/
│           ├── ThinkingBlock.tsx
│           ├── ToolIndicator.tsx
│           ├── SubagentCard.tsx
│           ├── StreamingMessage.tsx
│           ├── MessageBubble.tsx
│           ├── ApprovalCard.tsx
│           ├── ImageAttachment.tsx
│           ├── VoiceInput.tsx
│           └── PlanTracker.tsx
│
├── components/
│   ├── FilePanel.tsx
│   ├── FilePreview.tsx           # Multi-type file viewer
│   ├── FileTreePicker.tsx        # Visual file/script selector
│   ├── HeaderControls.tsx
│   ├── LogoLoading.tsx
│   ├── SplitToggle.tsx
│   ├── ApiKeyWarning.tsx         # Guidance modal when no LLM key configured
│   ├── ErrorBoundary.tsx         # The only class component in the entire codebase
│   └── modals/
│       ├── BatchRunner.tsx       # Embedded in GeneralPage
│       ├── SoulSettings.tsx
│       ├── SubagentManager.tsx
│       ├── SystemPromptEditor.tsx
│       └── UserProfileEditor.tsx
│
└── service-chat/                 # Vite second entry (Consumer side)
    ├── main.tsx
    ├── ServiceChatApp.tsx
    ├── ServiceToolBadge.tsx      # Friendly tool status bar (replaces admin's ToolIndicator)
    ├── streamHandler.ts          # Lightweight SSE handler (no HITL/subagent)
    ├── serviceApi.ts             # Consumer API (decoupled from services/api.ts)
    └── serviceChat.module.css

<BrowserRouter>
  <Routes>
    <Route path="/login" element={<PublicRoute><Login/></PublicRoute>} />
    <Route element={
      <ErrorBoundary scope="app-layout">
        <ProtectedRoute><AppLayout/></ProtectedRoute>
      </ErrorBoundary>
    }>
      <Route path="/" element={
        <ErrorBoundary scope="chat"><ChatPage/></ErrorBoundary>
      } />
      <Route path="/settings" element={
        <ErrorBoundary scope="settings"><SettingsLayout/></ErrorBoundary>
      }>
        <Route index element={<Navigate to="/settings/prompt" replace/>} />
        <Route path="prompt" element={<PromptPage/>} />
        <Route path="subagents" element={<SubagentPage/>} />
        <Route path="packages" element={<PackagesPage/>} />
        <Route path="batch" element={<Navigate to="/settings/general" replace/>} />
        <Route path="services" element={<AdminServicesPage/>} />
        <Route path="scheduler" element={<SchedulerPage/>} />
        <Route path="wechat" element={<WeChatPage/>} />
        <Route path="inbox" element={<InboxPage/>} />
        <Route path="general" element={<GeneralPage/>} />
      </Route>
    </Route>
    <Route path="*" element={<Navigate to="/" replace/>} />
  </Routes>
</BrowserRouter>

async function request<T>(method: string, path: string, body?: unknown): Promise<T>

type SSEEvent =
  | { type: 'token'; content: string }
  | { type: 'thinking'; content: string }
  | { type: 'tool_call'; name: string; args: string }
  | { type: 'tool_call_chunk'; args_delta: string }
  | { type: 'tool_result'; name: string; content: string }
  | { type: 'subagent_call'; name: string; task: string }
  | { type: 'subagent_call_chunk'; args_delta: string }
  | { type: 'subagent_start'; name: string }
  | { type: 'subagent_token'; content: string; agent: string }
  | { type: 'subagent_thinking'; content: string; agent: string }
  | { type: 'subagent_tool_call'; name: string; args: string; agent: string }
  | { type: 'subagent_tool_chunk'; args_delta: string }
  | { type: 'subagent_tool_result'; name: string; content: string; agent: string }
  | { type: 'subagent_end'; name: string; result: string }
  | { type: 'interrupt'; actions: unknown[]; configs: unknown[] }
  | { type: 'done' }
  | { type: 'error'; content: string }

SSE callback → useRef directly mutates blocks array (avoids setState per-token)
            → requestAnimationFrame throttled re-render (~60fps)
            → Batch update to React state
            → StreamingMessage (React.memo) avoids unnecessary re-renders

ChatPage (pages/Chat/index.tsx)
├── Conversation list (createPortal → #sider-slot)
├── Message area
│   ├── MessageBubble (history messages)
│   │   └── BlocksRenderer (msg.blocks priority → fallback to legacy logic)
│   ├── StreamingMessage (streaming container, React.memo)
│   │   ├── ThinkingBlock (collapsible)
│   │   ├── ToolIndicator (tool calls, expandable args/result)
│   │   └── SubagentCard (subagent timeline rendering)
│   └── ApprovalCard (HITL: file diff / Plan editing)
├── Input area
│   ├── ImageAttachment (paste/drag/file select)
│   ├── VoiceInput (toggle: click start → click stop → auto-transcribe)
│   ├── Capability switches / Plan Mode / Model selector
│   └── Send/Stop button
└── useSmartScroll (pause auto-scroll when user scrolls up, resume at bottom)