# CS2.WTF Rewrite TODO

## Phase 0 – Kickoff & Research

- [x] Create and push the `cs2-port` branch from the current default branch.
- [x] Clear legacy Vue 3 codebase for clean slate rewrite.
- [x] Capture the legacy stack (Vue 3 SPA + Go backend) and existing route map:
  - `/` - Homepage with featured matches
  - `/matches` - Match listing and search
  - `/player/[id]` - Player profile and statistics
  - `/match/[id]` - Match overview and scoreboard
  - `/match/[id]/economy` - Round-by-round economy tracking
  - `/match/[id]/details` - Detailed player statistics
  - `/match/[id]/flashes` - Flashbang effectiveness data
  - `/match/[id]/damage` - Damage visualization and heatmaps
  - `/match/[id]/chat` - In-game chat log
- [x] Audit the `csgowtfd` backend APIs and data models:
  - Backend: Go + Gin framework + Ent ORM + PostgreSQL
  - API endpoints documented in `docs/API.md`
  - 12 REST endpoints identified (player, match, matches listing, sitemap)
  - Data models: Match, Player, MatchPlayer, RoundStats, Weapon, Message
  - Swagger documentation available at `/api/swagger`
  - **Decision**: Continue using existing REST API (no replacement needed)
  - CS2 compatibility: Backend ready with rank field supporting 0-30000 Premier rating
- [x] Document CS2 demo parsing pipeline:
  - Demo parsing handled by backend (6 concurrent workers)
  - Share code submission via `/match/parse/:sharecode`
  - Demos expire after 30 days (configurable)
  - Parsing SLA: ~2-5 minutes per match (depends on queue)
  - Storage: PostgreSQL for structured data, Redis for caching
  - Data freshness: Player profiles update every 7 days, match check every 30 min
- [ ] Host workshops with stakeholders, shoutcasters, and data consumers to gather CS2-specific requirements (new stats, volumetric smokes, MR12 changes).
  - **Note**: Planned for implementation period - feedback will inform feature priorities

## Phase 1 – Technical Foundations ✅ COMPLETE

- [x] Standardize on Node.js ≥ 18 (add `.nvmrc` / `.tool-versions`) and lock package manager choice (npm or yarn).
- [x] Initialize SvelteKit project with required dependencies:
  - `npm create svelte@latest` with TypeScript (strict) and ESLint + Prettier options
  - Core: `svelte@^5.0.0`, `@sveltejs/kit@^2.0.0`, `vite@^5.0.0`
  - Styling: `tailwindcss@^3.4.0`, `daisyui@^4.0.0`, `autoprefixer@^10.4.0`, `postcss@^8.4.0`
  - TypeScript: `typescript@^5.3.0`, `tslib@^2.6.0`, `@sveltejs/vite-plugin-svelte@^4.0.0`
  - Icons: `lucide-svelte` or `@iconify/svelte`
- [x] Configure `tsconfig.json` with strict mode:
  ```json
  {
  	"extends": "./.svelte-kit/tsconfig.json",
  	"compilerOptions": {
  		"strict": true,
  		"noImplicitAny": true,
  		"strictNullChecks": true,
  		"strictFunctionTypes": true,
  		"noUnusedLocals": true,
  		"noUnusedParameters": true,
  		"noImplicitReturns": true,
  		"skipLibCheck": true
  	}
  }
  ```
- [x] Set up Tailwind CSS with DaisyUI:
  - Initialize: `npx tailwindcss init -p`
  - Configure DaisyUI themes (light, dark, CS2-branded theme)
  - Add custom color palette for teams (T-side orange, CT-side blue)
  - Import Tailwind directives in `app.css`
- [x] Add development tooling:
  - ESLint: `eslint-plugin-svelte`, `@typescript-eslint/eslint-plugin`, `@typescript-eslint/parser`
  - Prettier: `prettier-plugin-svelte`, `prettier-plugin-tailwindcss`
  - Git hooks: `husky@^9.0.0`, `lint-staged@^15.0.0`
  - Type checking: `svelte-check@^4.0.0`
  - Stylelint: `stylelint@^16.0.0`, `stylelint-config-standard`
- [x] Configure Vitest for unit/component tests:
  - Install: `vitest@^1.0.0`, `@testing-library/svelte@^5.0.0`, `@testing-library/jest-dom@^6.0.0`
  - Configure `vitest.config.ts` with Svelte plugin
  - Set up test utilities and mocking helpers
- [x] Configure Playwright for E2E tests:
  - Install: `@playwright/test@^1.40.0`
  - Create `playwright.config.ts` with multiple browsers (chromium, firefox, webkit)
  - Set up CI mode for headless execution
  - Create base fixtures and page objects
