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