gridpilot.gg/docs/architecture/website/REACT_COMPONENT_ARCHITECTURE.md

# React Component Architecture (Concept)

This document defines the clean concept for React component architecture in `apps/website`.

## Core Principle

**Separation of concerns by responsibility, not just by file location.**

## The Four Layers

### 1. App Layer (`app/`)
**Purpose**: Entry points and data orchestration

**What lives here**:
- `page.tsx` - Server Components that fetch data
- `layout.tsx` - Root layouts
- `route.tsx` - API routes
- `*PageClient.tsx` - Client entry points that wire server data to client templates

**Rules**:
- `page.tsx` does ONLY data fetching and passes raw data to client components
- `*PageClient.tsx` manages client state and event handlers
- No UI rendering logic (except loading/error states)

**Example**:
```typescript
// app/teams/page.tsx
export default async function TeamsPage() {
  const query = new TeamsPageQuery();
  const result = await query.execute();
  
  if (result.isErr()) {
    return <ErrorTeams />;
  }
  
  return <TeamsPageClient teams={result.value.teams} />;
}

// app/teams/TeamsPageClient.tsx
'use client';
export function TeamsPageClient({ teams }: TeamsViewData) {
  const [searchQuery, setSearchQuery] = useState('');
  const router = useRouter();
  
  const handleTeamClick = (teamId: string) => {
    router.push(`/teams/${teamId}`);
  };
  
  return (
    <TeamsTemplate
      teams={teams}
      searchQuery={searchQuery}
      onSearchChange={setSearchQuery}
      onTeamClick={handleTeamClick}
    />
  );
}
```

### 2. Template Layer (`templates/`)
**Purpose**: Composition and layout of components

**What lives here**:
- Stateless component compositions
- Page-level layouts
- Component orchestration

**Rules**:
- Templates ARE stateless (no `useState`, `useEffect`)
- Templates CAN use `'use client'` for event handling and composition
- Templates receive ViewData (primitives) and event handlers
- Templates compose components and UI elements
- No business logic
- No data fetching

**Example**:
```typescript
// templates/TeamsTemplate.tsx
'use client';

export function TeamsTemplate({ teams, searchQuery, onSearchChange, onTeamClick }: TeamsTemplateProps) {
  return (
    <main>
      <Header>
        <SearchInput value={searchQuery} onChange={onSearchChange} />
      </Header>
      
      <TeamLeaderboardPreview 
        teams={teams} 
        onTeamClick={onTeamClick} 
      />
      
      <TeamGrid teams={teams} onTeamClick={onTeamClick} />
    </main>
  );
}
```

### 3. Component Layer (`components/`)
**Purpose**: Reusable app-specific components

**What lives here**:
- Components that understand app concepts (teams, races, leagues)
- Components that may contain state and business logic
- Components that orchestrate UI elements for app purposes

**Rules**:
- Can be stateful
- Can contain app-specific business logic
- Can use Next.js hooks (but not Next.js components like `Link`)
- Should be reusable within the app context
- **Strictly Forbidden**: Generic UI primitives (`Box`, `Surface`) and generic wrappers (`Layout`, `Container`)
- **Strictly Forbidden**: The `className` prop (styling must be handled by UI components)

**Example**:
```typescript
// components/teams/TeamLeaderboardPreview.tsx
'use client';

export function TeamLeaderboardPreview({ teams, onTeamClick }: Props) {
  // App-specific logic: medal colors, ranking, etc.
  const getMedalColor = (position: number) => { /* ... */ };
  
  return (
    <Card>
      <CardHeader>Top Teams</CardHeader>
      {teams.map((team, index) => (
        <TeamRow 
          key={team.id}
          team={team}
          position={index}
          onClick={() => onTeamClick(team.id)}
          medalColor={getMedalColor(index)}
        />
      ))}
    </Card>
  );
}
```

### 4. UI Layer (`ui/`)
**Purpose**: Generic, reusable UI primitives

