Frontend Development Guide

Tech Stack

Technology	Version	Purpose
React	18.3.1	UI framework
TypeScript	~5.7.2	Type safety
Vite	6.0.3	Build tool and dev server
TanStack React Query	5.62.0	Data fetching and caching
Zustand	5.0.2	Client state management
react-router-dom	7.18.1	Routing
Bootstrap	5.3.8	CSS framework
Chart.js	4.4.7	Data visualization
xterm.js	6.0.0	Terminal emulation
react-markdown	10.1.0	Markdown rendering

Project Structure

frontend/
├── public/                     # Static assets
├── src/
│   ├── main.tsx                # Entry point
│   ├── App.tsx                 # Root component with routing
│   ├── api/                    # API client layer (30+ typed modules)
│   │   ├── client.ts           # ApiClient (retry, timeout, error handling)
│   │   ├── request.ts          # Shared request helpers
│   │   ├── index.ts            # Re-exports
│   │   └── ...                 # One module per backend domain:
│   │                           # auth, dashboard, messages, sessions, admin,
│   │                           # analysis, remote, governance, tenant, sso,
│   │                           # prompts, projects, toolAccounts, autonomous,
│   │                           # compliance, encryptionKeys, featureFlags,
│   │                           # feishuConfig, fs, insights, mappingRules,
│   │                           # modelGateway, notificationChannels, policy,
│   │                           # projectCategories, report, roi, smtpConfig,
│   │                           # system, users, workspace, alerts,
│   │                           # aiAgentSettings (plus colocated *.test.ts)
│   ├── components/
│   │   ├── common/             # 49 shared UI components
│   │   ├── layout/             # Layout shells (WorkLayout, ManageLayout)
│   │   ├── features/           # Page-level components
│   │   │   ├── analysis/       # TrendAnalysis, AnomalyDetection, ROIAnalysis, UsageForecast, EnterpriseReport
│   │   │   ├── management/     # Admin pages plus their modals/editors (UserManagement, TenantManagement, SecurityCenter, …)
│   │   │   ├── settings/       # SSOSettings, BrandingSettings, AiAgentSettings, NotificationIntegration, FeishuConfig
│   │   │   └── compliance/     # DataRetention, ComplianceReport
│   │   └── work/               # Work-mode specific components
│   ├── hooks/                  # React Query hooks
│   ├── store/                  # Zustand global store
│   ├── i18n/                   # Translations (en/zh/ja/ko)
│   ├── types/                  # TypeScript interfaces
│   ├── utils/                  # Formatters, helpers
│   └── styles/                 # CSS (Bootstrap overrides)
├── vite.config.ts              # Build configuration
├── tsconfig.json
└── package.json

Development Workflow

# Install dependencies
npm install

# Start dev server (port 3000, proxies API to localhost:19888)
npm run dev

# Build for production (outputs to ../static/js/dist/)
npm run build

# Run tests
npm run test

# Lint
npm run lint

The dev server runs on port 3000 with /api and /auth requests proxied to the Flask backend on port 19888.

Routing