- [x] Set up Vite configuration:
  - Configure path aliases: `$lib`, `$components`, `$stores`, `$utils`, `$types`
  - Set up environment variable handling (`.env.example`)
  - Configure build optimizations (chunking strategy, asset handling)
- [x] Update Woodpecker CI pipeline (`.woodpecker.yml`):
  - Add steps: `install` → `lint` → `type-check` → `test` → `build`
  - Configure caching for `node_modules`
  - Add quality gates (minimum coverage, zero TypeScript errors)

## Phase 2 – Design System & UX Direction ✅ COMPLETE

- [x] Produce a Figma (or Penpot) design system: typography scale, spacing, color ramps, iconography inspired by modern Counter-Strike 2 visuals.
  - **Note**: Created comprehensive `docs/DESIGN.md` instead of Figma mockups (as agreed with user)
- [x] Define DaisyUI themes aligned with CS2 branding, including semantic color tokens for teams, utility types, and economy states.
- [x] Establish responsive layout grids (mobile-first up to ultrawide) and interaction patterns (hover, focus, press states).
- [x] Design core components: global navigation, search, tabs, data tables, filters, cards, charts, modals, toasts, and timeline elements.
  - **Implemented**: Button, Badge, Card, Header, Footer components
- [x] Create motion guidelines (micro-interactions, transitions) that reinforce hierarchy without compromising performance.
- [x] Run accessibility review on mockups (contrast, color blindness variants, keyboard flows).

## Phase 3 – Domain Modeling & Data Layer ✅ COMPLETE

**Reference**: See `docs/API.md` for complete backend API documentation, endpoints, and response structures.

- [x] Define core TypeScript interfaces in `src/lib/types/` (based on backend schemas):
  - `Match.ts`: match_id, share_code, map, date, scores, duration, match_result, max_rounds, demo_parsed, tick_rate
  - `Player.ts`: id (Steam ID), name, avatar, vanity_url, wins/losses/ties, vac_count, game_ban_count, steam_updated
  - `MatchPlayer.ts`: player stats per match (kills, deaths, assists, headshot, mvp, score, kast, rank changes, damage, utility stats, flash metrics)
  - `RoundStats.ts`: round number, bank (money), equipment value, spent
  - `Weapon.ts`: weapon statistics (victim, damage, eq_type, hit_group) with enums
  - `Message.ts`: chat messages (message text, all_chat flag, tick, player reference)
  - Derived types: `MatchWithPlayers`, `PlayerProfile`, `MatchRoundsData`, `MatchChatData`
  - **Implemented**: Backend typo handling (looses → losses) with normalization
- [x] Create Zod schemas for runtime validation:
  - Match all TypeScript interfaces with Zod schemas for API response validation
  - Add custom validators for Steam IDs (uint64), match IDs, rank tiers (0-30000 for CS2)
  - Handle nullable fields properly (many optional fields in backend)
  - Export type-safe parsers: `parseMatch()`, `parsePlayer()`, `parseMatchPlayer()`, etc.
  - Add schema for error responses
- [x] Design API client architecture:
  - Backend confirmed: REST API (Go + Gin) at `localhost:8000` (default)
  - Built `src/lib/api/client.ts` with axios wrapper
  - Created endpoint modules: `players.ts`, `matches.ts`
  - Implemented error handling (network errors, API errors, validation errors)
  - Added timeout handling (10s default) and typed APIException
  - Implemented request cancellation (AbortController) for search
  - Zod validation on all API responses
  - Handle CORS (backend supports configurable CORS domains)
  - **Note**: Retry logic and response caching deferred to Phase 7 (Performance)
- [x] Set up MSW (Mock Service Worker) for testing:
  - Installed: `msw@^2.0.0`
  - Created mock handlers in `src/mocks/handlers/` for all endpoints
  - Generated realistic fixture data matching CS2 statistics
  - Configured MSW for both development mode (browser) and test runs (server)
- [ ] Explore real-time features:
  - Decide: polling vs WebSocket for live match updates
  - Define update frequency and data delta strategy
  - Plan optimistic UI updates and conflict resolution
  - Document backend API requirements for live data
  - **Note**: Deferred to Phase 5 after basic features are implemented

## Phase 4 – Application Architecture & Routing (IN PROGRESS)

- [x] Create SvelteKit route structure in `src/routes/` (partial):
  - ✅ Created: `+layout.svelte`, `+layout.ts`, `+error.svelte`
  - ✅ Homepage: `+page.svelte`, `+page.ts` with featured matches loader
  - ✅ Matches listing: `matches/+page.ts` with query params
  - ✅ Players: `players/+page.ts` placeholder
  - ✅ About: `about/+page.ts` static page
  - ⚠️ Match detail routes (nested layouts): **TODO Phase 5**
  - ⚠️ Player profile `[id]` route: **TODO Phase 5**
