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
• JetBrains Mono as the typography direction

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, lib/i18n, and lib/home/content modules.

Web GUI migration reality

webgui/ is still mid-migration. It already has the modern baseline, but some screens still rely on older global CSS.

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