Frontend System

Shared baseline

The repository uses a root pnpm workspace for webgui/, docs/, and the Ink tui/. uv remains the Python dependency manager; Makefile targets are thin aliases over pnpm and uv-backed commands.

Both docs/ and webgui/ were initialized from:

pnpm dlx shadcn@latest init --preset b2CQzAxv8 --template next

b2CQzAxv8 is the preset slug used at initialization time; if it is unavailable in the registry later or produces different output, each app's local components.json is the authoritative component contract.

That gives both apps a common baseline:

• Next.js App Router
• Tailwind v4
• CSS-variable theming
• the current shadcn preset
• local-first monospace typography without build-time Google Fonts fetches

Component rule

When we add shadcn components with pnpm dlx shadcn@latest add ..., the CLI reads each app’s local components.json. That means components should inherit the existing preset instead of drifting visually.

Modularity rule

Small files are not a goal by themselves, but the frontend should be split when it improves clarity. Good reasons to split a file:

• route file mixes loading, copy, and layout
• a single component owns too many unrelated concerns
• review becomes harder because one file includes several mental models
• locale-aware or feature-aware copy becomes easier to test in isolation

The docs app now follows that pattern with separate components/home, components/feedback, components/layout, components/ui/primitives, lib/i18n, and lib/home/content modules. The Web GUI control room follows the same direction: the top-level component should stay a state/render coordinator while view files, shell chrome, dashboard polling, action handlers, request helpers, primitives, and typed per-locale English/Turkish copy live in focused modules. React component files use PascalCase names so component boundaries are visible in reviews; copy, formatting, hooks, and request helpers keep role-based lowercase names.

Web GUI migration reality

webgui/ is still mid-migration. It already has the modern baseline, but some screens still rely on older global CSS. The first control-room split and main view-copy catalog are in place; future work should keep extracting typed view models, catalog-aware helper lines, and screen-scoped styling instead of re-growing the coordinator.

The current split includes state-hooks, view-model, action-request, formatting, diagnostics-formatting, context-formatting, loading panels, focused PascalCase view modules, shell chrome, primitives, and typed English/Turkish copy modules under webgui/src/components/control-room/. webgui/src/components/ControlRoom.tsx is the public facade and should not grow into a second implementation file.

Web GUI i18n rule

Web GUI render-boundary copy uses next-intl. The app wires the next-intl/plugin, request config, locale routing, typed messages, and a client provider under webgui/src/i18n/. Components should prefer useTranslations("controlRoom.section") and local view-model helpers instead of importing a whole copy catalog. Keep observer/API/dashboard JSON keys stable in English because those keys are runtime contracts, not UI strings.

Docs i18n rule

Docs stay on Fumadocs i18n with /en/... and /tr/... routes. Do not move docs onto next-intl only because Web GUI uses it; the docs app already has content routing, localized MDX, and navigation copy modules that match Fumadocs' contract.

Safe migration rules:

• migrate screen by screen
• prefer shadcn primitives and Tailwind utilities
• keep route handlers thin
• avoid adding new global CSS when a component can own the change

Route handler rule

Next.js route handlers in webgui/ should validate inputs and then delegate to the Python runtime contract. They should not become an alternative business-logic layer.

Docs UX rule

For the docs app specifically:

• make locale support explicit
• keep navigation predictable
• avoid overloaded landing pages
• keep feedback messaging unambiguous about browser-local drafts and manual GitHub issue links