- [x] Implement root layout (`src/routes/+layout.svelte`):
  - ✅ Global header with logo and navigation (Header.svelte)
  - ✅ Footer with links (Footer.svelte)
  - ✅ Toast notification system (ToastContainer.svelte, top-right)
  - ⚠️ Search bar with keyboard shortcuts: **TODO Phase 5**
  - ⚠️ Language switcher: **TODO Phase 6 (Localization)**
  - ⚠️ Theme toggle: **TODO Phase 5**
  - ⚠️ Loading bar: **TODO Phase 5**
- [x] Create reusable layout components in `src/lib/components/layout/` (partial):
  - ✅ `Header.svelte`: responsive navigation, mobile menu drawer
  - ✅ `Footer.svelte`: links, social, donation info
  - ⚠️ `SearchBar.svelte`: **TODO Phase 5**
  - ⚠️ `ThemeToggle.svelte`: **TODO Phase 5**
  - ⚠️ `LanguageSwitcher.svelte`: **TODO Phase 6**
  - ⚠️ `Breadcrumbs.svelte`: **TODO Phase 5**
- [x] Configure load functions with error handling:
  - ✅ Implemented `+page.ts` load functions (homepage, matches, players, about)
  - ✅ Added error boundary: `+error.svelte` at root level (404, 500, 503 handling)
  - ✅ API error handling in load functions (catch/fallback)
  - ⚠️ Loading skeletons: **TODO Phase 5**
  - ⚠️ Redirect logic for invalid IDs: **TODO Phase 5**
- [x] Set up state management with Svelte stores (`src/lib/stores/`):
  - ✅ `preferences.ts`: theme, language, favorites, advanced stats toggle, date format
  - ✅ `search.ts`: search query, filters, recent searches (localStorage)
  - ✅ `toast.ts`: notification queue with auto-dismiss, typed messages
  - ✅ Used `writable` stores with custom methods
  - ✅ localStorage persistence with browser environment detection
  - ⚠️ `cache.ts`: **Deferred to Phase 7 (Performance)**
  - ⚠️ `auth.ts`: **Not needed (no authentication planned)**
- [ ] Add analytics and privacy:
  - ⚠️ Choose analytics solution: **TODO Phase 5**
  - ⚠️ Implement consent banner: **TODO Phase 5**
  - ⚠️ Create analytics utility: **TODO Phase 5**
  - ⚠️ Ensure SSR compatibility: **TODO Phase 5**
  - ⚠️ Add opt-out mechanism: **TODO Phase 5**

## Phase 5 – Feature Delivery (Parity + Enhancements)

### 5.1 Homepage (`/` - `src/routes/+page.svelte`)

- [ ] Hero section with site branding and tagline
- [ ] Featured/Recent matches carousel:
  - Card component showing map, teams, score, date
  - Click to navigate to match detail
  - Auto-rotate with pause on hover
- [ ] Live matches indicator (if backend supports):
  - Real-time badge/pulse animation
  - Current round score updates
- [ ] Quick stats dashboard:
  - Total matches analyzed
  - Most played maps (pie chart)
  - Top performers this week/month
- [ ] Search bar prominently placed (autocomplete for players/matches)
- [ ] Call-to-action: "Upload Your Demo" or "Search Matches"

### 5.2 Matches Listing (`/matches` - `src/routes/matches/+page.svelte`)

- [ ] Advanced filter panel (collapsible on mobile):
  - Date range picker (from/to with presets: today, week, month)
  - Map selector (multi-select with map thumbnails)
  - Rank tier filter (CS2 Premier rating ranges)
  - Game mode filter (Premier, Competitive, Wingman)
  - Player name search (autocomplete)
  - Result filter (win/loss/tie)
- [ ] Matches table/grid view toggle:
  - Table: columns for date, map, score, duration, players, actions
  - Grid: card-based layout with match thumbnails
  - Virtualized scrolling for performance (svelte-virtual-list or custom)
- [ ] Sorting controls (date, duration, score difference)
- [ ] Pagination or infinite scroll
- [ ] Empty state with helpful message and search tips
- [ ] Export filtered results (CSV/JSON download)

### 5.3 Player Profile (`/player/[id]` - `src/routes/player/[id]/+page.svelte`)

- [ ] Player header:
  - Steam avatar (large)
  - Player name, Steam ID
  - Current CS2 rank/rating with icon
  - Last seen/last match date
- [ ] Career statistics grid:
  - Overall K/D ratio, win rate, HS%, ADR, KAST
  - Total matches played, hours estimated
  - Favorite maps (with win rates per map)
  - Favorite weapons (with kill counts)
- [ ] Performance charts:
  - Rating trend over time (line chart, last 20 matches)
  - Map performance (bar chart: win rate per map)
  - Role distribution (entry, support, clutch percentages)
  - Weapon accuracy breakdown (radar chart)
