## Why After the backend-frontend refactoring (commits `0591b00` through `8c7affc`), the codebase gained proper directory structure but several files grew into monoliths. The `main` branch (pre-refactor baseline at `5ed5e1c`) kept pages thin by delegating to extracted components. On `dev`, new features were added inline, causing pages and routers to absorb responsibilities that belong in components or services. ### Problem Files (Frontend) | File | Lines | Problem | |------|-------|---------| | `pages/ToolWorkshopPage.tsx` | **1,269** | Merged 3 tab components inline (ToolTypes, ToolConfigs, ConfigFolders) | | `pages/ConfigProfilesPage.tsx` | **1,611** | List, detail, edit, create, and mobile views all in one file | | `pages/TerminalPage.tsx` | **571** | Session tabs, keyboard shortcuts, fullscreen, mobile overlay, special keys all inline | | `pages/RepoWorkspacePage.tsx` | **505** | File editor, git toolbar, workspace header, sidebar logic inline | | `pages/SettingsPage.tsx` | **284** | Settings nav + multiple setting sections inline | | `pages/SshKeysPage.tsx` | **277** | List and create inline | ### Problem Files (Backend) | File | Lines | Problem | |------|-------|---------| | `api/tool/tool_instances.py` | **2,900** | CRUD, Docker lifecycle, WebSocket proxy, terminal sessions, instance proxy all in one router | | `api/project/git_repositories.py` | **1,588** | HTTP endpoints mixed with git command orchestration | | `api/config/config_profiles.py` | **842** | CRUD + validation + resolver + mount/include management | ### What `main` Did Differently `main` at `5ed5e1c`: - `ToolWorkshopPage.tsx` = **77 lines** (just a tab switcher, tabs imported from `features/tool-workshop/`) - `TerminalPage.tsx` = **38 lines** (just a wrapper around `TerminalComponent`) - `api/tool_instances.py` = **284 lines** (HTTP endpoints only) - `api/terminal.py` = **158 lines** (separate WebSocket router) ## What Changes Restore the **thin-page / thin-router / fat-component** pattern from `main`, adapted to current `dev` features: 1. **Frontend page extraction** — Split monolithic pages into: - Page shell (orchestrator, 50-150 lines) - Tab components (for tabbed pages) - List / Detail / Edit / Create components (for CRUD pages) - Mobile-specific views (extracted, not inline) 2. **Backend router slimming** — Split `tool_instances.py` into: - `tool_instances.py` — CRUD endpoints only - `tool_lifecycle.py` — Start/stop/restart/delete logic - Move terminal WebSocket back to dedicated `terminal.py` 3. **Git repository router** — Extract git command orchestration into `services/git/` ## Capabilities ### New Capabilities - None (pure structural refactor) ### Modified Capabilities - `frontend-structure`: Pages become orchestrators; components carry the UI logic - `backend-structure`: Routers become HTTP-only; services carry business logic ## Impact - **Frontend**: New `features/tool-workshop/` tab components, new `features/config-profiles/` components, `features/terminal/` session manager, etc. - **Backend**: New `api/tool/tool_lifecycle.py`, `api/tool/terminal.py`, slimmer `api/tool/tool_instances.py` - **Tests**: Test files may need import path updates (component moved → test follows) ## Exclusions (Already Done / Out of Scope) - Directory structure already exists (`features/`, `services/`, etc.) - Schema extraction already done (`schemas/` subpackages) - Model subpackages already done (`models/` subpackages) - API router subpackages already done (`api/tool/`, `api/project/`, etc.) - File naming already done (kebab-case APIs, PascalCase pages) - No behavioral changes to any endpoint or UI flow - No database schema changes - No new features