alex
78aaddb2b5
- Add frontend-foundation change (FN-005) with 46 tasks - Add deployment-config change (FN-006) with 27 tasks - Add runfusion-poc/opencode-poc change (FN-008) with 25 tasks - Add config-secrets change (FN-009) with 31 tasks - Add codeserver-spawn change (FN-010) with 38 tasks - Include project specsheet and configuration - Archive completed deployment-config change
244 lines
8.8 KiB
Markdown
244 lines
8.8 KiB
Markdown
# Headquarter Project Specsheet
|
|
|
|
> Canonical project state document. Updated after each completed FN task.
|
|
> Last updated: 2026-05-14
|
|
|
|
## Project Overview
|
|
|
|
Headquarter is a hosted workspace and tool-orchestration platform where authenticated users create Git-backed projects and spawn containerized development tools (OpenCode, code-server) via HTTPS subdomains.
|
|
|
|
## Tech Stack
|
|
|
|
| Layer | Technology |
|
|
|-------|-----------|
|
|
| Frontend | React 19 + Vite 6 + TypeScript 5 |
|
|
| Backend | FastAPI + SQLAlchemy 2.0 (async) + Pydantic v2 |
|
|
| Database | PostgreSQL 17 + Alembic migrations |
|
|
| Auth | Authentik OIDC (planned) |
|
|
| Runtime | Docker Compose (local dev + Portainer production) |
|
|
| Routing | Traefik reverse proxy with subdomain routing |
|
|
| Monorepo | pnpm workspace |
|
|
|
|
## Completed Features
|
|
|
|
### FN-002: Monorepo Scaffold ✅
|
|
- Root tooling (Makefile, package.json, pnpm-workspace.yaml)
|
|
- React frontend skeleton (apps/web/)
|
|
- FastAPI backend skeleton (apps/api/)
|
|
- Docker Compose local development stack
|
|
- Deployment skeleton for Portainer + Traefik
|
|
- CI/CD workflow (GitHub Actions)
|
|
|
|
### FN-019: Architecture & Specification ✅
|
|
- Enhanced docs/architecture.md (18 sections)
|
|
- docs/mvp-scope.md with milestones and dependency order
|
|
- docs/project-brief.md
|
|
- docs/development.md
|
|
- docs/deployment.md
|
|
- docs/tool-manifest-spec.md
|
|
|
|
### FN-003: Tool Registry ✅
|
|
- Manifest-driven tool registry (JSON schema)
|
|
- In-memory registry with built-in manifests
|
|
- FastAPI CRUD routes for tool definitions
|
|
- OpenCode and code-server built-in definitions
|
|
- Registry loaded at application startup
|
|
|
|
### FN-011: Git Provider Model ✅
|
|
- Git provider abstraction (GitHub, GitLab, Gitea, Forgejo, generic)
|
|
- SSH key pair generation (Ed25519)
|
|
- Encrypted private key storage
|
|
- Credential model and storage interface
|
|
- Repository connection model and manager
|
|
- Local Git operations interface
|
|
- Alembic migration for repository_connection table
|
|
- Full test coverage
|
|
|
|
### FN-004: Backend Foundation (Partial) ✅
|
|
- Domain models: User, Project, Repository, Workspace, ToolDefinition, ToolInstance, Config, Secret, AccessRoute, RepositoryConnection
|
|
- Alembic migrations
|
|
- API routers for all entities
|
|
- Database configuration with async SQLAlchemy
|
|
- Encryption utilities (Fernet)
|
|
- Auth dependencies structure
|
|
|
|
### FN-049: CI / Testing ✅
|
|
- GitHub Actions workflow
|
|
- Frontend: lint, typecheck, test (Vitest)
|
|
- Backend: lint (ruff), typecheck (mypy), test (pytest)
|
|
- PostgreSQL service container for backend tests
|
|
|
|
## OpenSpec Changes (Ready for Implementation)
|
|
|
|
### FN-005: Frontend Foundation 📋
|
|
**Location:** `openspec/changes/frontend-foundation/`
|
|
**Status:** All artifacts complete (proposal, design, specs, tasks)
|
|
**Dependencies:** FN-002, FN-019
|
|
**Tasks:** 46 total
|
|
**Key deliverables:**
|
|
- Authentik OIDC auth flow with PKCE
|
|
- Dashboard shell with responsive navigation
|
|
- Project CRUD UI
|
|
- Typed API client
|
|
- Auth-guarded routes
|
|
|
|
### FN-006: Deployment Config 📋
|
|
**Location:** `openspec/changes/deployment-config/`
|
|
**Status:** All artifacts complete (proposal, design, specs, tasks)
|
|
**Dependencies:** FN-002
|
|
**Tasks:** 27 total
|
|
**Key deliverables:**
|
|
- Traefik label generator service
|
|
- Production Docker Compose stack
|
|
- Portainer deployment guide
|
|
- Dynamic subdomain routing
|
|
|
|
### FN-009: Config & Secrets 📋
|
|
**Location:** `openspec/changes/config-secrets/`
|
|
**Status:** All artifacts complete (proposal, design, specs, tasks)
|
|
**Dependencies:** FN-004, FN-005
|
|
**Tasks:** 31 total
|
|
**Key deliverables:**
|
|
- Config management UI (global/user/project/instance scopes)
|
|
- Encrypted secret storage UI
|
|
- Runtime injection into tool containers
|
|
- Scope-based access control
|
|
|
|
### FN-010: code-server Spawn 📋
|
|
**Location:** `openspec/changes/codeserver-spawn/`
|
|
**Status:** All artifacts complete (proposal, design, specs, tasks)
|
|
**Dependencies:** FN-003, FN-006, FN-009
|
|
**Tasks:** 38 total
|
|
**Key deliverables:**
|
|
- Tool spawn API endpoint
|
|
- code-server manifest refinement
|
|
- Frontend spawn UI
|
|
- Container lifecycle management (start/stop/status)
|
|
- Traefik auth proxy integration
|
|
|
|
### FN-008: OpenCode POC 📋
|
|
**Location:** `openspec/changes/opencode-poc/`
|
|
**Status:** All artifacts complete (proposal, design, specs, tasks)
|
|
**Dependencies:** FN-003, FN-006, FN-009
|
|
**Tasks:** 25 total
|
|
**Key deliverables:**
|
|
- OpenCode manifest with web terminal config
|
|
- Containerized terminal environment
|
|
- Health reporting mechanism
|
|
- Web terminal interface
|
|
|
|
## Dependency Graph
|
|
|
|
```
|
|
FN-002 (Scaffold) ✅
|
|
│
|
|
├──> FN-019 (Architecture) ✅ ──> FN-004 (Backend) ✅
|
|
│ │
|
|
│ ├──> FN-003 (Tool Registry) ✅
|
|
│ │ │
|
|
│ │ ├──> FN-010 (code-server) 📋
|
|
│ │ └──> FN-008 (OpenCode) 📋
|
|
│ │
|
|
│ ├──> FN-011 (Git Provider) ✅
|
|
│ │
|
|
│ └──> FN-009 (Config/Secrets) 📋
|
|
│ │
|
|
│ └──> FN-010, FN-008 (runtime)
|
|
│
|
|
└──> FN-005 (Frontend) 📋 ───────> FN-009 (UI)
|
|
|
|
FN-006 (Deployment) 📋 runs in parallel with FN-004/FN-005
|
|
```
|
|
|
|
## Critical Path
|
|
|
|
FN-002 ✅ → FN-019 ✅ → FN-004 ✅ → FN-003 ✅ → FN-010/FN-008 📋
|
|
|
|
## Next Recommended Task
|
|
|
|
**FN-005: Frontend Foundation** - This unblocks user-facing features and enables parallel work on FN-009 (Config/Secrets UI).
|
|
|
|
## Database Schema
|
|
|
|
### Existing Tables
|
|
- `users` - User accounts (Authentik OIDC)
|
|
- `projects` - User projects with slug
|
|
- `repositories` - Git repository metadata
|
|
- `repository_connections` - Provider-specific connections with SSH keys
|
|
- `workspaces` - Project workspaces
|
|
- `tool_definitions` - Manifest-driven tool definitions
|
|
- `tool_instances` - Running/spawned tool instances
|
|
- `configs` - Key-value config storage (scoped)
|
|
- `secrets` - Encrypted secret storage (scoped)
|
|
- `access_routes` - Traefik routing rules
|
|
|
|
## API Endpoints
|
|
|
|
### Implemented Routers
|
|
- `/api/v1/users` - User management
|
|
- `/api/v1/projects` - Project CRUD
|
|
- `/api/v1/repositories` - Repository management
|
|
- `/api/v1/workspaces` - Workspace management
|
|
- `/api/v1/tool-definitions` - Tool registry CRUD
|
|
- `/api/v1/tool-instances` - Tool instance lifecycle
|
|
- `/api/v1/configs` - Config management
|
|
- `/api/v1/secrets` - Secret management
|
|
- `/api/v1/access-routes` - Routing rules
|
|
- `/api/v1/tools` - Tool registry (manifest-driven)
|
|
- `/health` - Health check
|
|
|
|
## Open Questions (from mvp-scope.md)
|
|
|
|
1. **Admin role in MVP:** Do we need a basic admin role for global config management?
|
|
2. **User slug derivation:** Display name, email local-part, or dedicated slug column?
|
|
3. **Provider adapter coverage:** Which Git providers get concrete adapters in MVP?
|
|
4. **Auto-deploy-key registration:** Automatic via provider APIs or manual copy-paste?
|
|
5. **Container image trust:** Allow-list or any image reference?
|
|
6. **Billing or resource quotas:** Usage limiting needed in MVP?
|
|
|
|
## File Structure
|
|
|
|
```
|
|
headquarter/
|
|
├── apps/
|
|
│ ├── web/ # React frontend (skeleton)
|
|
│ └── api/ # FastAPI backend (models + routers)
|
|
├── docs/ # Architecture, scope, development docs
|
|
├── deploy/ # Portainer/Traefik deployment examples
|
|
├── openspec/ # Spec-driven workflow
|
|
│ ├── config.yaml # Project context for AI
|
|
│ ├── changes/ # Active changes
|
|
│ │ ├── frontend-foundation/ # FN-005
|
|
│ │ ├── deployment-config/ # FN-006
|
|
│ │ ├── config-secrets/ # FN-009
|
|
│ │ ├── codeserver-spawn/ # FN-010
|
|
│ │ └── opencode-poc/ # FN-008
|
|
│ └── specs/ # Project specsheets
|
|
│ └── project-specsheet.md
|
|
├── docker-compose.yml # Local development stack
|
|
├── docker-compose.traefik.yml
|
|
├── Makefile # Common workflows
|
|
└── package.json # Root monorepo scripts
|
|
```
|
|
|
|
## Test Status
|
|
|
|
- **Frontend:** Vitest configured, basic App.test.tsx passing
|
|
- **Backend:** pytest configured, tests for git provider, credentials, operations
|
|
- **CI:** GitHub Actions runs on PR/push to main
|
|
|
|
## Definition of MVP Done
|
|
|
|
1. ✅ Monorepo scaffold complete
|
|
2. ✅ Architecture documented
|
|
3. ✅ Backend models and migrations
|
|
4. ✅ Tool registry with manifests
|
|
5. ✅ Git provider abstraction
|
|
6. 📋 Frontend auth and navigation (spec ready)
|
|
7. 📋 Config/secrets UI and runtime injection (spec ready)
|
|
8. 📋 code-server spawn flow (spec ready)
|
|
9. 📋 OpenCode terminal environment (spec ready)
|
|
10. 📋 Production deployment stack (spec ready)
|
|
11. ⏳ All tests passing
|
|
12. ⏳ Documentation consistent with implementation
|