headquarter/openspec/changes/repo-restructure/spec.md

Spec: Repository Restructuring and Modularization

Overview

Restructure the Headquarter monorepo into a modular, maintainable architecture where every source file has a single responsibility and stays within 300 lines (target: 100–200). No behavior changes. No new features. Pure structural reorganization with standardized naming conventions.

Scope: Frontend (apps/web/src/) and backend (apps/api/src/) Non-goals: Technology swaps, feature additions, database migrations, CI/CD changes Target file size: 100–200 lines; hard limit 300 lines

---

Naming Conventions (MUST follow)

Layer	File Naming	Component/Function Naming	Example
React page components	PascalCase matching exported name	GitHistoryPage	GitHistoryPage.tsx
React feature components	PascalCase matching exported name	FileBrowser	FileBrowser.tsx + FileBrowser.module.css
React UI primitives	PascalCase matching exported name	Button, Dialog	Button.tsx + Button.module.css
React hooks	camelCase	useTheme, useApiQuery	useTheme.ts
Frontend API modules	kebab-case	—	tool-configs.ts
Frontend utilities	kebab-case	camelCase functions	terminal-protocol.ts
Frontend types	kebab-case	PascalCase interfaces	session.ts
CSS modules	kebab-case matching component	—	file-browser.module.css
Backend routers	snake_case	snake_case handlers	tool_instances.py
Backend services	snake_case	snake_case functions	docker_compose.py
Backend models	snake_case	PascalCase classes	tool_instance.py
Backend tests	snake_case prefixed with test_	—	test_tool_instances.py

CSS Modules rule: Every React component with significant styling gets its own .module.css file. Global styles live in styles/ and only contain resets, tokens, and layout foundations.

---

Acceptance Criteria

AC-1: No Monolithic Files Remain

GIVEN the codebase after restructuring
WHEN we count lines in every .ts, .tsx, .py, and .css file under src/
THEN no file exceeds 300 lines
AND the average file size under each domain directory is under 200 lines

Test: Run find src -type f | xargs wc -l | sort -rn — verify top result ≤ 300.

AC-2: Types Are Centralized and Deduplicated

GIVEN a domain type such as Session or ToolInstance
WHEN a developer searches for its definition
THEN exactly one definition exists under types/
AND api/sessions.ts and state/sessions.tsx both import from types/session.ts
AND no API module defines types inline

Test: Search for interface Session — expect 1 result. Search for interface ToolInstance — expect 1 result.

AC-3: Styles Are Modular

GIVEN the frontend build
WHEN styles.css is checked
THEN it does not exist (deleted)
AND global styles live in styles/global.css (resets + tokens + layout)
AND component styles live in .module.css files co-located with components
AND page styles live in styles/pages/{page-name}.css for page-specific layout only
AND syntax highlighting styles live in styles/syntax-highlight.css

Test: test -f src/styles.css fails. find src/styles -name "*.css" | wc -l ≥ 5.

AC-4: Backend Routers Contain Only HTTP Concerns

GIVEN any router file under api/
WHEN reading its contents
THEN it contains only: route definitions, dependency injection, request/response models, and thin handler functions
AND no Docker CLI calls, no Git subprocess calls, no file I/O, no compose file mutation
AND all business logic delegates to services/ modules

