headquarter/openspec/changes/archive/2026-05-17-project-management/design.md

Context

Project management is defined in specs but not yet fully implemented across backend and frontend. The codebase now includes auth-oauth and frontend-foundation, so this change should connect authenticated users to project CRUD workflows and enforce ownership/security rules consistently.

Goals / Non-Goals

Goals:

• Provide authenticated CRUD endpoints for projects with owner-only updates/deletes.
• Expose project listing payloads that include associated repositories and default SSH key metadata.
• Add frontend project pages for listing, creating, editing, and deleting projects.
• Support setting/changing a default SSH key per project with ownership validation.
• Verify cascade behavior and authorization through tests.

Non-Goals:

• Advanced collaboration features (shared project ownership, invites, roles).
• Bulk project operations.
• Full analytics/activity stream implementation beyond simple listing metadata.

Decisions

1. Keep project logic in dedicated service layer with thin route handlers

   • Rationale: consistent with auth service separation and easier unit testing.
   • Alternative: embed logic directly in route handlers. Rejected for maintainability.

2. Use authenticated user identity from internal JWT for ownership checks

   • Rationale: single trust path and no client-provided owner fields.
   • Alternative: allow owner IDs in request body. Rejected for security risk.

3. Return normalized project DTOs with nested repository summaries

   • Rationale: reduces frontend round-trips and supports immediate dashboard/project page rendering.
   • Alternative: fetch repositories separately per project. Rejected due to extra request overhead.

4. Implement optimistic-friendly frontend forms with explicit server error display

   • Rationale: better UX while preserving clear failure feedback.
   • Alternative: full page reload after each action. Rejected due to poor interaction quality.

Risks / Trade-offs

• [Ownership bypass bugs] -> enforce auth checks at service boundary and test unauthorized scenarios.
• [Cascade deletion surprises] -> add integration tests that assert repository/association cleanup behavior.
• [Stale frontend lists after mutation] -> centralize refresh calls after create/update/delete.
• [Default SSH key mismatch] -> validate key belongs to user/project context before assignment.

Migration Plan

1. Add/adjust backend project API routes and services.
2. Add backend tests for CRUD, ownership, default-key, and cascade behavior.
3. Implement frontend project pages and API integration.
4. Add frontend tests for protected interactions and mutation flows.
5. Run quality gates for backend and frontend.

Rollback:

• Revert project API and frontend pages; keep existing schema unchanged unless explicit migration is added.

Open Questions

• Whether project descriptions should support markdown formatting (deferred; plain text for now).