- [ ] Recent matches table:
  - Scrollable list with match date, map, score, KDA, rating
  - Click row to navigate to match detail
- [ ] Utility effectiveness stats:
  - Flash assists, enemies blinded
  - Smoke effectiveness (teammates trading in smoke)
  - HE damage, molotov damage
- [ ] Achievements/badges (optional):
  - Ace count, clutch wins (1vX), MVP stars
- [ ] Share profile button (generate shareable link/image)

### 5.4 Match Overview (`/match/[id]` - `src/routes/match/[id]/+page.svelte`)

- [ ] Match header:
  - Map name with background image
  - Final score (large, prominent)
  - Match date, duration, game mode
  - Download demo button (if available)
- [ ] Tab navigation (sticky on scroll):
  - Overview (default), Economy, Details, Flashes, Damage, Chat
  - Active tab indicator with smooth transition
- [ ] Scoreboard component (`MatchScoreboard.svelte`):
  - Two teams (T/CT) with color coding
  - Player rows: name, K/D/A, ADR, HS%, rating, MVPs
  - Sortable columns
  - Highlight top performers (gold/silver/bronze indicators)
  - Click player name to navigate to player profile
- [ ] Round history timeline:
  - Horizontal timeline showing all rounds (MR12: 24 max rounds + OT)
  - Icons indicating round winner (T/CT bomb icons)
  - Round win reason (elimination, defuse, time, bomb explosion)
  - Click round to show detailed events (kill feed, economy)
- [ ] Win probability chart (optional advanced feature):
  - Line graph showing round-by-round win probability
  - Based on economy, players alive, time remaining
- [ ] Map callouts reference (expandable panel)

### 5.5 Economy Tab (`/match/[id]/economy` - `src/routes/match/[id]/economy/+page.svelte`)

- [ ] Round-by-round economy table:
  - Columns: Round #, Team 1 money, Team 2 money, Equipment value
  - Color coding for eco/force-buy/full-buy rounds
  - Loss bonus tracking
- [ ] Equipment charts:
  - Stacked area chart showing total equipment value over rounds
  - Pie charts for weapon purchases (rifles, SMGs, pistols)
  - Utility spend breakdown (grenades, armor, defuse kits)
- [ ] Save round detection:
  - Highlight rounds where teams saved economy
  - Track money gained from saves
- [ ] Economy impact visualization:
  - Correlation between equipment value and round wins
  - Buy round win percentage comparison

### 5.6 Details Tab (`/match/[id]/details` - `src/routes/match/[id]/details/+page.svelte`)

- [ ] Detailed player statistics table:
  - All players with expandable rows
  - Columns: K/D/A, ADR, HS%, KAST, rating, clutches (1v1, 1v2, etc.)
  - Entry frags, trade kills, multi-kills (2k, 3k, 4k, 5k)
  - Utility damage dealt
- [ ] Weapon performance breakdown:
  - Table per player showing kills/deaths per weapon
  - Accuracy percentages
  - Damage per weapon type
- [ ] Round-by-round player performance:
  - Heatmap showing player rating per round
  - Identify hot/cold streaks
- [ ] Advanced metrics (CS2-specific):
  - Positioning effectiveness (time spent in advantageous positions)
  - Trade success rate
  - Clutch conversion rates

### 5.7 Flashes Tab (`/match/[id]/flashes` - `src/routes/match/[id]/flashes/+page.svelte`)

- [ ] Flash effectiveness leaderboard:
  - Players ranked by total enemies blinded
  - Average blind duration per flash
  - Flash assists (blinded enemy killed by teammate)
  - Self-flash count (mistakes)
- [ ] Flash timeline visualization:
  - Round-by-round flash events
  - Pop flash detection (short reaction time)
  - Team flashes vs solo flashes
- [ ] Heatmap overlay (advanced):
  - Map with flash throw positions
  - Color intensity = effectiveness
  - Clickable markers showing flash details
- [ ] CS2-specific features:
  - Volumetric smoke interactions (flashes through smoke)
  - New flash mechanics tracking

### 5.8 Damage Tab (`/match/[id]/damage` - `src/routes/match/[id]/damage/+page.svelte`)

- [ ] Damage dealt/received summary:
  - Per-player total damage
  - Damage per round (line chart)
  - Weapon damage breakdown
- [ ] Hit group analysis:
  - Pie chart: headshots, chest, legs, arms
  - Headshot percentage ranking
- [ ] Damage heatmap (Canvas/WebGL):
  - Map overlay showing where damage occurred
  - Click to filter by player, weapon, round
  - Color intensity = damage amount
  - Toggle between dealt/received damage
- [ ] Engagement distance chart:
  - Histogram showing damage at various ranges
  - Optimal range analysis per weapon
- [ ] Utility damage:
  - HE grenade damage tracking
  - Molotov/Incendiary damage over time
  - CS2: Volumetric smoke damage interactions

