# 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: Tool Interface Type Dropdown
The tool workshop SHALL provide a dropdown for selecting a single interface type.

#### Scenario: Interface type dropdown
- GIVEN the tool workshop page
- WHEN a user creates or edits a tool type
- THEN the interface type field is a dropdown (not checkboxes)
- AND the options are "web" and "terminal"
- AND only one option can be selected

### Requirement: Conditional Port Fields
The tool workshop SHALL conditionally show or hide port-related fields based on the selected interface type.

#### Scenario: Web tool shows port fields
- GIVEN a tool type with interface type "web"
- WHEN the user views the tool editor
- THEN the Default Port field is visible and required
- AND port-related config fields are shown

#### Scenario: Terminal tool hides port fields
- GIVEN a tool type with interface type "terminal"
- WHEN the user views the tool editor
- THEN the Default Port field is hidden
- AND port-related config fields are hidden or disabled

#### Scenario: Changing interface type updates visibility
- GIVEN a user changes interface type from "web" to "terminal"
- WHEN the change is applied
- THEN port fields are immediately hidden
- AND any port value is preserved but not validated

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