csgowtf/TODO.md

CS2.WTF Rewrite TODO

Phase 0 – Kickoff & Research

• Create and push the cs2-port branch from the current default branch.
• Clear legacy Vue 3 codebase for clean slate rewrite.
• 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
• 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
• 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

• Standardize on Node.js ≥ 18 (add .nvmrc / .tool-versions) and lock package manager choice (npm or yarn).
• 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
• Configure tsconfig.json with strict mode:

  {
  	"extends": "./.svelte-kit/tsconfig.json",
  	"compilerOptions": {
  		"strict": true,
  		"noImplicitAny": true,
  		"strictNullChecks": true,
  		"strictFunctionTypes": true,
  		"noUnusedLocals": true,
  		"noUnusedParameters": true,
  		"noImplicitReturns": true,
  		"skipLibCheck": true
  	}
  }
  

• 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
• 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
• 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
• 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
• 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)
• 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

• 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)
• Define DaisyUI themes aligned with CS2 branding, including semantic color tokens for teams, utility types, and economy states.
• Establish responsive layout grids (mobile-first up to ultrawide) and interaction patterns (hover, focus, press states).
• Design core components: global navigation, search, tabs, data tables, filters, cards, charts, modals, toasts, and timeline elements.
  • Implemented: Button, Badge, Card, Header, Footer components
• Create motion guidelines (micro-interactions, transitions) that reinforce hierarchy without compromising performance.
• 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.

• 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
• 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
• 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)
• 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 ✅ COMPLETE

