Technical Design Rules (Frontend)

Basic Technology Stack Policy

TypeScript-based React application implementation. Architecture patterns should be selected according to project requirements and scale.

Environment Variable Management and Security

Environment Variable Management

• Use build tool's environment variable system: process.env does not work in browser environments
• Centrally manage environment variables through configuration layer
• Implement proper type safety with TypeScript
• Properly implement default value settings and mandatory checks

typescript
1// Build tool environment variables (public values only)
2const config = {
3  apiUrl: import.meta.env.API_URL || 'http://localhost:3000',
4  appName: import.meta.env.APP_NAME || 'My App'
5}
6
7// Does not work in frontend
8const apiUrl = process.env.API_URL

Security (Client-side Constraints)

• CRITICAL: All frontend code is public and visible in browser
• Never store secrets client-side: No API keys, tokens, or secrets in environment variables
• Do not include .env files in Git (same as backend)
• Prohibit logging of sensitive information (passwords, tokens, personal data)
• Do not include sensitive information in error messages

Correct Approach for Secrets:

typescript
1// Security risk: API key exposed in browser
2const apiKey = import.meta.env.API_KEY
3const response = await fetch(`https://api.example.com/data?key=${apiKey}`)
4
5// Correct: Backend manages secrets, frontend accesses via proxy
6const response = await fetch('/api/data') // Backend handles API key authentication

Architecture Design

Frontend Architecture Patterns

React Component Architecture:

• Function Components: Mandatory, class components deprecated
• 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

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

  typescript
  1// Immutable state update
  2setUsers(prev => [...prev, newUser])
  3
  4// Mutable state update (avoid)
  5users.push(newUser)
  6setUsers(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)

typescript
1// Type-safe data flow
2async function fetchUser(id: string): Promise<User> {
3  const response = await fetch(`/api/users/${id}`)
4  const data: unknown = await response.json()
5
6  if (!isUser(data)) {
7    throw new Error('Invalid user data')
8  }
9
10  return data // Type guaranteed as User
11}

Build and Testing

Use the appropriate run command based on the packageManager field in package.json.

Build Commands

• dev - Development server
• build - Production build
• preview - Preview production build
• type-check - 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

Phase 4-5: Tests and Final Confirmation

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

Coverage Requirements

• Mandatory: Unit test coverage must be 60% or higher
• Component-specific targets:
  • Atoms: 70% or higher
  • Molecules: 65% or higher
  • Organisms: 60% or higher
  • Custom Hooks: 65% or higher
  • Utils: 70% or higher

Non-functional Requirements

• Browser Compatibility: Chrome/Firefox/Safari/Edge (latest 2 versions)
• Rendering Time: Within 5 seconds for major pages