Frontend technical spec

Technical Design Rules (Frontend)

Prerequisite Detection

Inspect package.json, the lockfile, TypeScript/build configuration, CI definitions, and representative components before applying a tool- or framework-specific rule. Treat React, Vite, Next.js, a state library, form library, or script as available only when repository evidence names it. Label surrounding-pattern conclusions as inferred. When a missing decision changes rendering architecture, compatibility, security, or verification, stop and name the exact evidence or user decision required.

Basic Technology Stack Policy

These rules apply when repository configuration confirms a TypeScript-based React application. Select architecture by mapping current requirements and constraints to component responsibilities, state ownership, server/client boundaries, and observable verification points.

Environment Variable Management and Security

Environment Variable Management

• Use the build tool's client-exposure mechanism: Browser code can read only values explicitly exposed by the configured bundler/framework; server-only environment access remains outside client bundles
• Centrally manage environment variables through configuration layer
• Parse exposed values at one typed configuration boundary before application use
• Give a value a default only when requirements define valid behavior for absence; otherwise fail startup/build validation with the variable name and expected format

// Build tool environment variables (public values only; client-exposed vars need the VITE_ prefix)
const config = {
  apiUrl: import.meta.env.VITE_API_URL || 'http://localhost:3000',
  appName: import.meta.env.VITE_APP_NAME || 'My App'
}

// Does not work in frontend
const apiUrl = process.env.API_URL

Security (Client-side Constraints)

• CRITICAL: All frontend code is public and visible in browser
• Keep secrets server-side: Client-exposed configuration contains public values only; a backend or trusted service owns API keys, tokens, and credentials
• Keep local .env files outside version control and provide non-secret example files for required variable names
• Log and return only fields approved for the current trust boundary; redact passwords, tokens, and personal data

Correct Approach for Secrets:

// Security risk: API key exposed in browser
const apiKey = import.meta.env.VITE_API_KEY
const response = await fetch(`https://api.example.com/data?key=${apiKey}`)

// Correct: Backend manages secrets, frontend accesses via proxy
const response = await fetch('/api/data') // Backend handles API key authentication

Architecture Design

Frontend Architecture Patterns

React Component Architecture:

• Function Components: Mandatory; class components allowed solely for Error Boundaries (no hook equivalent)
• Custom Hooks: For logic reuse and dependency injection
• Component Hierarchy: Atoms -> Molecules -> Organisms -> Templates -> Pages
• Props-driven: Components receive all necessary data via props
• Co-location: Place tests, styles, and related files alongside components

Select a component/state pattern using these rules:

• Keep state local when one component subtree owns every read and write
• Use Context when multiple descendants require the same low-frequency state and the provider boundary is explicit
• Use a server-state library only when the configured dependency exists and caching, deduplication, background refresh, or request lifecycle state is required
• Introduce an additional state-management dependency only when current requirements cannot be covered by local state, reducer state, existing Context, or the repository's established state mechanism

State Management Patterns:

• Local State: useState for component-specific state
• Context API: For sharing state across component tree (theme, auth, etc.)
• Custom Hooks: Encapsulate state logic and side effects
• Server State: React Query or SWR for API data caching

Unified Data Flow Principles

Client-side Data Flow

Maintain consistent data flow throughout the React application:

• Single Source of Truth: Each piece of state has one authoritative source

  • UI state: Component state or Context
  • Server data: API responses cached in React Query/SWR
  • Form data: Controlled components with React Hook Form

• Unidirectional Flow: Data flows top-down via props

  API Response -> State -> Props -> Render -> UI
  User Input -> Event Handler -> State Update -> Re-render
  

• Immutable Updates: Use immutable patterns for state updates

  // Immutable state update
  setUsers(prev => [...prev, newUser])
  
  // Invalid mutable state update
  users.push(newUser)
  setUsers(users)
  

Type Safety in Data Flow

• Frontend -> Backend: Props/State (Type Guaranteed) -> API Request (Serialization)
• Backend -> Frontend: API Response (unknown) -> Type Guard -> State (Type Guaranteed)

// Type-safe data flow
async function fetchUser(id: string): Promise<User> {
  const response = await fetch(`/api/users/${id}`)
  const data: unknown = await response.json()

  if (!isUser(data)) {
    throw new Error('Invalid user data')
  }

  return data // Type guaranteed as User
}

Build and Testing

Select the package manager from the packageManager field, lockfile, or CI command in that order. Execute only scripts present in the selected manifest.

Build Commands

• Auto-detect and execute the following from package.json scripts:
  • Development server
  • Production build
  • Type check (no emit)

Testing Commands

• test - Run tests
• test:coverage - Run tests with coverage
• test:coverage:fresh - Run tests with coverage (fresh cache)
• test:safe - Safe test execution (with auto cleanup)
• cleanup:processes - Cleanup Vitest processes

Quality Check Requirements

Quality checks are mandatory upon implementation completion:

Phase 1-3: Basic Checks

• check - Biome (lint + format)
• build - TypeScript build

Transition evidence: every configured lint/format/type/build check exits successfully. A missing required script blocks the next phase until an equivalent repository command is identified.

Phase 4-5: Tests and Final Confirmation

• test - Test execution
• test:coverage:fresh - Coverage measurement
• check:all - Overall integrated check

Completion evidence: configured tests pass, the production build succeeds, and the integrated check remains clean after test fixes. Record an environment-dependent test as blocked with its exact prerequisite.

Coverage

• Treat coverage as a diagnostic signal for finding untested areas, not a target (a target gets gamed into trivial tests — Goodhart's Law)
• Concentrate test rigor on foundational, high-reuse units (shared components, custom hooks, utils) whose regression has the widest blast radius; higher-composition surfaces (organisms, pages) lean on integration/E2E coverage instead
• Any enforced numeric threshold is the project's CI/coverage config, not a goal in itself

Non-functional Requirements

• Browser Compatibility: Use the repository's Browserslist/build target or a named product requirement; record the source and test the affected browser-specific behavior
• Rendering Performance: Use the browser matrix and performance thresholds defined by project requirements, CI, or performance configuration. When none exists, report measured conditions as diagnostic evidence without inventing a pass threshold