diff --git a/TODO.md b/TODO.md index cef2f7d..dc15df2 100644 --- a/TODO.md +++ b/TODO.md @@ -1,20 +1,74 @@ # CS2.WTF Rewrite TODO ## Phase 0 – Kickoff & Research -- [ ] Create and push the `cs2-port` branch from the current default branch. -- [ ] Capture the legacy stack (Vue 3 SPA + Go backend) and existing route map (`/`, `/matches`, `/player/[id]`, `/match/[id]/{economy|details|flashes|damage|chat}`) for reference. +- [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 - [ ] Host workshops with stakeholders, shoutcasters, and data consumers to gather CS2-specific requirements (new stats, volumetric smokes, MR12 changes). - [ ] Audit the `csgowtfd` backend APIs and data models; decide whether to extend or replace services for CS2 telemetry. - [ ] Document CS2 demo parsing pipeline expectations, storage strategy, and data freshness SLAs. ## Phase 1 – Technical Foundations -- [ ] Standardize on Node.js ≥ 18 (add `.nvmrc` / `.tool-versions`) and npm or yarn (lock the choice in documentation). -- [ ] Scaffold a new SvelteKit project with TypeScript in strict mode and commit the baseline to `cs2-port`. -- [ ] Integrate Tailwind CSS with DaisyUI; configure theme tokens, base styles, and dark/light mode support. -- [ ] Add project tooling: ESLint (with Svelte + TypeScript rules), Prettier, `svelte-check`, Stylelint (for Tailwind), and git hooks via Husky + lint-staged. -- [ ] Configure Vitest for unit/component tests and Playwright for E2E smoke tests (headless + CI modes). -- [ ] Set up Vite aliases, environment variable handling, and TypeScript path mappings for domain-driven organization. -- [ ] Update Woodpecker (or preferred CI) pipelines to run install, lint, type-check, test, and build jobs on every push. +- [ ] 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: + ```json + { + "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 - [ ] Produce a Figma (or Penpot) design system: typography scale, spacing, color ramps, iconography inspired by modern Counter-Strike 2 visuals. @@ -25,30 +79,331 @@ - [ ] Run accessibility review on mockups (contrast, color blindness variants, keyboard flows). ## Phase 3 – Domain Modeling & Data Layer -- [ ] Define TypeScript interfaces and Zod schemas for CS2 entities: matches, rounds, players, utility events, economy states, chat logs, and metadata. -- [ ] Decide on data access strategy (REST, GraphQL, WebSocket) and outline API contracts with backend engineers. -- [ ] Build a typed API client module with error boundaries, retry/backoff, caching, and cancellation support. -- [ ] Prepare mocked fixtures and MSW handlers for offline development and automated tests. -- [ ] Explore real-time update requirements (live match polling or push) and capture API changes needed on the backend. +- [ ] Define core TypeScript interfaces in `src/lib/types/`: + - `Match.ts`: match metadata, teams, score, map, date, duration, game mode (Premier, Competitive, etc.) + - `Player.ts`: Steam ID, name, avatar, rank, stats summary, recent matches + - `Round.ts`: round number, winner, reason, duration, economy state, events + - `PlayerStats.ts`: kills, deaths, assists, ADR, HS%, KAST, rating, utility damage + - `Economy.ts`: money spent/saved, equipment value, loadouts, utility purchases + - `UtilityEvent.ts`: flashbangs (effectiveness, enemies blinded), smokes (volumetric coverage), HE grenades, molotovs + - `DamageEvent.ts`: attacker, victim, weapon, damage, hit group, distance, tick + - `ChatMessage.ts`: timestamp, round, player, message, team chat flag + - `Metadata.ts`: CS2 version, demo hash, server info, tickrate +- [ ] Create Zod schemas for runtime validation: + - Match all TypeScript interfaces with Zod schemas for API response validation + - Add custom validators for Steam IDs, match IDs, rank tiers + - Export type-safe parsers: `parseMatch()`, `parsePlayerStats()`, etc. +- [ ] Design API client architecture: + - Evaluate backend API (likely REST from csgowtfd) and create typed client + - Build `src/lib/api/client.ts` with fetch wrapper + - Implement error handling (network errors, API errors, validation errors) + - Add retry logic with exponential backoff for transient failures + - Implement request cancellation (AbortController) for navigation + - Add response caching strategy (in-memory cache, TTL-based invalidation) +- [ ] Set up MSW (Mock Service Worker) for testing: + - Install: `msw@^2.0.0` + - Create mock handlers in `src/mocks/handlers/` for all endpoints + - Generate realistic fixture data matching CS2 statistics + - Configure MSW for both development mode and test runs +- [ ] 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 ## Phase 4 – Application Architecture & Routing -- [ ] Plan a route hierarchy using SvelteKit layouts (`src/routes/+layout.svelte`, `routes/matches/+page.svelte`, nested `routes/match/[id]/+page.svelte`, etc.). -- [ ] Implement the global shell: header, footer, persistent search, language switcher, theme toggle, and notification area. -- [ ] Configure `load` functions, universal load guards, and error/skeleton states per route for resilient UX. -- [ ] Introduce cross-route state management (Svelte stores) for filters, user preferences, and shared data caches. -- [ ] Establish analytics and consent handling architecture compatible with SSR. +- [ ] Create SvelteKit route structure in `src/routes/`: + ``` + src/routes/ + ├── +layout.svelte # Root layout (header, footer, navigation) + ├── +layout.ts # Root load function (user prefs, i18n) + ├── +page.svelte # Homepage (/) + ├── +page.ts # Homepage data (featured matches) + ├── matches/ + │ ├── +page.svelte # Match listing (/matches) + │ └── +page.ts # Load matches with filters + ├── player/ + │ └── [id]/ + │ ├── +page.svelte # Player profile (/player/[id]) + │ └── +page.ts # Load player data + └── match/ + └── [id]/ + ├── +layout.svelte # Match layout (tabs navigation) + ├── +layout.ts # Load match data (shared by all tabs) + ├── +page.svelte # Match overview (/match/[id]) + ├── economy/ + │ └── +page.svelte + ├── details/ + │ └── +page.svelte + ├── flashes/ + │ └── +page.svelte + ├── damage/ + │ └── +page.svelte + └── chat/ + └── +page.svelte + ``` +- [ ] Implement root layout (`src/routes/+layout.svelte`): + - Global header with logo, navigation, search bar + - Language switcher component (dropdown with flag icons) + - Theme toggle (light/dark/auto) with smooth transitions + - Footer with links, version info, backend status indicator + - Toast/notification system (top-right positioned) + - Loading bar (NProgress-style) for route transitions +- [ ] Create reusable layout components in `src/lib/components/layout/`: + - `Header.svelte`: responsive navigation, mobile menu drawer + - `Footer.svelte`: links, social, donation info + - `SearchBar.svelte`: global search with keyboard shortcuts (Cmd+K) + - `ThemeToggle.svelte`: theme switcher with icon animations + - `LanguageSwitcher.svelte`: i18n selector with persistence + - `Breadcrumbs.svelte`: contextual navigation breadcrumbs +- [ ] Configure load functions with error handling: + - Implement `+page.ts` load functions for data fetching + - Add error boundaries: `+error.svelte` for each route level + - Create loading skeletons: `+loading.svelte` (SvelteKit streaming) + - Handle 404s, 500s, and API errors gracefully + - Implement redirect logic for invalid match/player IDs +- [ ] Set up state management with Svelte stores (`src/lib/stores/`): + - `preferences.ts`: user settings (theme, language, units, favorites) + - `search.ts`: search query, filters, recent searches + - `cache.ts`: client-side data cache with TTL + - `toast.ts`: notification queue and display logic + - `auth.ts`: user authentication state (if auth is implemented) + - Use `writable`, `derived`, and `readable` stores appropriately + - Persist critical stores to localStorage with sync +- [ ] Add analytics and privacy: + - Choose privacy-respecting analytics (Plausible, Umami, or self-hosted) + - Implement consent banner (GDPR-compliant) + - Create analytics utility: `trackPageView()`, `trackEvent()` + - Ensure SSR compatibility (client-side only execution) + - Add opt-out mechanism ## Phase 5 – Feature Delivery (Parity + Enhancements) -- [ ] Home/Dashboard: featured matches, live queue, top performers, and quick filters with real-time indicators. -- [ ] Matches Index: searchable, filterable list with virtualized tables, map/side filters, rank tiers, and date range pickers. -- [ ] Player Profile (`/player/[id]`): career summary, map win rates, weapon performance, clutch stats, and timeline cards. -- [ ] Match Overview (`/match/[id]`): scoreboard, round-by-round timeline, win probability graph, and MR12 adjustments. -- [ ] Economy View: spend/equipment charts, save rounds, utility purchases, and loss-bonus visualization. -- [ ] Utility/Flashes View: breakdown of utility effectiveness, pop flash timings, volumetric smoke coverage (heatmap/webgl overlays). -- [ ] Damage View: per-round damage charts, headshot percentages, spatial heatmaps using Canvas/WebGL. -- [ ] Chat View: chronological chat feed with role badges, highlight detection, and translation toggle. -- [ ] Introduce CS2-exclusive insights (sky smoke bloom, loadout value changes, new grenade types) and align labels accordingly. -- [ ] Add sharing/export features (downloadable stats, social cards) respecting privacy constraints. + +### 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. @@ -90,4 +445,356 @@ - [ ] 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 0 (Planning & Research) +**Next Milestone**: Complete Phase 1 scaffold and tooling setup