headquarter/docs/conversation-handoff.md

Conversation Handoff: FN-019

Task Context

This document captures the key architectural decisions, assumptions, and open loops produced during FN-019 — Architecture and MVP Specification for Headquarter.

Key Decisions Made

1. Auth Callback Flow (Section 12.2)

• Decision: Backend-handled callback is the recommended MVP pattern.
• Rationale: The frontend receives the Authentik redirect at a backend endpoint (GET /api/v1/auth/callback), the backend exchanges the code for tokens, sets an httpOnly cookie, and returns an HTTP 302 redirect to the frontend dashboard. This avoids exposing the client secret to the frontend and avoids the fetch() + redirect ambiguity.

2. GitProvider Split (Section 5.1)

• Decision: Two complementary abstractions: GitProvider (remote API operations) and GitOperations (local Git CLI).
• Rationale: This separation was already implemented in FN-011. The architecture doc preserves and formalizes it.

3. AccessProvider Protocol (Section 9.2)

• Decision: Added an explicit AccessProvider ABC with RoutingConfig Pydantic model.
• Rationale: The original architecture doc mentioned AccessProvider as an extension point but never defined method signatures. The enhanced doc makes it as concrete as GitProvider and RuntimeProvider.

4. Subdomain Pattern (Section 10.1)

• Decision: Default pattern is {tool}-{project}-{user}.{tool_domain}.
• Rationale: Aligns with existing config.py (tool_subdomain_pattern) and downstream FN-006 label generator. The relationship between ROOT_DOMAIN and TOOL_DOMAIN is now explicitly documented.

5. Dev Bypass Security Model (Section 12.7)

• Decision: AUTH_DEV_BYPASS is an environment variable, not a query parameter.
• Rationale: The backend must reject the bypass when settings.debug is False, even if the env var is set. This prevents accidental production exposure.

6. Credential Storage Abstraction (Section 4.10, 5.3, 6.3)

• Decision: Credentials are stored as encrypted secret rows with scope_type='repository'.
• Rationale: The CredentialStorage ABC (from FN-011) is the interface, but the canonical storage is the secret table. The architecture doc now cross-references correctly.

Assumptions

1. Single-tenant MVP: The platform runs as a single deployment with no hard multi-tenant isolation.
2. Portainer-managed stacks: Production deployment assumes an existing Portainer instance.
3. Existing Traefik: The reverse proxy is already running and attached to an external Docker network named traefik.
4. Authentik pre-configured: The OIDC application is created in Authentik before deployment.
5. PostgreSQL 17+: The database schema uses features compatible with PostgreSQL 17.

Open Loops for Future Tasks

1. User slug derivation (architecture.md Section 18, Open Question 2): Should the user slug for subdomain generation be derived from display_name, email local-part, or a new slug column? Decision needed before FN-006/FN-010 implementation.
2. Admin role in MVP (architecture.md Section 18, Open Question 1): Do we need a basic admin role for global config management? Decision needed before FN-009 API implementation.
3. Auto-deploy-key registration (architecture.md Section 18, Open Question 4): Should the platform auto-register deploy keys via provider APIs, or is manual copy-paste acceptable for MVP? Decision needed before FN-011 UI work.
4. Container image trust (architecture.md Section 18, Open Question 5): Should the platform restrict tool images to an allow-list? Decision needed before FN-010/FN-008 spawn implementation.
5. Subdomain truncation strategy (architecture.md Section 10.1): DNS labels have a 63-byte limit. A deterministic truncation/hashing strategy for long project or user names is needed before FN-006 label generation is finalized.
6. Global config write permissions (architecture.md Section 13.7): The architecture doc documents two possible MVP behaviors (allow all authenticated users, or reject with 403). A stakeholder must choose before FN-009 router implementation.

Files Modified / Created

• docs/architecture.md — Rewritten with 18 required sections
• docs/mvp-scope.md — New file
• docs/project-brief.md — New file
• docs/conversation-handoff.md — New file (this document)
• docs/README.md — Updated index
• tests/docs/test_architecture.py — New automated validation suite
• tests/docs/__init__.py — New empty init

Downstream Dependencies

• FN-004: Backend Foundation — depends on the PostgreSQL domain model in Section 4
• FN-005: Frontend Foundation — depends on component boundaries in Section 3.1
• FN-006: Deployment Config — depends on Traefik routing model in Section 10
• FN-008: OpenCode POC — depends on spawn lifecycle in Section 8 and Docker runtime in Section 9
• FN-009: Config & Secrets — depends on storage layout in Section 11 and security in Section 13
• FN-010: code-server Spawn — depends on tool manifest in Section 7 and Docker runtime in Section 9
• FN-011: Git Provider — depends on Git provider abstraction in Section 5