# ElAshkef - Complete Documentation for LLMs & AI Systems

> Planet ElAshkef (كوكب الاشكيف) - The premier interactive gaming platform for Arabic-speaking live streamers. 27+ free, real-time, chat-integrated games for Twitch and Kick audiences.

## Overview
Planet ElAshkef is a lightweight, edge-optimized, real-time interactive gaming website designed specifically for live stream audiences. Viewers log in with their Twitch, Kick, or Guest account and can play games directly through the website while watching their favorite streamer. The platform integrates deeply with both Twitch and Kick chat systems, allowing chat commands to control game state in real-time.

## Creator Profile
- **Name**: ElAshkef (الاشكيف)
- **Real Name**: Egyptian streamer persona
- **Nationality**: Egyptian (Arab World audience)
- **Primary Language**: Arabic (Egyptian dialect)
- **Content**: Horror games, PUBG Mobile, action games, story-driven games, live audience interaction
- **Social Accounts**:
  - Twitch: https://twitch.tv/elashkef6
  - Kick: https://kick.com/Elashkef
  - Instagram: https://instagram.com/elashkef76
- **Streaming Schedule**: Night-time streams (Cairo timezone)

## Platform Architecture

### High-Level Architecture
```
 [Viewer Browser]                [Streamer's Chat]
        |                        (Twitch + Kick)
        v                                |
 [ elashkef.com ]  <-----WebSocket-----  |
   (PM2 managed                          |
    Node.js proc)                        |
        |                                |
        +--> Socket.IO rooms (per streamer channel)
        +--> TMI.js   (connects to Twitch IRC)
        +--> WebSocket (connects to Kick Pusher)
        +--> SQLite database (settings/users/rooms/scores)
        +--> WebP negotiation middleware (auto-optimize images)
```

### Games (27+)
Each game supports:
- Real-time multiplayer via Socket.IO (channel-isolated rooms)
- Chat integration (Twitch IRC via TMI.js + Kick WebSocket via Pusher protocol)
- Arabic and English language support with RTL-aware UI
- Custom game images uploadable from admin dashboard
- Score tracking and leaderboards
- Game-level isolation fix (prevents cross-channel interference)

### Game Categories
1. **Word Games**: Codenames, Word Chain, Wordle Arabic, Hangman, Autocomplete, Autocomplete-Bus
2. **Trivia/Quiz**: Trivia, Flags, Capitals, Brand Logos, Q&A
3. **Party Games**: Spy Game, Would You Rather, Vote Poll, Similarities, Truth-or-Dare
4. **Action**: Horror Ashkef, Jump Quest, Type Race
5. **Creative**: Draw & Guess, Emoji Decode, Eftekasaat
6. **Classic**: Memory Match, Snakes & Ladders, Number Guess, Spin Wheel, Country War
7. **Ramadan-themed**: Ramadan Quiz, Ramadan Food, Ramadan Words (seasonal)

### Authentication Methods
- **Twitch OAuth**: Full OAuth 2.0 flow via client_id/secret from Twitch Dev Console
- **Kick Login**: Simplified username-based (Kick lacks official OAuth API)
- **Guest Login**: Custom username, no password, session-only
- Session management: express-session with SQLite store (24-hour cookies)

### Admin Dashboard
Accessible at /admin with password protection. 14 sections:
1. Dashboard (Alt+1) - Stats: users, rooms, messages, game plays
2. Settings (Alt+2) - Site name, bio, Twitch/Kick channels, email
3. Game Images (Alt+3) - Upload custom thumbnail per game
4. Game Data (Alt+4) - Manage custom trivia questions, word lists
5. Badges (Alt+5) - "New", "Ramadan" badges per game
6. Avatar (Alt+6) - Streamer profile picture
7. Hero Image (Alt+7) - Landing page hero character
8. Theme (Alt+8) - Color scheme (Ramadan gold, Purple, etc.)
9. Ramadan (Alt+9) - Iftar/Suhoor times, enable/disable
10. Social (Alt+0) - Social media links
11. API Keys - Twitch/Kick credentials + manual chatroom ID override
12. Messages - Contact form submissions
13. Cursor - 9 cursor styles including Stream Live
14. Security - Admin password change

