Dawn of War: Definitive Edition Leaderboard Development

Expert assistant for working with the DoW:DE production leaderboard site at dow-de.com.

Project Context

This is a **production Next.js 14 + TypeScript application** that creates a public leaderboard site for Dawn of War: Definitive Edition. Data from Relic's Community API is enriched with Steam player names and stored in Supabase for features like player profiles, match history, and replay uploads.

**Live site**: https://www.dow-de.com

Tech Stack

Core Features Understanding

1. Leaderboards System

2. Player Profiles (`/profile/[profileId]`)

3. Replay System

4. Player Search

5. Premium Features Teaser

Development Instructions

Before Any Changes

1. **Always read files before modifying** - Never propose changes to code you haven't read

2. **Run TypeScript checks before deployment**:

```bash

npm run typecheck

```

3. **Understand data flow** - Review `src/lib/relic.ts` and `src/lib/supabase.ts` first

Key Implementation Rules

#### Data Accuracy Constraints

#### API Integration

- `GetAvailableLeaderboards` - 37 leaderboards (cached 24h)

- `getLeaderBoard2` - Player rankings (cached 5 min)

- `proxysteamuserrequest` - Steam name resolution

#### Caching Strategy

#### Performance Requirements

Critical Files Reference

**Core Logic**:

**Main UI Components**:

**API Routes Structure**:

Data Structures

```typescript

// Ladder row (API response + enrichment)

type LadderRow = {

rank: number

profileId: string

playerName: string

rating: number

wins: number

losses: number

winrate: number // (wins / (wins + losses)) * 100

streak: number

country?: string

lastMatchDate?: Date

faction?: string

level?: number

rankDelta?: number | null // 24h change

originalRank?: number // for multi-faction views

leaderboardId?: number

}

// Player (database)

type Player = {

profile_id: string

current_alias: string | null

country: string | null

steam_id64: string | null

level: number | null

xp: number | null

first_seen_at: string

last_seen_at: string

}

```

Development Workflow

Starting Development

```bash

npm run dev # Start dev server (localhost:3000)

npm run build # Production build

npm run typecheck # TypeScript validation (run before deploy!)

```

Environment Variables Required

```bash

Supabase (client-side)

NEXT_PUBLIC_SUPABASE_URL=

NEXT_PUBLIC_SUPABASE_ANON_KEY=

Supabase (server-side for scripts/admin)

SUPABASE_URL=

SUPABASE_SERVICE_ROLE_KEY=

Feature flags

NEXT_PUBLIC_ENABLE_PREMIUM_TEASER=false

```

Data Collection Scripts

Located in `scripts/` directory:

All scripts use `.env` for Supabase credentials.

Known Quirks & Workarounds

1. **Relic API Bug**: Returns `level: 1` for all players - compute from XP locally using `src/lib/xp-levels.ts`

2. **Steam Resolution**: ~90% success rate (some profiles private/missing) - graceful fallback to "Unknown"

3. **Combined 1v1 Views**: Offers both deduplicated (best faction per player) and multi-entry (all faction placements)

4. **Replay Parsing**: Requires temp file creation (Node.js buffer → file → parser)

5. **Large UI File**: `page.tsx` is ~42k tokens - use offset/limit when reading

Error Handling Guidelines

Database Schema Reference

**Core Tables**:

**Migrations**: Located in `supabase/migrations/`

**Edge Functions**: `supabase/functions/steam-player-count/`

Testing Checklist

Before deployment, verify:

Best Practices

1. **Always validate Relic API responses** - Data shape can vary

2. **Use proper TypeScript types** - Avoid `any`

3. **Implement loading states** - All data fetching should show progress

4. **Cache aggressively** - Follow existing cache duration patterns

5. **Handle errors gracefully** - User-facing messages, detailed server logs

6. **Test rate limits** - Verify throttling works as expected

7. **Document assumptions** - Comment complex logic, especially data transformations

8. **Keep UI responsive** - Mobile-first design principles

Common Tasks

Adding a New API Route

1. Create route in `src/app/api/[your-route]/route.ts`

2. Implement caching strategy (refer to existing routes)

3. Add error handling with appropriate status codes

4. Update TypeScript types if needed

5. Test with `npm run typecheck`

Modifying Leaderboard Display

1. **Read** `src/app/page.tsx` first (use offset/limit due to size)

2. Locate relevant component (tabs, filters, table)

3. Preserve existing caching and performance patterns

4. Test with different data scenarios (empty, full, loading)

Working with Database

1. Check `src/lib/supabase.ts` for client setup

2. Review schema in `supabase/migrations/`

3. Use Supabase client for all database operations

4. Handle real-time subscriptions appropriately

Debugging Relic API Issues

1. Check `src/lib/relic.ts` for retry logic

2. Verify `title=dow1-de` parameter is passed

3. Check rate limiting logs

4. Validate response data shape matches expectations

5. Review statgroup_id joins (not array position)

Production Deployment

The site auto-deploys to Vercel on push to main branch. Ensure:

1. All TypeScript checks pass

2. Environment variables are set in Vercel dashboard

3. Supabase migrations are applied

4. API rate limits are configured correctly

Support & Resources