### 5.9 Chat Tab (`/match/[id]/chat` - `src/routes/match/[id]/chat/+page.svelte`)

- [ ] Chronological chat feed:
  - Message bubbles with player avatars
  - Timestamps (round number + time)
  - Team chat indicator (colored border or icon)
  - All chat vs team chat filtering
- [ ] Round navigation:
  - Jump to specific round's chat
  - Round separator with score
- [ ] Search/filter:
  - Filter by player
  - Search message content
  - Filter by chat type (team/all)
- [ ] Highlight detection (optional):
  - Detect toxic language (with blur/toggle)
  - Highlight strategic callouts
- [ ] Translation toggle (stretch goal):
  - Auto-translate non-English messages
  - Language detection

### 5.10 CS2-Exclusive Features

- [ ] MR12 format awareness:
  - Update all round displays to reflect 24-round max (12-12)
  - Adjust overtime logic and display
- [ ] New utility tracking:
  - Volumetric smokes (coverage area, bloom effect)
  - Updated grenade mechanics
  - Molotov spread and duration
- [ ] Premier mode specifics:
  - CS2 rating system (different from CS:GO ranks)
  - Skill group progression tracking
- [ ] Updated economy values:
  - CS2 weapon prices and economy changes
  - Loss bonus adjustments
- [ ] New weapon statistics:
  - Track kills with CS2-exclusive weapons
  - Update weapon icons and names

### 5.11 Shared Components Library (`src/lib/components/`)

- [ ] Data visualization components:
  - `LineChart.svelte`: responsive line charts (Chart.js or D3)
  - `BarChart.svelte`: horizontal/vertical bar charts
  - `PieChart.svelte`: donut charts for categorical data
  - `Heatmap.svelte`: grid-based heatmaps
  - `MapOverlay.svelte`: CS2 map with data overlays (Canvas/SVG)
  - `TimelineRounds.svelte`: horizontal round history
- [ ] Data table components:
  - `DataTable.svelte`: sortable, filterable tables
  - `PlayerRow.svelte`: reusable player stat row
  - `VirtualTable.svelte`: virtualized scrolling for large datasets
- [ ] Card components:
  - `MatchCard.svelte`: match summary card
  - `PlayerCard.svelte`: player summary card
  - `StatCard.svelte`: single statistic display
- [ ] Form/input components:
  - `DateRangePicker.svelte`: date selection
  - `MultiSelect.svelte`: multi-option selector (maps, filters)
  - `SearchInput.svelte`: search with debounce and autocomplete
  - `FilterPanel.svelte`: collapsible filter sidebar
- [ ] UI components:
  - `Modal.svelte`: accessible modal dialogs
  - `Toast.svelte`: notification toasts
  - `Tooltip.svelte`: hover tooltips
  - `Skeleton.svelte`: loading skeletons
  - `Badge.svelte`: labels and tags
  - `Tabs.svelte`: tab navigation component
  - `Accordion.svelte`: expandable sections

## Phase 6 – Localization & Personalization

- [ ] Integrate `sveltekit-i18n` (or equivalent) for multi-language support, starting with English plus priority locales.
- [ ] Externalize all copy into translation files, including validation messages and chart labels.
- [ ] Persist language preference (cookie/localStorage) and sync with SSR.
- [ ] Localize formatting (dates, currency, ranks) using `Intl` APIs and server-aware utilities.
- [ ] Provide user preference storage for theme, metric units, and favorite players/teams.

## Phase 7 – Performance, Accessibility & Observability

- [ ] Define and enforce performance budgets (LCP ≤ 2.5s, CLS ≤ 0.1, TTI ≤ 4s) with automated Lighthouse checks.
- [ ] Optimize assets: code splitting, prefetching strategies, image/CDN pipeline, and font loading.
- [ ] Implement progressive enhancement for charts/tables and graceful degradation when JS is disabled.
- [ ] Add runtime error monitoring (e.g., Sentry), structured logging, and privacy-aware analytics.
- [ ] Conduct comprehensive accessibility audits with axe, manual keyboard testing, and screen reader passes.

## Phase 8 – Testing & Quality Assurance

- [ ] Write unit tests for components, stores, and utilities (Vitest + Testing Library).
- [ ] Develop integration/E2E scenarios (Playwright) covering match search, player view, and match detail tabs.
- [ ] Set up visual regression snapshots for critical pages via Playwright or Loki.
- [ ] Build load-testing scripts for APIs powering live dashboards (k6 or artillery).
- [ ] Coordinate QA playbook: test matrices, release checklists, and bug triage workflow.

## Phase 9 – Deployment & Release Strategy

