# Frontend Foundation Specification

## Purpose

Provide a modern React frontend with TypeScript, routing, and responsive layout.
## 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: Styling Framework

The system SHALL use Tailwind CSS for styling.

#### Scenario: UI components
- GIVEN the frontend codebase
- THEN Tailwind CSS SHALL:
  - Provide utility-first styling
  - Support custom theme configuration
  - Include responsive design utilities
  - Support dark mode

### 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: Responsive Design

The system SHALL support mobile devices.

#### Scenario: Mobile viewport
- GIVEN a mobile device
- WHEN the app loads
- THEN:
  - A hamburger menu replaces the sidebar
  - Content adapts to screen width
  - Touch targets are appropriately sized

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

### 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: Dashboard Page

The system SHALL provide a dashboard overview.

#### Scenario: Dashboard view
- GIVEN an authenticated user
- WHEN they visit the dashboard
- THEN they see:
  - Total repository count
  - Total project count
  - Recent activity
  - Quick action buttons

### Requirement: Projects Listing Page Layout
The projects listing page SHALL display project cards with Settings, Delete, and Open Workspace actions, where Open Workspace is the rightmost action.

#### Scenario: Project card action layout
- GIVEN the projects listing page
- WHEN project cards are rendered
- THEN each card shows actions in order: Settings link, Delete button, Open Workspace button (rightmost)

#### Scenario: Navigate to project settings
- GIVEN the projects listing page
- WHEN a user clicks the Settings link
- THEN they navigate to `/projects/:id/settings`

#### Scenario: No inline edit modal
- GIVEN the projects listing page
- WHEN a user views a project card
- THEN no inline Edit button or modal dialog is available

## Dependencies

- React 18+
- TypeScript 5+
- Vite
- React Router
- Tailwind CSS
- Axios

## Quality Gates

- `npm run typecheck` must pass
- `npm run lint` must pass
- `npm run build` must succeed
- Frontend handles 401 responses correctly
- Responsive design works on mobile