alex
62640daf36
- Update architecture.md with spawn service and auth proxy sections - Update deployment.md with production stack details - Update development.md with spawn workflow documentation - Update mvp-scope.md, project-brief.md, tool-manifest-spec.md - Update conversation-handoff.md with current status - Replace all RunFusion references with OpenCode
185 lines
10 KiB
Markdown
185 lines
10 KiB
Markdown
# Headquarter MVP Scope
|
|
|
|
> Canonical definition of what is in, out, and deferred for the Minimum Viable Product.
|
|
> This document is the scope boundary for all downstream implementation tasks.
|
|
|
|
---
|
|
|
|
## 1. Product Vision
|
|
|
|
Headquarter is a hosted workspace and tool-orchestration platform for developers who want self-hosted control over their development environments. It gives authenticated users a single dashboard to create Git-backed projects, connect repositories from any provider, and spawn containerized tools—starting with OpenCode and code-server—on demand, each accessible via its own HTTPS subdomain. Headquarter is for individual developers and small teams who outgrow cloud IDEs but do not want to build their own orchestration layer from scratch.
|
|
|
|
---
|
|
|
|
## 2. MVP User Journeys
|
|
|
|
An MVP user can complete the following end-to-end flows without assistance:
|
|
|
|
### 2.1 Sign Up / Log In via Authentik
|
|
- User clicks "Sign In" and is redirected to the organization's Authentik instance.
|
|
- After OIDC authentication, the user is redirected back to the Headquarter dashboard.
|
|
- A `User` row is created automatically on first login.
|
|
|
|
### 2.2 Create a Project
|
|
- User clicks "New Project" and provides a name and optional description.
|
|
- The backend generates a URL-friendly `slug` from the name.
|
|
- The project appears in the user's project list.
|
|
|
|
### 2.3 Connect a Git Repository
|
|
- User selects a project and chooses "Connect Repository."
|
|
- User provides the Git clone URL and selects the provider type (GitHub, GitLab, Gitea, Forgejo, or generic).
|
|
- The backend creates a `Repository` row and a `RepositoryConnection` row.
|
|
|
|
### 2.4 Generate Per-Repository SSH Credentials
|
|
- User clicks "Generate SSH Key" for a repository connection.
|
|
- The backend generates an Ed25519 key pair, encrypts the private key, and stores it.
|
|
- The public key is displayed to the user for manual registration at the provider, or registered automatically via the provider adapter when available.
|
|
|
|
### 2.5 Spawn a Tool Instance
|
|
- User navigates to "Tools" and selects a tool (OpenCode or code-server).
|
|
- User chooses a project and optional config overrides.
|
|
- The backend generates a Docker Compose service definition, Traefik labels, and starts the container.
|
|
- The tool instance receives workspace mounts, config mounts, and secret injection.
|
|
|
|
### 2.6 Access the Running Tool via Subdomain
|
|
- After the tool instance reaches `running` or `healthy` status, the user sees a link.
|
|
- The link follows the subdomain pattern: `https://{tool}-{project}-{user}.{tool_domain}`.
|
|
- Traefik routes the subdomain to the container's exposed port over HTTPS.
|
|
|
|
### 2.7 Stop and Restart a Tool Instance
|
|
- User clicks "Stop" on a running tool instance.
|
|
- The backend calls Docker to stop the container and updates the status to `stopped`.
|
|
- User can click "Start" to re-provision the container with the same configuration.
|
|
|
|
### 2.8 Configure Tool Settings
|
|
- User navigates to "Settings" for a project or their user profile.
|
|
- User can create, update, or delete config values at project or user scope.
|
|
- Config values are stored as JSON and mounted into tool containers at runtime.
|
|
|
|
### 2.9 Store and Inject Secrets
|
|
- User navigates to "Secrets" for a project.
|
|
- User creates a secret by providing a key name and value.
|
|
- The backend encrypts the value with Fernet before storage.
|
|
- At spawn time, the backend decrypts the secret and injects it as an environment variable or mounted file.
|
|
|
|
---
|
|
|
|
## 3. In-Scope Features
|
|
|
|
- **Authentik OIDC authentication** with automatic user provisioning
|
|
- **Project management** (CRUD, ownership-based)
|
|
- **Repository connections** with provider-agnostic Git URL storage
|
|
- **Per-repository SSH key generation** (Ed25519) with encrypted private-key storage
|
|
- **Tool registry** with manifest-driven definitions for OpenCode and code-server
|
|
- **Tool instance spawning** via Docker Compose with Traefik subdomain routing
|
|
- **Tool instance lifecycle** (start, stop, health checks, status tracking)
|
|
- **Persistent config storage** at global, user, project, and tool-instance scopes
|
|
- **Encrypted secret storage** at user, project, and tool-instance scopes
|
|
- **Traefik label generation** for dynamic subdomain routing
|
|
- **Local development stack** via Docker Compose (API, web, PostgreSQL)
|
|
- **Deployment skeleton** for Portainer-managed production stacks
|
|
|
|
---
|
|
|
|
## 4. Out-of-Scope Features (Non-Goals)
|
|
|
|
The following are explicitly excluded from MVP to prevent scope creep:
|
|
|
|
- **Multi-user teams / shared projects** — Schema leaves room for `ProjectMember`, but no UI or API in MVP
|
|
- **Real-time collaboration** — No shared cursors, simultaneous editing, or presence
|
|
- **Advanced CI/CD pipelines** — No build orchestration, test runners, or deployment stages
|
|
- **Kubernetes runtime** — Docker Compose only; Kubernetes adapter is a future extension point
|
|
- **Non-Docker runtimes** — No Podman, LXC, or VM runtimes in MVP
|
|
- **Automatic Git provider webhooks** — No push-triggered actions or webhook receivers
|
|
- **Built-in GitHub/GitLab UI integrations** — No issue trackers, PR viewers, or code review UI
|
|
- **Backup and disaster recovery automation** — Rely on host-level volume backups
|
|
- **High availability / replicas** — Single-instance deployment only
|
|
- **Rate limiting** — No API or Traefik rate limits in MVP
|
|
- **Audit logging** — No immutable audit trail of user actions
|
|
- **Automatic credential rotation** — Manual rotation only
|
|
- **Container image vulnerability scanning** — No image trust enforcement
|
|
|
|
---
|
|
|
|
## 5. MVP Milestones / Slices
|
|
|
|
Slices are ordered by dependency. Each slice corresponds to a task on the Fusion board.
|
|
|
|
| Slice | Task ID | Title | Deliverable |
|
|
|-------|---------|-------|-------------|
|
|
| 1 | **FN-002** | Monorepo Scaffold | Root tooling, frontend/backend skeletons, Docker Compose, deployment skeleton |
|
|
| 2 | **FN-019** | Architecture & Specification | Enhanced `docs/architecture.md`, `docs/mvp-scope.md`, doc validation tests |
|
|
| 3 | **FN-004** | Backend Foundation | Domain models, Alembic migrations, auth boundaries, secret encryption, API routers |
|
|
| 4 | **FN-005** | Frontend Foundation | Auth shell, navigation, placeholder pages, API client, config layer |
|
|
| 5 | **FN-003** | Tool Registry | Manifest schema, in-memory registry, built-in OpenCode/code-server manifests, FastAPI routes |
|
|
| 6 | **FN-006** | Deployment Config | Traefik label generator, production Compose stacks, Portainer stack definition |
|
|
| 7 | **FN-011** | Git Provider Model | Provider abstraction, SSH key lifecycle, credential models, repository connection |
|
|
| 8 | **FN-009** | Config & Secrets | Encrypted storage, runtime injection, frontend config/secrets UI |
|
|
| 9 | **FN-010** | code-server Spawn | code-server manifest, spawn flow, runtime integration, auth layer |
|
|
| 10 | **FN-008** | OpenCode POC | AI-powered terminal environment, web interface, health reporting |
|
|
|
|
**Dependency notes:**
|
|
- FN-004 and FN-005 can proceed in parallel once FN-019 is complete.
|
|
- FN-003 depends on FN-004 (backend models exist).
|
|
- FN-006 depends on FN-002 (scaffold exists) and benefits from FN-003 (manifest routing fields).
|
|
- FN-011 depends on FN-004 (models and test infrastructure).
|
|
- FN-009 depends on FN-004 and FN-005.
|
|
- FN-010 depends on FN-003, FN-006, and FN-009.
|
|
- FN-008 depends on FN-003, FN-006, and FN-009.
|
|
|
|
---
|
|
|
|
## 6. Dependency Order for Downstream Implementation
|
|
|
|
```
|
|
FN-002 (Scaffold)
|
|
│
|
|
├──> FN-019 (Architecture) ──> FN-004 (Backend)
|
|
│ │
|
|
│ ├──> FN-003 (Tool Registry)
|
|
│ │ │
|
|
│ │ ├──> FN-010 (code-server Spawn)
|
|
│ │ └──> FN-008 (OpenCode POC)
|
|
│ │
|
|
│ ├──> FN-011 (Git Provider)
|
|
│ │
|
|
│ └──> FN-009 (Config/Secrets)
|
|
│ │
|
|
│ └──> FN-010, FN-008 (runtime injection)
|
|
│
|
|
└──> FN-005 (Frontend) ───────> FN-009 (Config/Secrets UI)
|
|
|
|
FN-006 (Deployment) runs in parallel with FN-004/FN-005
|
|
after FN-002 is complete.
|
|
```
|
|
|
|
**Critical path:** FN-002 → FN-019 → FN-004 → FN-003 → FN-010/FN-008
|
|
|
|
---
|
|
|
|
## 7. Definition of MVP Done
|
|
|
|
MVP is complete and shippable when **all** of the following are true:
|
|
|
|
1. A user can sign up, create a project, connect a Git repository, and spawn code-server from a single dashboard.
|
|
2. Spawned tools are accessible via HTTPS subdomains routed through Traefik.
|
|
3. Secrets and configs are encrypted at rest and injected correctly at runtime.
|
|
4. SSH keys are generated per repository and used for Git operations inside containers.
|
|
5. All backend tests pass (`pytest`), all frontend tests pass (`vitest`), and all lint/typecheck gates pass.
|
|
6. The production stack (`docker-compose.prod.yml`) deploys cleanly via Portainer.
|
|
7. Documentation (`architecture.md`, `mvp-scope.md`, `deployment.md`, `development.md`) is accurate and consistent with the implementation.
|
|
8. No incomplete placeholders or task markers remain in committed code or documentation.
|
|
|
|
---
|
|
|
|
## 8. Open Questions
|
|
|
|
The following scope decisions are pending stakeholder input. Implementers should not choose defaults for these without explicit approval:
|
|
|
|
1. **Admin role in MVP:** Do we need a basic admin role for global config management, or can all authenticated users write global config in MVP?
|
|
2. **User slug derivation:** Should the user slug for subdomain generation be derived from `display_name`, `email` local-part, or a new dedicated `slug` column?
|
|
3. **Provider adapter coverage:** Which Git providers get concrete adapters in MVP? GitHub and GitLab are assumed; Gitea and Forgejo may be deferred.
|
|
4. **Auto-deploy-key registration:** Should the platform attempt to register deploy keys automatically via provider APIs, or is manual copy-paste acceptable for MVP?
|
|
5. **Container image trust:** Should the platform restrict tool images to an allow-list in production, or is any image reference acceptable in MVP?
|
|
6. **Billing or resource quotas:** Is any form of usage limiting or project quota needed in MVP, or is it strictly single-user-unlimited?
|