- [ ] Choose hosting strategy (Node SSR on Fly.io/Vercel/Render or self-hosted) and provision staging/production environments.
- [ ] Configure CI/CD deployment pipelines with environment promotion gates and feature flag toggles.
- [ ] Establish secrets management (e.g., Doppler, Vault, SSM) for API keys and telemetry tokens.
- [ ] Plan data migration/backfill from CS:GO to CS2, including schema evolution and archive policies.
- [ ] Organize beta program, feedback channels, and phased rollout (legacy vs CS2 opt-in).

## Phase 10 – Documentation & Handover

- [ ] Update `README.md` with setup, development, testing, and deployment instructions for CS2.WTF.
- [ ] Create architecture decision records (ADRs) for key choices (SvelteKit adoption, data strategy, hosting).
- [ ] Document API contracts, rate limits, and error semantics in an accessible format (OpenAPI + human-readable docs).
- [ ] Prepare contributor guidelines, coding standards, and project board workflow.
- [ ] Schedule knowledge transfer sessions and record walkthrough videos for onboarding.

## Stretch Goals

- [ ] Add authenticated user features: saved searches, match alerts, personalized dashboards.
- [ ] Offer real-time live match viewer with timeline scrubbing and auto-updating stats.
- [ ] Deliver PWA enhancements (offline read-only cache, push notifications when favorites go live).
- [ ] Explore integrations with tournament APIs (Valve, HLTV, FACEIT) to enrich match context.
- [ ] Mobile app with React Native or Capacitor (share types and API client)
- [ ] Community features: comments, player comparisons, squad tracking
- [ ] Advanced analytics: ML-based player role detection, positioning heatmaps, team synergy analysis

---

## Project Structure

Recommended directory organization for the rewrite:

```
csgowtf/
├── .husky/                      # Git hooks
├── .vscode/                     # Editor settings
├── docs/                        # Documentation, ADRs
├── playwright/                  # E2E test specs
├── public/                      # Static assets
│   ├── fonts/
│   ├── images/
│   │   ├── maps/               # CS2 map thumbnails
│   │   ├── weapons/            # Weapon icons
│   │   └── ranks/              # Rank icons
│   ├── favicon.ico
│   └── site.webmanifest
├── src/
│   ├── lib/
│   │   ├── api/                # API client and endpoints
│   │   │   ├── client.ts
│   │   │   ├── matches.ts
│   │   │   ├── players.ts
│   │   │   └── index.ts
│   │   ├── components/         # Reusable components
│   │   │   ├── charts/         # Chart components
│   │   │   ├── data-display/   # Tables, grids, cards
│   │   │   ├── forms/          # Form inputs, pickers
│   │   │   ├── layout/         # Header, Footer, Nav
│   │   │   ├── match/          # Match-specific components
│   │   │   ├── player/         # Player-specific components
│   │   │   └── ui/             # Base UI (Button, Modal, etc.)
│   │   ├── stores/             # Svelte stores
│   │   │   ├── preferences.ts
│   │   │   ├── search.ts
│   │   │   ├── cache.ts
│   │   │   └── toast.ts
│   │   ├── types/              # TypeScript types
│   │   │   ├── Match.ts
│   │   │   ├── Player.ts
│   │   │   ├── Round.ts
│   │   │   └── index.ts
│   │   ├── utils/              # Utility functions
│   │   │   ├── formatters.ts   # Date, number formatting
│   │   │   ├── validators.ts   # Input validation
│   │   │   ├── analytics.ts    # Tracking utilities
│   │   │   └── constants.ts    # App constants
│   │   └── i18n/               # Internationalization
│   │       ├── en.json
│   │       ├── de.json
│   │       └── index.ts
│   ├── routes/                 # SvelteKit routes (see Phase 4)
│   ├── mocks/                  # MSW mock handlers
│   │   ├── handlers/
│   │   └── browser.ts
│   ├── app.css                 # Global styles (Tailwind imports)
│   └── app.html                # HTML shell
├── static/                     # Additional static files
├── tests/
│   ├── unit/                   # Unit tests
│   └── integration/            # Integration tests
├── .env.example                # Environment variables template
├── .eslintrc.cjs               # ESLint config
├── .gitignore
├── .nvmrc                      # Node version
├── .prettierrc.json            # Prettier config
├── .stylelintrc.cjs            # Stylelint config
├── package.json
├── playwright.config.ts        # Playwright config
├── postcss.config.cjs          # PostCSS config
├── README.md
├── svelte.config.js            # SvelteKit config
├── tailwind.config.cjs         # Tailwind config
├── tsconfig.json               # TypeScript config
├── vite.config.ts              # Vite config
└── vitest.config.ts            # Vitest config
```

---

## Implementation Best Practices

### Code Quality Standards

