module-organisation

To organize React code by responsibility, separate capabilities, commands, services, application state, hooks, components, and utilities into distinct directories to prevent business logic from leaking into the UI.

Business logic leaks into components when a codebase lacks clear layer boundaries. Separating tools, commands, services, state, hooks, and components into distinct directories isolates rendering concerns from orchestration logic.

To add a new tool capability, create a file like src/tools/[Name]Tool/[Name]Tool.tsx, export it as a named constant, and register it in src/tools.ts to maintain per-tool subdirectories.

Use .tsx file extensions to signal rendering concerns and .ts for non-rendering logic. This distinction helps separate capabilities, services, and pure utility functions from TUI components.

Yes, you can trace UI behavior by following directory conventions for tools, services, and state selectors. This structure isolates external system integrations and allows you to trace disk operations explicitly.

The best way to manage AppState is to maintain a single AppState source within a dedicated state/ directory. This prevents implicit state coupling and avoids logic leakage into UI components.