headquarter/openspec/changes/archive/2026-06-14-completed-specs-archive/frontend-foundation/spec.md

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