frontend-technical-spec

name	frontend/technical-spec
description	Frontend technical design rules including environment variables, architecture design, data flow, Nx workspace conventions, and build/testing commands.

Technical Design Rules (Frontend)

Basic Technology Stack Policy

The frontend lives inside the Nx workspace and is orchestrated through nx. The primary customer-facing application is the Next.js project at apps/app, with shared UI primitives located in libs/frontend/*. Use Nx generators and project boundaries to keep the architecture consistent. 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

// Build tool environment variables (public values only)
const config = {
  apiUrl: import.meta.env.API_URL || 'http://localhost:3000',
  appName: import.meta.env.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
• 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:

// Security risk: API key exposed in browser
const apiKey = import.meta.env.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

Nx Workspace Conventions

• Project placement: UI features that ship to production belong in apps/app. Reusable view logic or utilities must live under the appropriate libs/frontend/... subdirectory (components, hooks, lib, shared-ui, story-editor).
• Generators first: Scaffold new libraries or components with Nx generators (nx g @nx/next:component, nx g @nx/react:library) to inherit workspace standards (naming, testing, linting).
• Enforce boundaries: Respect module boundary rules defined for frontend tags (scope:frontend, type:ui, etc.). Add dependency tags before importing across feature areas.
• Project graph awareness: Use nx graph when designing features to understand the dependency impact and to avoid unintended cross-package coupling.

Frontend Architecture Patterns

Strictly adhere to selected project patterns. Project-specific details reference docs/rules/architecture/.

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

  // Immutable state update
  setUsers((prev) => [...prev, newUser]);
  
  // Mutable state update (avoid)
  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

Build Commands

# Development server (Next.js app at apps/app)
nx dev app

# Production build (includes type-checking via Next)
nx build app

# Preview built output locally
nx start app

# Type check shared frontend libraries (adjust list as libs evolve)
nx run-many -t typecheck --projects components,hooks,lib,shared-ui,story-editor

Testing Commands

Frontend tests run with Jest through Nx-managed targets.

# Run unit tests for the Next.js app entry point
nx test app

# Run unit tests for all frontend libraries (scope tag)
nx run-many -t test --projects tag:scope:frontend

# Run tests with coverage for all frontend libs
nx run-many -t test --projects tag:scope:frontend -- --coverage

# Start a watch-mode unit test session
nx test components --watch

Quality Check Requirements

Quality checks are mandatory upon implementation completion:

Phase 1-3: Basic Checks

nx run-many -t lint --projects app,tag:scope:frontend        # Biome (lint + format)
nx run-many -t typecheck --projects tag:scope:frontend       # Type-only checks for shared libs
nx build app                                                 # TypeScript build & Next.js compilation

Phase 4-5: Tests and Final Confirmation

nx test app                                  # Test execution for entry app
nx run-many -t test --projects tag:scope:frontend --skip-nx-cache -- --coverage --runInBand   # Coverage measurement (forces fresh run)
nx run-many -t lint --projects app,tag:scope:frontend --skip-nx-cache                        # Lint verification without cache
nx run-many -t typecheck --projects tag:scope:frontend --skip-nx-cache                        # Type-only verification

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