57 lines
3.1 KiB
Markdown
57 lines
3.1 KiB
Markdown
## 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).
|