headquarter/openspec/changes/archive/2026-05-17-frontend-foundation/design.md

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