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)

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

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

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

# 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-04 Current Phase: Phase 5 (Feature Delivery) - IN PROGRESS (50% Complete) Completed Phases: Phase 0 (Planning), Phase 1 (Technical Foundations), Phase 2 (Design System), Phase 3 (Domain Modeling), Phase 4 (Application Architecture) Next Milestone: Complete remaining match detail tabs (Flashes, Damage), enhance player profile with charts Recent Progress:

• ✅ 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
• ⚠️ Flashes and Damage tabs deferred for future implementation