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

MODIFIED Requirements

Requirement: React Application Setup

The system SHALL use React 18+ with TypeScript and SHALL provide a runnable application source structure in apps/web/src.

Scenario: Frontend build

• GIVEN the frontend codebase
• THEN it SHALL:
  • Use React 18+ with TypeScript 5+
  • Use Vite as the build tool
  • Support Hot Module Replacement (HMR)
  • Output optimized production builds
  • Include a concrete entrypoint, app composition, and route tree

Requirement: Client-Side Routing

The system SHALL implement client-side routing with authenticated route guards and explicit not-found handling.

Scenario: Navigation

• GIVEN the frontend application
• THEN React Router SHALL:
  • Define routes for all foundation pages
  • Support protected routes (require authentication)
  • Handle 404 errors
  • Support route parameters for feature pages

Scenario: Protected routes

• GIVEN an unauthenticated user
• WHEN they access a protected route
• THEN they are redirected to login flow
• AND post-auth navigation returns them to an authenticated landing route

Requirement: Layout Component

The system SHALL provide a consistent application layout for authenticated screens across desktop and mobile sizes.

Scenario: Application shell

• GIVEN the frontend application
• THEN a Layout component SHALL:
  • Display a header with user info and logout
  • Display sidebar navigation on desktop
  • Show main content area
  • Collapse sidebar into a mobile menu toggle on small viewports

Scenario: Navigation links

• GIVEN the sidebar navigation
• THEN it SHALL include links to:
  • Dashboard
  • Projects
  • Repositories
  • SSH Keys
  • Settings

Requirement: HTTP Client Configuration

The system SHALL configure HTTP requests for cookie-based auth and unauthorized-session recovery.

Scenario: API communication

• GIVEN the frontend application
• THEN Axios/fetch SHALL:
  • Send credentials (cookies) with requests
  • Handle 401 responses by redirecting to login
  • Set appropriate content-type headers
  • Support request/response interception in a shared client module

Requirement: Loading States

The system SHALL handle asynchronous operations gracefully during auth bootstrap and dashboard fetches.

Scenario: Data fetching

• GIVEN a page loading data
• THEN:
  • Loading states are shown while requests are in flight
  • Errors are shown with retry affordance
  • Initial auth-check loading prevents protected-layout flicker