# 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