Developer Guides
Frontend Development
Work on the SOIT React Router frontend and route-centered workspace surfaces.
The SOIT frontend lives under soit/web and uses TypeScript, React 19, React Router, Tailwind CSS 4, Zustand, React Query, React Flow, i18next, and Playwright.
Local commands
npm install
npm run dev # dev server with hot reload
npm run typecheck
npm run build
npm run test:e2e # Playwright (run npx playwright install chromium once)Frontend structure
The app is route-centered: workspace routes expose the product areas, and shared layers support them.
| Folder | Responsibility |
|---|---|
app/routes | Workspace and admin route surfaces |
app/components | Shared UI and business components |
app/services | API clients and service wrappers (REST / WS / SSE) |
app/stores | Zustand stores |
app/hooks | Custom hooks (often wrapping React Query) |
app/i18n | Translation setup and resources |
app/styles | Styles and theme integration |
app/config | Runtime configuration |
app/types | Shared TypeScript types |
Route map
The main product routes and what they serve:
/agents— agent workbench (definitions, versions, bindings, publish)./chat— threaded conversational execution with streaming./workflow— DAG design surface built on React Flow./knowledge— bases, documents, and analytics./tasks— execution queue and per-task detail control./observe— runs, approvals, feedback, audits, and run detail replay./plugin,/mcp,/skill— plugin lifecycle and capability views./model— ModelHub provider and catalog configuration./setting,/system,/auth,/notifications— admin and account surfaces.
Working rules
- Frontend code contains no backend business rules — services call
api/v1and render its envelopes. - API response envelopes are stable (
success,code,data,request_id,run_id); clients should surfacerun_idwhere users may need to jump to Observe. - All user-visible copy goes through i18next resources.
- Critical flows need Playwright coverage; the frontend gate (
typecheck,build,test:e2e) is blocking — see Testing and Quality Gate.