Work Mode (/work/*) — All authenticated users

3-panel layout (WorkLayout): session list | workspace (iframe) | assist panel

Route	Component	Description
/work	Workspace	Main AI coding environment
/work/sessions	SessionList	Session history
/work/prompts	Prompts	Prompt templates
/work/usage	UsageOverview	Personal usage stats
/work/insights	InsightsReport	AI-generated insights
/work/files	PersonalFiles	Personal file browser
/work/alerts	UserAlerts	Personal alert center
/work/autonomous	AutonomousDev	Autonomous development workflows (feature-gated)
/work/workspace	—	Workspace iframe anchor

Manage Mode (/manage/*) — Admin only

Sidebar navigation layout (ManageLayout)

Route	Component	Description
/manage/dashboard	Dashboard	Admin overview
/manage/analysis	—	Redirects to /manage/analysis/trend
/manage/analysis/trend	TrendAnalysis	Token trends
/manage/analysis/request-dashboard	RequestDashboard	Request-level usage dashboard
/manage/analysis/anomaly	AnomalyDetection	Usage anomalies
/manage/analysis/roi	ROIAnalysis	ROI metrics
/manage/analysis/forecast	UsageForecast	Usage forecasting
/manage/analysis/enterprise-report	EnterpriseReport	Enterprise usage report
/manage/analysis/conversation-history	ConversationHistory	Conversation history browser
/manage/messages	Messages	Message browser
/manage/audit	AuditCenter	Audit log viewer
/manage/quota	QuotaAlerts	Quota & alerts
/manage/compliance	Compliance	Data retention
/manage/security	SecurityCenter	Security settings
/manage/policy/rules	PolicyRouteGuard	Policy rules management
/manage/users	UserManagement	User CRUD
/manage/tenants	TenantManagement	Multi-tenant
/manage/tenants/:id	TenantDetail	Tenant detail
/manage/projects	ProjectManagement	Project CRUD
/manage/remote/machines	RemoteMachineManagement	Machine management
/manage/settings/sso	SSOSettings	SSO configuration
/manage/settings/branding	BrandingSettings	Branding and appearance
/manage/settings/api-keys	APIKeyManagement	API key proxy management
/manage/settings/encryption-keys	EncryptionKeyManagement	Encryption key management
/manage/settings/ai-agent	AiAgentSettings	AI agent settings
/manage/settings/notification-integration	NotificationIntegration	Notification integrations
/manage/settings/smtp	SmtpConfig	SMTP configuration
/manage/settings/model-gateway	ModelGatewayConfig	Model gateway (LiteLLM-compatible)
/manage/settings/feishu	FeishuConfig	Feishu integration

Legacy routes (/dashboard, /messages, etc.) redirect admins to /manage/... and non-admins to /work/....

Data Flow

API Client (src/api/client.ts)
  → React Query hooks (src/hooks/)
    → Page components (src/components/features/)

The ApiClient class wraps fetch with:

• Automatic retry (up to 3 attempts with exponential backoff)
• 30-second timeout
• Credential inclusion (credentials: 'include')
• Friendly error messages per HTTP status code

React Query is configured with 1-minute stale time and single retry.

State Management

Zustand store (src/store/index.ts) with localStorage persistence (key: open-ace-store):

Persisted:

• theme (light/dark), language (en/zh/ja/ko)
• appMode (work/manage), sidebarCollapsed
• workspaceTabs — multi-tab workspace state (type, sessionId, machineId, etc.)

Non-persisted:

• user, isAuthenticated, authLoading
• workspaceFullscreen

Selectors are exported for granular subscriptions (useUser, useTheme, useAppMode).

Internationalization

Custom lightweight i18n in src/i18n/index.ts:

import { t } from '@/i18n'

// Usage
t('common.save', language)

Supports 4 languages: en (default), zh, ja, ko. ~800+ keys per language.

Help documents also exist per language in src/components/work/docs/.

Build Configuration

vite.config.ts key settings:

Setting	Value
Base path	/static/js/dist/
Output	../static/js/dist
Dev server port	3000
API proxy	/api, /auth → http://localhost:19888
Target	ES2020
Minifier	esbuild (drops console.log in prod)

Path aliases: @ → src/, @api → src/api/, @components → src/components/, etc.

Chunk splitting: react-vendor, router, query, zustand, charts, date-fns, api, components, hooks, store, utils, i18n, plus auto-chunks for each lazy-loaded page.

Common Components

All in src/components/common/:

Component	Description
Button	Configurable button with variants, sizes, loading state
Card, StatCard	Content cards and stat display
Modal, ConfirmModal	Dialog modals with size variants
Select, SearchableSelect	Dropdown selects
Tabs, TabList, Tab, TabPanels	Tab navigation
Loading, Skeleton, SkeletonCard	Loading indicators
Error, EmptyState	Error and empty states
Badge, StatusBadge, CountBadge	Status indicators
Progress, CircularProgress	Progress indicators
TextInput, Textarea, Checkbox	Form inputs
Dropdown, SplitButton	Dropdown menus
Avatar, AvatarUploader	User avatars
Tooltip	Tooltips
ToastContainer, useToast	Toast notifications
ModeSwitcher	Work/Manage mode toggle
SessionDetailContent	Session detail viewer
LazyCharts	Lazy-loaded chart components

Adding a New Feature

1. API layer — Create src/api/myFeature.ts with typed API calls
2. Hooks — Create src/hooks/useMyFeature.ts with React Query hooks
3. Component — Create src/components/features/MyFeature.tsx (lazy-loaded)
4. Route — Add route in App.tsx under WorkRoutes or ManageRoutes
5. i18n — Add keys to all 4 languages in src/i18n/index.ts
6. Types — Add interfaces to src/types/index.ts