• Create SvelteKit route structure in src/routes/:
  • ✅ 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): /match/[id]/* with tabs
  • ✅ Player profile [id] route: /player/[id]
• 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 (SearchBar.svelte)
  • ⚠️ Language switcher: TODO Phase 6 (Localization)
  • ✅ Theme toggle (ThemeToggle.svelte)
• Create reusable layout components in src/lib/components/layout/:
  • ✅ Header.svelte: responsive navigation, mobile menu drawer
  • ✅ Footer.svelte: links, social, donation info
  • ✅ SearchBar.svelte: search with autocomplete
  • ✅ ThemeToggle.svelte: theme switching
  • ⚠️ LanguageSwitcher.svelte: TODO Phase 6
• Create base UI components in src/lib/components/ui/:
  • ✅ Modal.svelte, Skeleton.svelte, Tabs.svelte, Tooltip.svelte
  • ✅ Button.svelte, Badge.svelte, Card.svelte
  • ✅ Toast.svelte, ToastContainer.svelte
• Create domain components:
  • ✅ MatchCard.svelte in src/lib/components/match/
  • ✅ PlayerCard.svelte in src/lib/components/player/
• 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 created (Skeleton.svelte)
• 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: Deferred to Phase 7
  • ⚠️ Implement consent banner: Deferred to Phase 7
  • ⚠️ Create analytics utility: Deferred to Phase 7
  • ⚠️ Ensure SSR compatibility: Deferred to Phase 7
  • ⚠️ Add opt-out mechanism: Deferred to Phase 7

Phase 5 – Feature Delivery (Parity + Enhancements)

5.1 Homepage (/ - src/routes/+page.svelte) ✅ SUBSTANTIALLY COMPLETE

• 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 (5 second intervals)
  • ✅ Manual navigation arrows with temporary pause
  • ✅ Responsive slides (1/2/3 matches based on screen width)
• Processing matches indicator:
  • ✅ Badge with pulsing animation for unparsed demos
  • ✅ Count of matches being processed
• Quick stats dashboard:
  • ✅ Total matches analyzed (dynamic from last 50 matches)
  • ✅ Most played maps (pie chart with top 7 maps)
  • ✅ Recent activity stats cards
  • ⚠️ Top performers this week/month - Deferred (would require 50+ API calls for player details)
• Search bar in header (global navigation)
• Call-to-action sections ("Why CS2.WTF?", "Ready to improve?")
• Recently visited players component

5.2 Matches Listing (/matches - src/routes/matches/+page.svelte) ✅ COMPLETE (with documented blockers)

• Advanced filter panel (collapsible on mobile):
  • Date range picker (from/to with presets: today, week, month)
  • Map selector (multi-select with map thumbnails)
  • Result filter (win/loss/tie)
  • ⚠️ BLOCKED by backend: Rank tier filter (CS2 Premier rating ranges) - UI present with "Coming Soon" badge
  • ⚠️ BLOCKED by backend: Game mode filter (Premier, Competitive, Wingman) - UI present with "Coming Soon" badge
  • ⚠️ BLOCKED by backend: Player name search autocomplete - No /players/search endpoint exists, UI shows "Coming Soon" badge
    • Current functionality: Basic match ID/share code search works
    • Backend needs: New endpoint GET /players/search?q={query}&limit={limit} returning player suggestions
• Matches table/grid view toggle:
  • Table: columns for date, map, score, duration, players, actions
  • Grid: card-based layout with match thumbnails
  • View preference persisted to localStorage
  • Infinite scroll implemented (virtualized scrolling not needed - infinite scroll is the better UX)
• Sorting controls (date, duration, score difference)
• Infinite scroll with intersection observer
• Empty state with helpful message and search tips
• Export filtered results (CSV/JSON download)
• Share code input component for demo parsing
• Active filters display with clear functionality

Backend API Blockers (3 features waiting for backend support):

1. Player name search - Requires GET /players/search?q={query}&limit={limit}
2. Rank tier filter - Requires rank filtering in GET /matches endpoint
3. Game mode filter - Requires game_mode field and filtering in GET /matches endpoint

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

• Player header:
  • ✅ Steam avatar (placeholder with User icon)
  • ✅ Player name, Steam ID
  • ✅ Current CS2 rank/rating display
  • ✅ Favorite player toggle (heart icon)
• Career statistics grid:
  • ✅ Overall K/D ratio, win rate, HS%
  • ✅ Total matches played
  • ⚠️ Favorite maps/weapons: Deferred to future update (data available, visualization deferred)
• Performance charts:
  • ✅ Performance trend over time (K/D ratio and KAST% line chart, last 15 matches)
  • ✅ Map performance (bar chart: win rate per map with color coding)
  • ⚠️ Role distribution: Deferred to future update (requires additional data analysis)
  • ⚠️ Weapon accuracy breakdown: Deferred to future update (requires weapons endpoint integration)
• Recent matches section:
  • ✅ Card-based grid showing last 10 matches
  • ✅ MatchCard component with clickable navigation
• Utility effectiveness stats:
  • ✅ Flash assists, enemies blinded
  • ✅ HE damage, molotov/flame damage
  • ✅ Stats displayed with per-match averages
• Achievements/badges (optional):
  • ⚠️ Deferred to future update (Ace count, clutch wins, MVP stars)
• Share profile button:
  • ⚠️ Deferred to future update (generate shareable link/image)

5.4 Match Overview (/match/[id] - src/routes/match/[id]/+page.svelte) ✅ SUBSTANTIALLY COMPLETE

• Match header (implemented in +layout.svelte):
  • ✅ Map name with background image (full-width header)
  • ✅ Multi-layer gradient overlays for depth
  • ✅ Final score (large, prominent with team colors)
  • ✅ Match date, duration, game mode, tick rate
  • ✅ Download demo button (functional with Steam protocol link)
  • ✅ Back to matches navigation
  • ✅ Demo parsed status badge
• Tab navigation:
  • ✅ Overview, Economy, Details, Weapons, Flashes, Damage, Chat
  • ✅ Sticky tabs with backdrop blur
  • ✅ Active tab indicator
• Team statistics overview cards:
  • ✅ Both teams with T/CT color coding
  • ✅ Team K/D, ADR, KAST, total kills, average Premier rating
• Scoreboard component:
  • ✅ Two teams with color coding
  • ✅ Player rows: name, K/D/A, ADR, HS%, KAST%, rating, MVPs
  • ✅ Sortable by kills (default)
  • ✅ Top performer indicators (Trophy icons)
  • ✅ Clickable player names → player profiles
  • ✅ Player color indicators (from game)
• Round history timeline:
  • ✅ RoundTimeline component with MR12 support (24 rounds + OT)
  • ⚠️ Round win reason indicators - Deferred (data not in current API response)
  • ⚠️ Click round for detailed events - Deferred
• Win probability chart:
  • ❌ Deferred to future update (advanced feature, requires economy simulation)
• Map callouts reference:
  • ❌ Deferred to future update (requires callout data/images)

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

• Round-by-round economy table:
  • ✅ Columns: Round #, Team 1 money, Team 2 money, Equipment value
  • ✅ Color coding for eco/force-buy/full-buy rounds (badges)
  • ✅ Buy type classification (Eco, Semi-Eco, Force, Full Buy)
• Equipment charts:
  • ✅ Line chart showing total equipment value over rounds
  • ✅ Summary stats cards (total rounds, buy rounds, eco rounds)
  • ⚠️ Pie charts for weapon purchases: Deferred
• Economy analysis:
  • ✅ Buy type legend with thresholds
  • ✅ Team-by-team buy round tracking
  • ⚠️ Save round detection: Deferred to future update

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

• Detailed player statistics table:
  • ✅ All players sortable table
  • ✅ Columns: K/D/A, ADR, HS%, KAST, MVPs, Aces
  • ✅ Multi-kills tracking (2k, 3k, 4k, 5k)
  • ✅ Utility damage stats (HE, flames, flash assists)
• Multi-kill distribution chart:
  • ✅ Bar chart showing 2K, 3K, 4K, 5K per player
  • ✅ Color-coded by multi-kill type
• Team performance summary:
  • ✅ Total damage, utility damage, flash assists per team
  • ✅ Average KAST per team
• Top performers cards:
  • ✅ Most kills, Best K/D, Most utility damage
• Weapon performance breakdown:
  • ⚠️ Deferred to future update (weapons data loaded but not visualized)
• Advanced metrics:
  • ⚠️ Deferred to future update

5.7 Flashes Tab (/match/[id]/flashes - src/routes/match/[id]/flashes/+page.svelte) ⚠️ BASIC IMPLEMENTATION COMPLETE

• Flash effectiveness leaderboard:
  • ✅ Players ranked by total enemies blinded
  • ✅ Average blind duration per flash
  • ✅ Flash assists (blinded enemy killed by teammate)
  • ✅ Self-flash count displayed
  • ✅ Team-specific flash stats tables (T vs CT)
  • ✅ Summary stats cards (Total Blinded, Flash Assists, Blind Time)
• Flash timeline visualization:
  • ❌ Round-by-round flash events - Deferred to future update
  • ❌ Pop flash detection (short reaction time) - Deferred
  • ❌ Team flashes vs solo flashes - Deferred
• Heatmap overlay (advanced):
  • ❌ Map with flash throw positions - Deferred to future update
  • ❌ Color intensity = effectiveness - Deferred
  • ❌ Clickable markers showing flash details - Deferred
• CS2-specific features:
  • ❌ Volumetric smoke interactions (flashes through smoke) - Deferred
  • ❌ New flash mechanics tracking - Deferred

5.8 Damage Tab (/match/[id]/damage - src/routes/match/[id]/damage/+page.svelte) ⚠️ BASIC IMPLEMENTATION COMPLETE

• Damage dealt/received summary:
  • ✅ Per-player total damage in sortable table
  • ✅ Team damage stat cards (T vs CT)
  • ✅ Top 3 damage dealers cards
  • ❌ Damage per round (line chart) - Deferred to future update
  • ❌ Weapon damage breakdown - Deferred
• Utility damage:
  • ✅ Utility damage distribution pie chart (HE + Fire)
  • ❌ HE grenade damage tracking details - Deferred
  • ❌ Molotov/Incendiary damage over time - Deferred
  • ❌ CS2: Volumetric smoke damage interactions - Deferred
• Hit group analysis:
  • ❌ Pie chart: headshots, chest, legs, arms - Deferred to future update
  • ❌ Headshot percentage ranking - Deferred
• Damage heatmap (Canvas/WebGL):
  • ❌ Map overlay showing where damage occurred - Deferred to future update
  • ❌ Click to filter by player, weapon, round - Deferred
  • ❌ Color intensity = damage amount - Deferred
  • ❌ Toggle between dealt/received damage - Deferred
• Engagement distance chart:
  • ❌ Histogram showing damage at various ranges - Deferred to future update
  • ❌ Optimal range analysis per weapon - Deferred

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

• Chronological chat feed:
  • ✅ Message bubbles with player initials (circular avatars)
  • ✅ Grouped by round with round headers
  • ✅ Team chat indicator (badges: Team / All Chat)
  • ✅ Team color coding (T=orange, CT=blue)
• Round navigation:
  • ✅ Messages grouped by round
  • ✅ Round separator cards with message counts
  • ✅ Warmup/Pre-Match messages support
• Search/filter:
  • ✅ Filter by player (dropdown selector)
  • ✅ Search message content (live search)
  • ✅ Filter by chat type (checkboxes: team/all)
• Statistics:
  • ✅ Total messages count
  • ✅ Team chat vs all chat breakdown
• Advanced features:
  • ⚠️ Translation toggle: Deferred to future update
  • ⚠️ Toxic language detection: Deferred to future update

5.10 CS2-Exclusive Features ✅ SUBSTANTIALLY COMPLETE

• MR12 format awareness:
  • ✅ RoundTimeline component dynamically calculates halftime (round 12 for MR12, round 15 for MR15)
  • ✅ Economy tab dynamically calculates halftime based on match.max_rounds
  • ✅ All round displays use max_rounds from match data (24 for MR12, 30 for MR15)
  • ✅ ADR calculations use dynamic max_rounds
  • ⚠️ Overtime display logic not yet implemented (deferred - requires overtime data from backend)
• Premier mode specifics:
  • ✅ CS2 rating system fully implemented (0-30,000 range)
  • ✅ PremierRatingBadge component with tier colors (Beginner/Intermediate/Advanced/Expert/Elite/Legendary)
  • ✅ Rating change tracking (show +/- rating difference)
  • ✅ Automatic detection of Skill Group (0-18) vs CS Rating (>1000) based on match date and game mode
  • ✅ RankIcon component for displaying CS:GO legacy skill groups
  • ✅ Formatters handle full 0-30,000 rating range with color-coded tiers
• ⚠️ DEFERRED: New utility tracking (requires backend support):
  • Volumetric smokes (coverage area, bloom effect) - Backend needs smoke effectiveness data
  • Updated grenade mechanics tracking - Requires additional API fields
  • Molotov spread and duration analysis - Requires positional data
• ⚠️ OUT OF SCOPE: Updated economy values:
  • CS2 weapon prices and economy changes - Backend handles this automatically
  • Loss bonus adjustments - Backend parses demo with correct CS2 values
• ⚠️ DEFERRED: New weapon statistics:
  • Track kills with CS2-exclusive weapons - Weapons endpoint exists, visualization deferred
  • Update weapon icons and names - Would require asset updates

5.10 Shared Components Library (src/lib/components/) - IN PROGRESS

Chart Components (src/lib/components/charts/) ✅ COMPLETE

• LineChart.svelte - Line charts with Chart.js
  • ✅ Responsive, customizable options
  • ✅ Svelte 5 runes ($effect for reactivity)
  • ✅ Multi-dataset support with fill
• BarChart.svelte - Bar/horizontal bar charts
  • ✅ Vertical and horizontal modes
  • ✅ Stacked bar support
• PieChart.svelte - Pie/Doughnut charts
  • ✅ Doughnut mode (default) or full pie
  • ✅ Legend positioning

Data Display Components (src/lib/components/data-display/) ✅ COMPLETE

• DataTable.svelte - Sortable, filterable tables
  • ✅ Generic TypeScript support
  • ✅ Sortable columns with visual indicators
  • ✅ Custom formatters and renderers
  • ✅ Alignment options (left, center, right)
  • ✅ Striped and hoverable rows

5.11 Remaining Components (Deferred)

• 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 5.12 – Critical TypeScript Errors (BLOCKING) ✅ COMPLETE

Status: ✅ All fixed - ready for production Priority: P0 (Highest) Completion Date: 2025-11-13

TrackPlayerModal API Signature Mismatches ✅

File: src/lib/components/player/TrackPlayerModal.svelte

• Fixed trackPlayer() call - Removed shareCode parameter to match API signature
• Fixed untrackPlayer() call - Removed authCode parameter (API doesn't require it)
• Fixed Modal binding - Changed bind:isOpen to bind:open
• Solution Applied: Removed shareCode input from UI, API accepts (steamId, authCode) only
• Added event callback props (ontracked, onuntracked) to support Svelte 5 pattern

Result: Player tracking feature now works correctly in strict TypeScript mode

Player Profile Type Inconsistencies ✅

File: src/routes/player/[id]/+page.svelte

• Fixed addRecentPlayer() type mismatch - Changed PlayerMeta.id from number to string
• Fixed profile.vac_count reference - Added to PlayerMeta interface
• Fixed profile.vac_date reference - Added to PlayerMeta interface
• Fixed profile.game_ban_count reference - Added to PlayerMeta interface
• Fixed profile.game_ban_date reference - Added to PlayerMeta interface
• Solution Applied: Extended PlayerMeta interface with ban fields and dates
• Updated preferences.ts store - Changed favoritePlayers from number[] to string[]
• Updated mock fixtures - Changed mockPlayerMeta.id to string type

Result: VAC/ban badges display correctly, recent players feature works, type consistency maintained

DataTable Generic Type Constraints ✅

Files:

• src/routes/match/[id]/details/+page.svelte

• src/routes/match/[id]/weapons/+page.svelte

• Fixed DataTable column definitions - Added explicit type annotations to render/format functions

• Created type aliases (PlayerWithStats, PlayerWeapon) for cleaner column definitions

• Used unknown type for parameters to satisfy generic constraints

• Solution Applied: Explicit typing on arrow function parameters

Result: Type safety fully restored, no implicit any types

Chart.js Fill Property Type Errors ✅

File: src/routes/match/[id]/economy/+page.svelte:156, 166

• Fixed fill: 'origin' type error - Used @ts-expect-error with explanatory comment
• Solution Applied: Suppressed incorrect Chart.js type definition (fill accepts 'origin' value)
• Documented that Chart.js types are outdated but code is correct

Result: Build succeeds, chart fill behavior works as expected

Missing Environment Module ✅

File: src/routes/api/[...path]/+server.ts

• Fixed import error - Changed from $env/dynamic/private to import.meta.env
• Solution Applied: Use Vite's import.meta.env.VITE_API_BASE_URL for environment variables
• Updated comment to reflect correct approach for VITE_ prefixed vars

Result: API proxy route now works correctly in all environments

Button Component Enhancements ✅

File: src/lib/components/ui/Button.svelte

• Added target and rel props for external links
• Updated template to pass through anchor attributes
• Fixed player profile button variant (changed 'success' to 'secondary')

Result: External links (Steam profile) now work correctly with security attributes

Other TypeScript Issues ✅

• Fixed unused variable warnings - Used _value prefix for intentionally unused parameters
• Resolved all implicit any types - Added explicit type annotations
• Ran npm run check - Zero errors, zero warnings

Success Criteria Met: ✅ npm run check exits with zero errors and zero warnings

---

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

Current Status: ⚠️ Minimal coverage (~5% of planned tests) Target: 80%+ coverage for unit/integration tests

Unit Tests (0% Complete)

• Write component tests (Vitest + Testing Library):
  • UI components: Button, Badge, Card, Modal, Tabs, Tooltip, Skeleton, Toast
  • Chart components: LineChart, BarChart, PieChart
  • Data display: DataTable, RoundTimeline
  • Match components: MatchCard, ShareCodeInput
  • Player components: PlayerCard, TrackPlayerModal, RecentPlayers
  • Layout components: Header, Footer, SearchBar, ThemeToggle
• Write store tests:
  • preferences.ts (theme, favorites, settings persistence)
  • search.ts (query, filters, recent searches)
  • toast.ts (notification queue, auto-dismiss)
• Write utility function tests:
  • formatters.ts (date, number, rank formatting)
  • validators.ts (Steam ID, share code validation)
  • constants.ts (buy type thresholds, map names)

Current Coverage: 0 test files in /tests/unit/

Integration Tests (0% Complete)

• Develop integration scenarios:
  • Match search flow (filters → results → detail)
  • Player profile navigation (search → profile → match)
  • Match detail tab switching (overview → economy → details → chat)
  • Infinite scroll behavior
  • Export functionality (CSV/JSON)
  • Share code submission
  • Recent players tracking
  • Theme persistence

Current Coverage: 0 test files in /tests/integration/

E2E Tests (~1% Complete)

• Basic homepage test (tests/e2e/home.test.ts)
• Develop comprehensive E2E scenarios (Playwright):
  • Match search and filtering
  • Player profile viewing
  • Match detail tab navigation
  • Share code parsing flow
  • Export match data
  • Recent players functionality
  • Mobile responsive behavior
• Set up visual regression snapshots for critical pages via Playwright or Loki.
• Cross-browser testing (Chrome, Firefox, Safari)

Current Coverage: 1 test file with 2 basic tests

Performance & Load Testing

• Build load-testing scripts for APIs powering live dashboards (k6 or artillery).
• Set up Lighthouse CI for automated performance checks
• Bundle size monitoring and regression detection

QA Process

• Coordinate QA playbook: test matrices, release checklists, and bug triage workflow.
• Establish code review checklist
• Create testing documentation

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

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

# Install dependencies
npm install
# or
yarn install

Development

# 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

# 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

# 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):

# 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-13 Current Phase: Phase 5 (Feature Delivery) - IN PROGRESS (75% Complete) Completed Phases: Phase 0 (Planning), Phase 1 (Technical Foundations), Phase 2 (Design System), Phase 3 (Domain Modeling), Phase 4 (Application Architecture), Phase 5.12 (Critical TypeScript Fixes) Next Milestone: Phase 6 (Localization) or Phase 8 (Testing & QA) Blocking Issues: None - All critical issues resolved ✅

Recent Progress (2025-11-13 Session 2):

• ✅ Section 5.2 (Matches Listing) completion audit:

  • Investigated backend API for player search capability
  • Confirmed 3 features blocked by backend API support:
    1. Player name search/autocomplete (no /players/search endpoint)
    2. Rank tier filter (no rank filtering in matches endpoint)
    3. Game mode filter (no game_mode field in API)
  • Added "Coming Soon" badge to search input with tooltip explanation
  • Updated placeholder text to clarify current search capability (match ID/share code only)
  • Documented all backend blockers in Section 5.2 with required API changes
  • Marked Section 5.2 as COMPLETE with documented blockers
  • Cleaned up outdated TypeScript error warnings from Sections 5.3, 5.5, 5.6

• ✅ Section 5.10 (CS2-Exclusive Features) implementation:

  • Fixed MR12/MR15 halftime calculation to be dynamic based on max_rounds:
    • Updated RoundTimeline component to accept maxRounds prop
    • Updated Economy tab to calculate halfPoint from match.max_rounds
    • MR12 (24 rounds): halftime after round 12
    • MR15 (30 rounds): halftime after round 15
  • Verified Premier rating system fully supports 0-30,000 range:
    • PremierRatingBadge component with 6 tier colors
    • Rating change tracking with +/- display
    • Automatic detection of Skill Group vs CS Rating
  • Documented deferred features (volumetric smokes, weapon stats) requiring backend support
  • Marked Section 5.10 as SUBSTANTIALLY COMPLETE

Recent Progress (2025-11-13 Session 1):

• ✅ FIXED: All 12 critical TypeScript errors resolved - Project now compiles with zero errors ✅
  • Fixed TrackPlayerModal API signature mismatches
  • Fixed Player Profile type inconsistencies (PlayerMeta extended with ban fields)
  • Fixed DataTable generic type constraints with explicit typing
  • Fixed Chart.js fill property errors with @ts-expect-error
  • Fixed environment module imports (switched to import.meta.env)
  • Added target/rel props to Button component
• ✅ Homepage enhancements completed:
  • Added "Most Played Maps" section with pie chart (top 7 maps from last 50 matches)
  • Added "Community Statistics" dashboard with recent activity cards
  • Added processing matches indicator with pulsing animation
  • Enhanced page loader to calculate map statistics dynamically
• ✅ Match Overview enhancements:
  • Download demo button now functional (uses Steam protocol links)
  • Map background header already implemented with beautiful gradients
• ⚠️ Test coverage still severely lacking (<5% actual vs 80% target)

Earlier Progress (Since 2025-11-04):

• ✅ Comprehensive project analysis completed
• ✅ Matches listing substantially complete (95%) - all core features done
• ✅ Flashes tab basic implementation complete with leaderboard and team stats
• ✅ Damage tab basic implementation complete with summary tables and pie chart

Previously Completed:

• ✅ Implemented chart components (Line, Bar, Pie) with Chart.js
• ✅ Created sortable DataTable component
• ✅ Match Economy tab with buy type analysis and equipment value charts
• ✅ Match Details tab with multi-kill distribution and top performers
• ✅ Match Chat tab with filtering, search, and round grouping
• ✅ Player profile with performance charts and utility stats
• ✅ Homepage with featured matches carousel and stats dashboard

Known Issues:

1. TypeScript Errors: ✅ ALL FIXED - Zero errors, zero warnings (as of 2025-11-13)

2. Technical Debt:

   • Zero unit test coverage (0 test files in /tests/unit/)
   • Zero integration test coverage (0 test files in /tests/integration/)
   • Minimal E2E coverage (1 file with 2 basic tests)
   • TODO comments in transformers (round winner/weapon kills not extracted)
   • Magic numbers for buy type thresholds (should be constants)

3. Deferred Advanced Features:

   • Damage/flash heatmaps (Canvas/WebGL visualization)
   • Hit group analysis charts
   • Engagement distance histograms
   • Flash/damage timeline visualizations
   • Live match indicators (backend support needed)
   • Volumetric smoke tracking (CS2-specific)

Priority Actions:

1. Immediate (1-2 days): Fix all TypeScript errors (Phase 5.12)
2. Short-term (1 week): Implement test suite (unit + integration + E2E)
3. Medium-term (2 weeks): Complete advanced visualizations (heatmaps, timelines)
4. Long-term (1 month): Phase 6 (Localization), Phase 7 (Performance)