Test: grep -n "subprocess\|docker\|compose\|os\." apps/api/src/api/*.py returns zero matches.

AC-5: Backend Services Are Focused

GIVEN the services/ directory
WHEN listing files
THEN each service module has a single responsibility (e.g., container lifecycle, tunnel management, compose generation)
AND services/docker.py does not exist (split into focused modules)

Test: test -f apps/api/src/services/docker.py fails. Each .py in services/ is ≤ 300 lines.

AC-6: Inline Components Are Extracted

GIVEN any page component
WHEN reading its JSX
THEN no inner component definitions exist (no const FileBrowser = () => ... inside a page)
AND all extracted components are importable and testable independently

Test: grep -rn "const [A-Z].*=.*=>" apps/web/src/pages/ returns zero results.

AC-7: Naming Is Consistent

GIVEN any source file
WHEN checking its name against the naming table above
THEN it follows the convention for its layer
AND every exported React component matches its file name (case-insensitive)

Test: Script checks that every .tsx file's default/named export matches its basename.

AC-8: All Quality Gates Pass

GIVEN any phase of the refactor
WHEN running the quality gates
THEN npm run typecheck (frontend) passes with zero errors
AND npm run lint (frontend) passes with zero warnings
AND pytest (backend) passes with zero failures
AND no visual regressions are introduced

Test: Run all gates after each phase. No failures.

AC-9: Barrel Exports for Stable Boundaries

GIVEN components/ui/, components/features/{domain}/, or types/
WHEN importing from those directories
THEN an index.ts barrel export exists
AND consumers import from the directory, not individual files
AND one-off utilities and API modules do NOT have barrel exports

Test: test -f src/components/ui/index.ts passes. test -f src/utils/index.ts fails.

---

Requirements

REQ-1: Frontend Type System

The system SHALL centralize all shared domain types under apps/web/src/types/.

Rationale: Prevents drift between API types, state types, and component prop types.

Scenario: Centralizing Session types

• GIVEN Session is defined in api/sessions.ts and state/sessions.tsx
• WHEN the refactor is applied
• THEN a single types/session.ts defines the canonical Session interface
• AND both api/sessions.ts and state/sessions.tsx import from it
• AND api/sessions.ts no longer exports a Session type

Scenario: API modules lose inline types

• GIVEN api/tool_types.ts defines ToolType inline
• WHEN the refactor is applied
• THEN types/tool-type.ts defines ToolType
• AND api/tool_types.ts imports and re-exports it

REQ-2: Frontend Style Modules

The system SHALL use CSS Modules for component-scoped styles.

Rationale: Eliminates global CSS specificity wars; makes component styles discoverable and deletable.

Scenario: Component with styles

• GIVEN FileBrowser has custom styles
• WHEN a developer looks for its styles
• THEN they find components/features/git/file-browser/FileBrowser.module.css
• AND the module contains only .fileBrowser and child selectors
• AND no global class names leak outside the component

Scenario: Global styles remain minimal

• GIVEN styles/global.css exists
• WHEN reading it
• THEN it contains only: CSS variables, * { box-sizing }, body reset, and shell layout grid
• AND it does not contain component-specific rules (cards, buttons, dialogs, etc.)

REQ-3: Backend Router Separation

The system SHALL separate HTTP routing from business logic.

Rationale: Routers should be thin and testable; business logic should be reusable and independently testable.

Scenario: Creating a tool instance

• GIVEN a POST /instances request
• WHEN the router handles it
• THEN it validates the request body with a Pydantic schema
• AND it calls services.instances.create_instance(...)
• AND it returns the response
• AND it does not call docker compose up, modify files, or manage tunnels

Scenario: Starting a tool instance

• GIVEN a POST /instances/{id}/start request
• WHEN the router handles it
• THEN it calls services.instances.lifecycle.start_instance(...)
• AND it does not contain subprocess calls

REQ-4: Backend Service Focus

The system SHALL split services/docker.py into single-responsibility modules.

Rationale: Docker operations span compose, containers, tunnels, and config staging — too many concerns for one file.

Scenario: Service decomposition

• GIVEN the old services/docker.py
• WHEN the refactor is applied
• THEN the following modules exist:
  • services/docker/compose.py — compose file generation and modification
  • services/docker/container.py — container lifecycle (create, start, stop, remove)
  • services/docker/tunnel.py — Cloudflare tunnel management
  • services/docker/config.py — config folder staging and file writing
• AND each module is ≤ 300 lines
• AND services/docker.py does not exist

REQ-5: Page Component Decomposition

The system SHALL split page components into route entry points and feature sub-components.

Rationale: Pages should orchestrate data and routing, not contain inline UI implementations.

Scenario: Repo workspace page

• GIVEN the old pages/repo-workspace.tsx
• WHEN the refactor is applied
• THEN pages/repo-workspace/page.tsx contains only: data loading, layout, and sub-component composition
• AND components/features/git/file-browser/FileBrowser.tsx contains the file tree UI
• AND components/features/git/commit-panel/CommitPanel.tsx contains the commit form
• AND each extracted component is independently importable

Scenario: Tool workshop page

• GIVEN the old pages/tool-workshop.tsx
• WHEN the refactor is applied
• THEN it is split into:
  • pages/tool-workshop/page.tsx — tab navigation and layout
  • components/features/tool-workshop/ToolTypesTab.tsx
  • components/features/tool-workshop/ToolConfigsTab.tsx
  • components/features/tool-workshop/ConfigFoldersTab.tsx
• AND each tab component manages its own form state

REQ-6: Inline Component Extraction

The system SHALL not contain inner component definitions.

Rationale: Inner components cannot be tested independently, cause re-creation on every render, and hide complexity.

Scenario: No inner components in pages

• GIVEN any file under pages/
• WHEN searching for const [A-Z] followed by a component body
• THEN zero matches are found
• AND all previously inner components are moved to components/

REQ-7: Reusable Loading/Error Patterns

The system SHALL extract repeated loading/error/retry UI into shared components.

Rationale: ~8 pages copy the same status: "loading" | "ready" | "error" pattern with identical retry buttons.

Scenario: Loading state

• GIVEN a page is loading data
• WHEN the UI renders
• THEN it uses <LoadingState message="Loading sessions..." /> instead of inline JSX

Scenario: Error state

• GIVEN a page fails to load data
• WHEN the UI renders
• THEN it uses <ErrorState message="Failed to load" onRetry={loadData} /> instead of inline JSX

REQ-8: Barrel Exports at Stable Boundaries

The system SHALL provide index.ts barrel exports for stable module boundaries.

Rationale: Cleaner imports; encapsulates internal file structure.

Scenario: Importing UI primitives

• GIVEN a developer needs Button and Dialog
• WHEN they write the import
• THEN they write import { Button, Dialog } from "@/components/ui"
• AND not import { Button } from "@/components/ui/button/button"

Scenario: No barrel for utilities

• GIVEN a developer needs terminal-protocol utilities
• WHEN they write the import
• THEN they write import { encodeControlMessage } from "@/utils/terminal-protocol"
• AND utils/index.ts does not exist

---

API / Protocol Changes

None. This is a pure reorganization refactor. All HTTP endpoints, WebSocket protocols, and database schemas remain unchanged.

---

Dependencies

No new dependencies required. Existing toolchain:

• Frontend: React 18, Vite, TypeScript, ESLint, Vitest
• Backend: FastAPI, SQLAlchemy, Alembic, pytest

Optional consideration: If CSS Modules are adopted (per proposal), Vite has built-in support — no new dependency needed.

---

Non-Functional Requirements

• Build time: No regression in npm run build or vite build duration
• Bundle size: No increase in output bundle size
• Test runtime: No regression in npm run test or pytest duration
• Developer experience: File discovery time (time to locate a component/service) must decrease

---

Migration Order

Phase	Concern	Files Touched	Est. Lines
1	Types, seeds, shared deps	types/, main.py, repo-workspace.tsx	~350
2	Style system	styles.css → styles/ + .module.css	~2,750
3a	Backend shared deps	auth/dependencies.py, router helpers	~400
3b	tool_instances split	api/tool_instances.py → router + services	~800
3c	git_repositories + config_profiles split	Routers + services	~700
4a	tool-workshop split	Page + feature components	~500
4b	Pages split	sessions.tsx, dashboard.tsx, repo-workspace.tsx	~600
4c	Naming consistency	Rename files/components	~350
5	Tests + docs	Backfill tests, naming doc	~350

---

Open Questions (Resolved)

#	Question	Resolution
1	CSS approach	CSS Modules — each component gets its own .module.css
2	Backend API versioning	Keep flat api/ — version when v2 is actually needed
3	Feature components location	components/features/{domain}/
4	Barrel exports	Yes for stable boundaries (components/ui/, components/features/{domain}/, types/); no for one-off utilities and API modules
5	Branching strategy	Merge each phase to main immediately

---

Spec prepared for SDD design phase. Next: technical design with exact file layout and import patterns.