## 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).