feat: implement auth, projects, and frontend foundation

2026-05-17 20:21:55 +00:00
parent e7819bfc82
commit 71d9fe6406
88 changed files with 10936 additions and 47 deletions
@@ -0,0 +1,56 @@
+## Context
+
+`apps/web` currently contains only package and container scaffolding, with no source code. Backend authentication and API foundations are now available, including cookie-based auth flows. The frontend foundation must establish a maintainable structure that supports authenticated navigation, responsive layout behavior, and consistent API communication.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Create a minimal but production-oriented React app structure with TypeScript and Vite.
+- Add client-side routing with protected-route behavior and fallback 404 route.
+- Provide an authenticated shell layout with desktop sidebar and mobile navigation affordances.
+- Add a shared API client that sends credentials and handles unauthorized responses.
+- Provide a starter dashboard page with loading and error-safe patterns.
+
+**Non-Goals:**
+- Full feature implementation for projects/repositories/ssh keys/settings pages.
+- Pixel-perfect final design system and component library.
+- Advanced state-management framework adoption beyond required foundation.
+
+## Decisions
+
+1. **Route-centric app composition with `react-router-dom` data boundaries kept simple**
+   - Rationale: aligns with existing dependency set and keeps first milestone small.
+   - Alternative: add heavier route/data framework patterns now. Rejected as unnecessary for foundation stage.
+
+2. **Auth state bootstraps from `/auth/me` and routes guard against missing session**
+   - Rationale: backend is source of truth for cookie-backed identity; avoids duplicative token logic in browser.
+   - Alternative: local token/session storage. Rejected for weaker security and mismatch with cookie strategy.
+
+3. **Single API client module wrapping Axios defaults and 401 interception**
+   - Rationale: centralizes credential behavior and unauthorized handling.
+   - Alternative: per-request fetch wrappers across pages. Rejected due to duplication risk.
+
+4. **App shell-first approach before deep page content**
+   - Rationale: navigation and responsive structure are prerequisites for all future feature pages.
+   - Alternative: implement pages first then refactor into shell. Rejected due to avoidable churn.
+
+## Risks / Trade-offs
+
+- **[Auth bootstrap flicker on first load]** -> use explicit loading screen until session check resolves.
+- **[401 redirect loops]** -> add interceptor guard and avoid redirecting when already on public/auth routes.
+- **[Responsive nav complexity early]** -> keep mobile behavior minimal (toggleable drawer) and iterate later.
+- **[Frontend/backend contract drift]** -> codify expected endpoint behavior in integration-oriented frontend tests.
+
+## Migration Plan
+
+1. Scaffold source tree (`main.tsx`, app router, shell, pages, API client, styles).
+2. Implement auth context + protected route guard and login/logout wiring.
+3. Implement responsive shell and dashboard placeholder content.
+4. Add checks/tests and run `npm run typecheck`, `npm run lint`, `npm run build`.
+
+Rollback:
+- Remove added source tree and revert package/config changes if foundation rollout is paused.
+
+## Open Questions
+
+- Whether to include React Query in the next frontend increment (deferred; not required for foundation).