**What lives here**:
- Pure UI elements with no app knowledge
- Generic building blocks
- Framework-agnostic components

**Rules**:
- Stateless (no `useState`, `useEffect`)
- No app-specific logic
- No Next.js imports
- Only receive props and render
- Maximum reusability
- **Strict Layering**: Generic primitives (`Box`, `Surface`, `Stack`, `Grid`) are internal to this layer.

**Example**:
```typescript
// ui/Button.tsx
export function Button({ children, variant, onClick }: ButtonProps) {
  return (
    <button 
      className={`btn btn-${variant}`}
      onClick={onClick}
    >
      {children}
    </button>
  );
}

// ui/Card.tsx
export function Card({ children, className }: CardProps) {
  return <div className={`card ${className}`}>{children}</div>;
}
```

## UI Layering & Primitives

To prevent "div wrapper" abuse and maintain architectural integrity, we enforce a strict boundary between **Primitives** and **Semantic UI**.

### 1. Primitives & Generic Wrappers (Forbidden in Components)
- **Primitives**: `Box`, `Surface` (in `ui/primitives/`)
- **Generic Wrappers**: `Layout`, `Container` (in `ui/`)
- **Internal only**: These should NEVER be imported by `components/`. They are for building semantic UI elements.
- **Full flexibility**: They allow arbitrary styling (bg, border, shadow, etc.) to build semantic components.

### 2. Semantic UI (Allowed in Components)
- **Building blocks**: `Card`, `Panel`, `Button`, `Table`.
- **Layout Components**: `Stack`, `Grid` (Restricted to layout-only props).
- **Restricted flexibility**: Semantic layout components are restricted to layout-only props. They do NOT allow styling props (bg, border, etc.).
- **Public API**: These are the only UI elements that should be imported by `components/` or `pages/`.

**Rule of thumb**: If you need a styled container in a component, use `Panel` or `Card`. If you need a new type of styled container, create it in `ui/` using primitives. Direct use of primitives or raw HTML tags in `components/` is forbidden.

## The Display Object Layer

**Purpose**: Reusable formatting and presentation logic

**What lives here**:
- `lib/display-objects/`
- Deterministic formatting functions
- Code-to-label mappings
- Value transformations for display

**Rules**:
- Class-based
- Immutable
- Deterministic
- No side effects
- No `Intl.*` or `toLocale*`

**Usage**:
```typescript
// lib/display-objects/RatingDisplay.ts
export class RatingDisplay {
  static format(rating: number): string {
    return rating.toFixed(0);
  }
  
  static getColor(rating: number): string {
    if (rating >= 90) return 'text-green';
    if (rating >= 70) return 'text-yellow';
    return 'text-red';
  }
}

// In ViewModel Builder
const viewModel = {
  rating: RatingDisplay.format(dto.rating),
  ratingColor: RatingDisplay.getColor(dto.rating)
};
```

## Dependency Flow

```
app/ (page.tsx)
  ↓ fetches data
app/ (*PageClient.tsx)
  ↓ manages state, creates handlers
templates/ (composition)
  ↓ uses components
components/ (app-specific)
  ↓ uses UI elements
ui/ (generic primitives)
```

## Decision Rules

### When to use *PageClient.tsx?
- When you need client-side state management
- When you need event handlers that use router/other hooks
- When server component needs to be split from client template

### When to use Template vs Component?
- **Template**: Page-level composition, orchestrates multiple components
- **Component**: Reusable app-specific element with logic

### When to use Component vs UI?
- **Component**: Understands app concepts (teams, races, leagues)
- **UI**: Generic building blocks (button, card, input)

### When to use Display Objects?
- When formatting is reusable across multiple ViewModels
- When mapping codes to labels
- When presentation logic needs to be deterministic

## Key Benefits

1. **Clear boundaries**: Each layer has a single responsibility
2. **Testability**: Pure functions at UI/Display layer
3. **Reusability**: UI elements can be used anywhere
4. **Maintainability**: Changes in one layer don't ripple
5. **Type safety**: Clear contracts between layers