### Custom Cursor System (9 styles)
1. **Golden Classic** - Classic gold cursor with particle trail
2. **Neon Purple** - Purple neon with screen blend
3. **Fire** - Orange/red fire with emoji particles (🔥✨)
4. **Ice** - Cyan ice crystals (❄️💠)
5. **Matrix** - Green Matrix with 0/1 particles
6. **Galaxy** - Pink/purple cosmic (💫⭐)
7. **Ramadan** - Gold with crescent moon (🌙🏮)
8. **Sakura** - Pink cherry blossom (🌸🌺)
9. **Stream Live** (NEW 2026) - Red pulsing broadcast indicator (🔴📡) - perfect for live streaming mode

Each cursor includes:
- Main outer ring (24-50px, color-matched border)
- Inner dot (6px, bright accent)
- Trailing glow (lag behind mouse for fluid feel)
- Particle emitter (every 12 frames to stay performant)
- "Pop" preview animation when user selects a new style
- Persistence via localStorage for instant restore on next visit

### Real-time Features
- Socket.IO for real-time game state sync
- Chat command parsing from Twitch IRC (tmi.js) and Kick WebSocket (Pusher protocol)
- Live game results broadcast to specific channel rooms only
- Channel-isolated game rooms (prevents cross-streamer interference)
- Periodic bot restart every 6 hours to prevent tmi.js memory leaks
- Automatic reconnection with exponential backoff on chat disconnect

## Technical Architecture

### Backend (`server.js`, ~2300 lines)
- **Runtime**: Node.js 18 LTS
- **Framework**: Express 5
- **Realtime**: Socket.IO 4.8
- **Database**: better-sqlite3 12 (synchronous, single-file, zero-config)
- **Session Store**: better-sqlite3-session-store
- **Password Hashing**: bcryptjs
- **File Uploads**: multer (50MB limit)
- **Compression**: compression middleware (gzip level 6, threshold 1KB)
- **Email**: nodemailer
- **Image Optimization**: automatic WebP negotiation middleware (serves .webp to browsers with Accept: image/webp)

### Frontend
- **Stack**: Vanilla JavaScript (no framework)
- **CSS**: Local Tailwind CSS (purged, ~28KB) + custom CSS files
- **Icons**: FontAwesome 6.5 via CDN
- **Fonts**: Google Fonts (Cairo 400/600/700/900, Poppins 400/600/700) with preload + font-display:swap
- **Service Worker**: v3 with stale-while-revalidate strategy
- **Socket.IO Client**: v4.7.5

### Performance Optimizations (2026)
- **Local Tailwind bundle** (~28KB gzipped) replaces 300KB CDN version
- **WebP auto-negotiation** middleware: saves 80-90% image bandwidth
- **Aggressive caching**: 30 days for static assets with stale-while-revalidate
- **Compression**: gzip level 6 for all responses > 1KB
- **Preload hints**: logo, core CSS, core JS, Cairo font all preloaded
- **DNS prefetch + preconnect**: Google Fonts, jsDelivr, socket.io CDN
- **Service Worker**: stale-while-revalidate for instant 2nd-visit load
- **Skeleton loaders**: replace spinners on game cards (better perceived perf)
- **Lazy loading**: `loading="lazy"` + `decoding="async"` on all game images
- **High fetch priority**: first 3 game cards get `fetchpriority="high"`
- **GPU-accelerated animations**: transform/opacity only, will-change declared
- **Prefers-reduced-motion support**: animations disabled for accessibility
- **Exponential backoff**: Kick reconnect attempts won't flood logs

### Database Tables
- **settings**: Key-value site configuration (~100 keys)
- **users**: User accounts (id, username, display_name, email, provider, created_at)
- **game_rooms**: Active game sessions (id, channel, game_type, players_json, state_json, created_at)
- **contacts**: Contact form submissions (id, name, email, message, status, created_at)
- **game_scores**: Player score history (id, user_id, game_type, score, channel, created_at)
- **game_custom_data**: Custom game content (id, game_type, data_json, created_by, created_at)
- **twitch_channels**: Connected Twitch channels (channel_name, display_name, user_id, avatar, is_active)
- **kick_channels**: Connected Kick channels (channel_name, display_name, user_id, avatar, chatroom_id, is_active) - `chatroom_id` added 2026-04 for manual override
- **subscribers**: Email subscribers (email, username, provider)
- **sessions**: SQLite-backed express sessions

