Developer
d472c41092
Create SDD proposal, spec, and tasks for splitting monolithic pages and routers into focused components and services. Targets: - Frontend pages: 50-150 lines max (from 300-1600) - Backend routers: 300-400 lines max (from 800-2900) - Follow main branch pattern: thin pages + extracted components Quality gates: tsc, build, py_compile, file size limits
74 lines
3.6 KiB
Markdown
74 lines
3.6 KiB
Markdown
## 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
|