headquarter/openspec/specs/project-specsheet.md

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