Fusion
61c5554c42
Commits merged: - docs(FN-019): complete Step 6 — documentation index, conversation handoff, project brief, and build config - test(FN-019): complete Step 4 — doc validation tests, project-brief.md, and fix mvp-scope placeholders - feat(FN-019): complete Step 3 — draft mvp-scope.md with milestones, dependency order, and open questions - docs(FN-019): fix auth callback flow, Python syntax, dev bypass clarity, add AccessProvider protocol and type stubs - feat(FN-019): complete Step 2 — draft enhanced architecture.md with all 18 required sections Files changed: docs/README.md | 11 +- docs/architecture.md | 1185 ++++++++++++++++++++++++++++++++++----- docs/conversation-handoff.md | 68 +++ docs/mvp-scope.md | 184 ++++++ docs/project-brief.md | 31 + package.json | 3 + tests/docs/__init__.py | 0 tests/docs/test_architecture.py | 120 ++++ 8 files changed, 1444 insertions(+), 158 deletions(-) Fusion-Task-Id: FN-019
69 lines
5.1 KiB
Markdown
69 lines
5.1 KiB
Markdown
# 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:** RunFusion 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
|