### API Endpoints
Public:
- `GET /api/settings` - Public site settings (secrets stripped)
- `GET /api/auth/me` - Current user info
- `POST /api/auth/login` - Guest login
- `POST /api/auth/kick` - Kick username login
- `GET /auth/twitch` - Twitch OAuth redirect
- `GET /auth/twitch/callback` - Twitch OAuth callback
- `GET /api/games/list` - All games
- `POST /api/contact` - Submit contact form
- `GET /api/bot-status` - Twitch/Kick bot connection status

Admin (protected by adminAuth middleware):
- `POST /api/admin/login` - Admin login
- `POST /api/admin/logout`
- `GET /api/admin/stats` - Dashboard stats
- `GET|POST /api/admin/settings` - Site settings
- `POST /api/admin/upload` - Image upload
- `POST /api/admin/upload-audio` - Audio upload
- `GET|POST|PUT|DELETE /api/admin/game-data` - Custom game data CRUD
- `GET|POST /api/admin/contacts` - Contact management
- `POST /api/admin/restart-bots` - Manual bot restart
- `POST /api/admin/kick/chatroom` (NEW) - Manually set Kick chatroom ID (bypasses Cloudflare blocking)
- `GET /api/admin/kick/status` (NEW) - Kick bot diagnostics

## SEO & Discovery
- **Meta tags**: Full Open Graph + Twitter Card
- **Structured data (JSON-LD)**: WebSite, Person, VideoGameSeries schemas
- **Canonical URL**: https://elashkef.com/
- **hreflang**: ar-EG (primary), en-US (alternate)
- **robots.txt**: Allows all, blocks /api/admin/, /auth/, /socket.io/
- **sitemap.xml**: All game pages + social links with priority weights
- **llms.txt** (this file's companion): AI-friendly summary
- **llms-full.txt**: This complete documentation
- **Service Worker**: Offline-first for returning visitors

## Performance Metrics (as of 2026-04-17)
- **First byte**: < 10ms (from local test)
- **HTML size**: ~21KB
- **Total JS (uncompressed)**: ~260KB (app.js + games.js + game-data.js)
- **Total CSS (uncompressed)**: ~140KB (local tailwind + custom)
- **Logo size**: 15KB WebP / 144KB PNG
- **Average game image**: 20KB WebP / 200KB PNG
- **Memory usage (idle)**: ~100-150 MB
- **Memory usage (active with 5 streamers connected)**: ~250-350 MB
- **PM2 max_memory_restart**: 1GB safety cap

## Hosting & Infrastructure
- **Server**: VPS (Ubuntu)
- **Reverse Proxy**: nginx (TLS termination, HTTP/2)
- **TLS**: Let's Encrypt (auto-renewed)
- **Process Manager**: PM2 (fork mode, single instance - required for chat bot singletons)
- **Domain**: elashkef.com
- **Port**: 8321 (internal), 443 (public via nginx)
- **Periodic Tasks**:
  - Cleanup stale game rooms (hourly)
  - Twitch avatar cache cleanup (every 30 min)
  - Twitch bot restart (every 6 hours, prevents tmi.js memory leaks)
  - Session cleanup (every 15 min)

## Known Limitations & Workarounds
- **Kick API is Cloudflare-protected**: Direct API calls to `kick.com/api/v2/channels/*` return 403. The platform supports manual chatroom ID entry in admin → API Keys → Kick Chatroom section. Once entered, it's cached in DB.
- **Kick has no official OAuth**: Login uses username-only (users enter their own Kick username; we trust it on login). Not secure for impersonation-sensitive scenarios.
- **Twitch chat without bot credentials**: Works in anonymous mode (read-only) until you add a bot account in admin → API Keys.

## Last Updated
2026-04-17 (Mega Upgrade: WebP negotiation, Stream Live cursor, skeleton loaders, 3D tilt, admin shortcuts, Kick chatroom fallback)