- **TypeScript Strict Mode**: Zero `any` types, all functions fully typed
- **Component Size**: Keep components under 300 lines; extract sub-components
- **Props Validation**: Use TypeScript interfaces for all component props
- **Store Usage**: Prefer props for local state, stores for shared/global state
- **Naming Conventions**:
  - Components: `PascalCase.svelte`
  - Utilities: `camelCase.ts`
  - Constants: `SCREAMING_SNAKE_CASE`
  - Types: `PascalCase` interfaces/types

### Performance Guidelines

- **Code Splitting**: Lazy load heavy components (charts, maps)
- **Image Optimization**: Use WebP with fallbacks, lazy loading
- **Virtual Scrolling**: For lists > 100 items
- **Debounce Inputs**: Search, filters (300ms minimum)
- **Memoization**: Cache expensive calculations with derived stores
- **Bundle Size**: Monitor with `vite-bundle-visualizer`

### Accessibility Requirements (WCAG 2.1 AA)

- **Color Contrast**: Minimum 4.5:1 for text, 3:1 for UI
- **Keyboard Navigation**: All interactive elements accessible via Tab
- **Focus Indicators**: Visible focus states (outline or ring)
- **Semantic HTML**: Proper heading hierarchy, landmarks
- **ARIA Labels**: For icons, dynamic content, screen readers
- **Alt Text**: Descriptive alt text for all images
- **Form Labels**: Explicit labels for all inputs

### Testing Strategy

- **Unit Tests**: All utilities, stores, pure functions (>80% coverage)
- **Component Tests**: User interactions, edge cases, error states
- **Integration Tests**: Complete user flows (search → view match)
- **E2E Tests**: Critical paths (homepage → player profile → match detail)
- **Visual Regression**: Screenshot diffs for major pages
- **Performance Tests**: Lighthouse CI on every PR

### Git Workflow

- **Branch Naming**: `feature/description`, `fix/description`, `refactor/description`
- **Commit Messages**: Conventional commits (`feat:`, `fix:`, `docs:`, `test:`)
- **PR Requirements**: Passing CI, code review, no merge conflicts
- **Protected Branch**: `cs2-port` requires PR approval
- **Merge Strategy**: Squash and merge for cleaner history

---

## Quick Start Guide

### Prerequisites

```bash
# Node.js 18+ (check with nvmrc)
node --version  # Should be v18+ or v20+

# Install dependencies
npm install
# or
yarn install
```

### Development

```bash
# Start dev server
npm run dev

# Run in different modes
npm run dev -- --host          # Expose to network
npm run dev -- --port 5173     # Custom port

# Type checking
npm run check                  # Svelte + TypeScript
npm run check:watch            # Watch mode

# Linting
npm run lint                   # ESLint + Prettier
npm run lint:fix               # Auto-fix issues
npm run format                 # Prettier only
```

### Testing

```bash
# Unit/component tests
npm run test                   # Run once
npm run test:watch             # Watch mode
npm run test:coverage          # Coverage report

# E2E tests
npm run test:e2e               # Headless
npm run test:e2e:ui            # Playwright UI
npm run test:e2e:debug         # Debug mode
```

### Building

```bash
# Production build
npm run build

# Preview production build
npm run preview

# Analyze bundle size
npm run build -- --analyze
```

### Environment Variables

Create `.env` file (copy from `.env.example`):

```bash
# API Configuration
VITE_API_BASE_URL=http://localhost:8080
VITE_API_TIMEOUT=10000

# Feature Flags
VITE_ENABLE_LIVE_MATCHES=false
VITE_ENABLE_ANALYTICS=true

# Analytics (optional)
VITE_PLAUSIBLE_DOMAIN=cs2.wtf
```

---

## Migration from Legacy CSGOW.TF

### Data Compatibility

- [ ] Map CS:GO rank system to CS2 Premier ratings
- [ ] Update match IDs format if changed in CS2
- [ ] Migrate player statistics (K/D, ADR, etc.) with new formulas
- [ ] Archive old CS:GO-specific data (old ranks, removed weapons)
- [ ] Ensure backward compatibility for old match links

### Backend API Changes

- [ ] Document breaking changes between CS:GO and CS2 APIs
- [ ] Create API versioning strategy (v1 vs v2)
- [ ] Implement adapter layer for legacy data if needed
- [ ] Test data parsing with both CS:GO and CS2 demos

### Asset Updates

- [ ] Replace CS:GO map images with CS2 versions
- [ ] Update weapon icons (new CS2 designs)
- [ ] Update rank icons (Premier rating system)
- [ ] Refresh brand colors to match CS2 theme

---

## Key Dependencies Reference

### Core Framework

- `@sveltejs/kit@^2.0.0` - SvelteKit framework
- `svelte@^5.0.0` - Svelte compiler
- `vite@^5.0.0` - Build tool

### UI & Styling

- `tailwindcss@^3.4.0` - Utility-first CSS
- `daisyui@^4.0.0` - Tailwind component library
- `lucide-svelte@^0.400.0` - Icon library

