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

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

### Requirement: Client-Side Routing

The system SHALL implement client-side routing.

#### Scenario: Navigation
- GIVEN the frontend application
- THEN React Router SHALL:
  - Define routes for all pages
  - Support protected routes (require authentication)
  - Handle 404 errors
  - Support route parameters

#### Scenario: Protected routes
- GIVEN an unauthenticated user
- WHEN they access a protected route
- THEN they are redirected to login

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

#### Scenario: Application shell
- GIVEN the frontend application
- THEN a Layout component SHALL:
  - Display a header with user info and logout
  - Display a sidebar with navigation links
  - Show main content area
  - Collapse sidebar on mobile

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

#### Scenario: Data fetching
- GIVEN a page loading data
- THEN:
  - Loading spinners/skeletons are shown
  - Error boundaries catch errors
  - Retry options are available on failure

### Requirement: HTTP Client Configuration

The system SHALL configure HTTP requests properly.

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

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

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