headquarter/openspec/changes/reorganize-long-files/proposal.md at ce8b5dc86de39b75ee7168086f6e87df7e00c483

Files

T

Developer d472c41092 docs: add OpenSpec spec for reorganize-long-files

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

2026-06-05 10:19:27 +00:00

3.6 KiB

Raw Blame History

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:

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)
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
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

3.6 KiB Raw Blame History

Why