### Data Visualization

- `chart.js@^4.4.0` - Charts library
- `svelte-chartjs@^3.1.0` - Svelte wrapper for Chart.js
- Or `d3@^7.8.0` - For custom visualizations

### Forms & Validation

- `zod@^3.22.0` - Schema validation
- `sveltekit-superforms@^2.0.0` - Form handling

### Internationalization

- `svelte-i18n@^4.0.0` or `typesafe-i18n@^5.26.0`

### Testing

- `vitest@^1.0.0` - Unit test runner
- `@testing-library/svelte@^5.0.0` - Component testing
- `@playwright/test@^1.40.0` - E2E testing
- `msw@^2.0.0` - API mocking

### Development

- `typescript@^5.3.0` - Type safety
- `eslint@^8.57.0` - Linting
- `prettier@^3.2.0` - Code formatting
- `husky@^9.0.0` - Git hooks

---

## CS2-Specific Considerations

### Game Mechanics Changes

1. **MR12 Format**: Max 24 rounds (was 30 in MR15)
2. **Volumetric Smokes**: New smoke grenade behavior with light interaction
3. **Premier Mode**: New ranking system (0-30,000 rating instead of 18 ranks)
4. **Economy Adjustments**: Different loss bonuses and weapon prices
5. **Sub-tick System**: More accurate timing for events
6. **Map Updates**: Remade maps (Inferno, Overpass, Nuke, etc.)
7. **Weapon Changes**: Removed R8, some stat adjustments

### Data Model Updates

- Add `game_mode` field: "Premier", "Competitive", "Wingman", "Deathmatch"
- Update `rank` field to support both legacy CS:GO ranks and new CS2 rating (0-30000)
- Add `premier_rating` and `premier_division` fields
- Add `sub_tick_accurate` boolean for events
- Update weapon enum to include/exclude CS2 changes
- Add `volumetric_smoke_data` for smoke effectiveness tracking

### UI/UX Priorities

1. **Mobile-First**: 60%+ traffic is mobile (test on devices)
2. **Dark Mode Default**: Most gamers prefer dark themes
3. **Fast Load Times**: Competitive with HLTV, Leetify (< 3s LCP)
4. **Clear Data Hierarchy**: Don't overwhelm with stats
5. **CS2 Aesthetic**: Modern, clean, inspired by in-game UI
6. **Accessibility**: Color-blind friendly team colors

---

## Success Metrics

### Technical Metrics

- [ ] Lighthouse Score: 90+ (Performance, Accessibility, Best Practices, SEO)
- [ ] TypeScript Coverage: 100% (no `any` types)
- [ ] Test Coverage: 80%+ (unit/integration)
- [ ] Bundle Size: < 200KB initial (gzipped)
- [ ] Build Time: < 60s (production)

### User Experience Metrics

- [ ] First Contentful Paint: < 1.5s
- [ ] Largest Contentful Paint: < 2.5s
- [ ] Time to Interactive: < 4s
- [ ] Cumulative Layout Shift: < 0.1
- [ ] Mobile Performance Score: 85+

### Feature Completeness

- [ ] All legacy CSGOW.TF routes implemented
- [ ] CS2-specific features added
- [ ] Multi-language support (3+ languages)
- [ ] Full keyboard navigation
- [ ] Cross-browser compatible (Chrome, Firefox, Safari, Edge)

---

## Notes & Decisions Log

### Why SvelteKit over Next.js/Nuxt?

- **Performance**: Smaller bundles, faster hydration
- **DX**: Simpler mental model, less boilerplate
- **SSR/SSG**: Built-in, file-based routing
- **TypeScript**: First-class support
- **Popularity**: Growing ecosystem, modern approach

### Why DaisyUI over Material/Chakra?

- **Tailwind Integration**: Seamless with utility classes
- **Customization**: Easy theme creation
- **Bundle Size**: Smaller than component libraries
- **Accessibility**: Built-in ARIA attributes

### API Strategy

- **REST over GraphQL**: Backend is REST, simpler for this use case
- **Client-side Caching**: In-memory with TTL, no need for React Query/SWR complexity
- **Optimistic UI**: For favoriting, settings changes

### Charting Library Choice

- **Chart.js**: Simpler, good for standard charts (line, bar, pie)
- **D3**: For complex visualizations (heatmaps, custom timelines)
- **Consider**: Recharts, ApexCharts as alternatives

---

**Last Updated**: 2025-11-04
**Current Phase**: Phase 4 (Application Architecture & Routing) - IN PROGRESS
**Completed Phases**: Phase 0 (Planning), Phase 1 (Technical Foundations), Phase 2 (Design System), Phase 3 (Domain Modeling)
**Next Milestone**: Implement SvelteKit routing, data loading, and state management