React Frontend

The frontend is a single-page application built with React and Vite, served as static files by gui.py. It contains no server-side rendering and requires no Node.js runtime in production.

Technology Stack

Library	Version	Role
React	19.3	Component framework
React Router	7.18	Client-side routing
Vite	6.x	Development server and bundler
TypeScript	5.x	Type checking
ECharts	6.1	Data visualization
@xyflow/react	12.x	Visual node scheduler canvas
motion	13.x	Animation transitions
CodeMirror	6.x	Embedded YAML / JSON editors
lucide-react	1.45	Iconography

Requires Node.js >=22.12.0 (defined in frontend/package.json under engines).

Directory Architecture

frontend/src/
├── main.tsx           # App entry and router configuration
├── app/               # Layout chrome, navbar, search index, preferences
├── pages/             # Page view components
├── components/        # Reusable design system components
├── api/               # WebSocket client, types, generated contracts
├── config/            # Dynamic form models and edit queue
├── scheduler/         # Visual graph nodes, ports, layout algorithms
├── mind/              # Mind calculator modules
├── fleet-tech/        # Fleet technology views
├── resources/         # Resource flow analytics
├── stock/             # Stock exchange interfaces
├── remote/            # Remote pairing dialogs
├── i18n*.ts           # Localization strings and dev utilities
└── styles/            # Global stylesheets and theme tokens

Client-Side Routes

Path	View
/	Home dashboard (instance list)
/announcement	Announcements
/interface	Interface preferences
/remote	Remote access settings
/settings	System settings
/updater	Upstream updater
/configs	Instance management
/dev	Developer utilities
/i/:instance/overview	Instance overview
/i/:instance/task/:task	Task configuration forms
/i/:instance/statistics	Performance and drop statistics
/i/:instance/stock-exchange	Stock exchange ledger
/i/:instance/task/SchedulerProgram	Visual scheduler canvas
/i/:instance/task/MindCalculator	Mind calculator
/i/:instance/task/FleetTechnology	Fleet technology

Legacy routes (/logs, /resources, /scheduler, /mind-calculator) redirect to preserve existing bookmarks.

Consuming API Contracts

import { api } from '../api/client'

const list = await api.request('instances.list', {})

• frontend/src/api/generated.ts is generated by dev_tools.export_api_schema, defining method names and request/response interfaces.
• frontend/src/api/contract.json provides a comprehensive JSON Schema for automated validation.
• Never edit generated files manually. Re-export schemas when backend endpoints change.

api.request handles request ID generation, timeouts, error code mapping, and reconnection prompts.

State Architecture

State is partitioned across three layers:

Layer	Implementation	Scope
Server State	Subscriptions + RPC results	Instance status, resource gauges, telemetry
Edit State	config/EditQueue.ts	Uncommitted configuration adjustments
UI State	localStorage + navbar state	Themes, density settings, navigation routes

Configuration Edit Queue

Form adjustments do not dispatch network requests per keystroke:

1. Input changes register in EditQueue.
2. Edits to identical paths coalesce.
3. Batched changes commit via config.patch with revision checks.
4. Concurrent conflicts prompt users to reload without overwriting external edits.

View teardown awaits queue flushing to prevent data loss on rapid navigation.

Localization (i18n)

• i18n.resources.ts manages runtime strings, with zh-CN as the baseline locale.
• i18n.dev.ts flags missing keys in development environments.
• Task parameter descriptions load from module/config/i18n/*.json via schema.get.

When authoring new UI views, provide both zh-CN and en-US strings.

Visual Scheduler Canvas

Modules under src/scheduler/ power the custom visual scheduler:

• Node schemas derive from module/scheduler/ models; the frontend handles layout and editing.
• Square ports govern sequence ordering; round ports handle typed data flow.
• Canvas state is managed by React Flow, committing modifications to the document model.
• Edits validate via scheduler.program.validate before applying.

Styling Conventions

• Global CSS design tokens reside in styles/.
• Theme toggles consume CSS variables; avoid hardcoding hex colors inside components.
• Responsive breakpoints collapse navigation sidebars into single-column layouts on mobile viewports.

Local Frontend Development

npm ci --prefix frontend
npm run dev --prefix frontend        # Connects to live backend on port 25548
npm run dev:mock --prefix frontend   # Runs against mock service without live backend

The Vite server binds to 127.0.0.1, proxying requests to the backend. dev:mock enables UI authoring without risk to live configurations.

Testing Suites

Suite	Command	Scope
Type Check	npm run typecheck --prefix frontend	TypeScript type evaluation
Unit Tests	npm test --prefix frontend	Components, hooks, utilities
End-to-End	npm run test:e2e --prefix frontend	Live backend testing
Mock End-to-End	npm run test:e2e:mock --prefix frontend	Mock service testing
Stock Exchange	npm run test:e2e:stock --prefix frontend	Stock trade workflows

Production Builds

npm run build --prefix frontend

• Runs tsc -b followed by vite build; compilation errors fail the build immediately.
• Outputs compile to frontend/dist, served statically by gui.py.