dubs-server 1.0.0

package/documentation/latest/LATEST_PRODUCTION_SETUP.md

@@ -0,0 +1,865 @@
+# 🚀 DUBS Server Production Setup
+
+**Created:** December 14, 2025  
+**Last Updated:** December 14, 2025
+
+This document contains critical operational information for the `dubs-server-prod` Heroku application.
+
+---
+
+## 📋 Quick Reference
+
+| Field | Value |
+|-------|-------|
+| **App Name** | `dubs-server-prod` |
+| **Production URL** | https://dubs-server-prod-9c91d3f01199.herokuapp.com/ |
+| **Git Remote** | `heroku-prod` |
+| **Team** | dubs |
+| **Region** | US |
+| **Stack** | heroku-24 |
+
+---
+
+## 🖥️ Infrastructure
+
+### Dynos (Compute)
+
+| Dyno | Type | Size | Purpose |
+|------|------|------|---------|
+| `web.1` | Standard-1X | 512MB RAM | Express.js API server |
+| `oracle.1` | Standard-1X | 512MB RAM | Automatic game resolution oracle |
+
+### Database (PostgreSQL)
+
+| Field | Value |
+|-------|-------|
+| **Addon Name** | `postgresql-regular-65857` |
+| **Plan** | Standard-0 |
+| **Cost** | ~$50/month |
+| **PG Version** | 17.5 |
+| **Storage Limit** | 64 GB |
+| **Max Connections** | 200 |
+| **Region** | US East (AWS) |
+| **Created** | December 14, 2025 |
+
+#### Database Features
+
+| Feature | Status |
+|---------|--------|
+| Fork/Follow | ✅ Available |
+| Point-in-Time Rollback | ✅ Available |
+| Continuous Protection | ✅ On |
+| Data Encryption | ✅ In Use |
+| Connection Pooling | ✅ Available |
+
+#### Database vs Dev Comparison
+
+| Property | PROD | DEV |
+|----------|------|-----|
+| **Addon** | `postgresql-regular-65857` | `postgresql-colorful-22525` |
+| **Plan** | Standard-0 ($50/mo) | Essential-0 ($5/mo) |
+| **Storage** | 64 GB | 1 GB |
+| **Connections** | 200 | 20 |
+| **Rollback** | ✅ Yes | ❌ No |
+| **Fork/Follow** | ✅ Yes | ❌ No |
+
+⚠️ **Important:** These are completely separate databases with different credentials. No data is shared between environments.
+
+#### Database Tables (34 total)
+
+**Authentication & Users:**
+- `users` - User profiles
+- `auth_nonces` - Signature verification nonces
+- `user_sessions` - JWT sessions
+- `user_badges` - Achievement badges
+- `telegram_notification_preferences` - Notification settings
+
+**Chat System:**
+- `chat_messages` - Chat messages
+- `chat_notifications` - In-app notifications
+- `chat_payments` - SOL payment tracking
+- `chat_reactions` - Emoji reactions
+- `direct_messages` - Private messages
+- `message_mentions` - @mentions
+
+**Games & Betting:**
+- `games` - Sports betting games
+- `user_game_refs` - User game participation
+- `pending_game_dismissals` - Dismissed game notifications
+- `sports_betting_stats` - Betting statistics
+- `audit_logs` - Action logging
+
+**Social Features:**
+- `friends` - Friend relationships
+- `friend_requests` - Pending requests
+- `user_relationships` - Blocks, etc.
+- `groups` - Group chats
+- `group_members` - Group membership
+
+**Live Games (ESPN Integration):**
+- `live_games` - Real-time game data
+- `live_game_plays` - Play-by-play
+- `live_game_stats` - Game statistics
+- `live_game_subscriptions` - User subscriptions
+- `live_game_polling_log` - Polling history
+
+**Jackpot System:**
+- `jackpot_rounds` - Round history
+- `keeper_actions` - Keeper logs
+- `keeper_health` - Health checks
+- `keeper_rounds` - Round state
+
+**Player Stats:**
+- `player_stats` - Aggregate stats
+- `player_history` - Transaction history
+
+**Caching:**
+- `crypto_prices_cache` - Crypto price cache
+- `exchange_rates_cache` - Currency rates cache
+
+### S3 Storage (Avatar Uploads)
+
+| Field | Value |
+|-------|-------|
+| **Bucket** | `dubs-avatars-prod` |
+| **Region** | `us-east-2` |
+| **Public URL** | `https://dubs-avatars-prod.s3.us-east-2.amazonaws.com/avatars/` |
+| **Access** | Public read for `/avatars/*` |
+| **CORS** | Enabled for browser uploads |
+
+**Note:** The bucket/region is determined by `NODE_ENV=production` in the code, not by env vars.
+
+---
+
+## 🗄️ Database Access
+
+### Connection Details
+
+| Field | Value |
+|-------|-------|
+| **Host** | `ec2-34-202-113-158.compute-1.amazonaws.com` |
+| **Port** | `5432` |
+| **Database** | `d6jpka002e1ept` |
+| **User** | `uddg5sp8vh4l8g` |
+| **Password** | Run: `heroku config:get DATABASE_URL --app dubs-server-prod` |
+| **SSL Mode** | `require` (mandatory) |
+
+### Connect via Heroku CLI (Recommended)
+
+```bash
+# Interactive psql session
+heroku pg:psql --app dubs-server-prod
+
+# Run a single query
+heroku pg:psql --app dubs-server-prod -c "SELECT COUNT(*) FROM users;"
+
+# Run a SQL file
+heroku pg:psql --app dubs-server-prod < scripts/some-migration.sql
+```
+
+### Get Connection String
+
+```bash
+# View DATABASE_URL (contains credentials)
+heroku config:get DATABASE_URL --app dubs-server-prod
+
+# Format: postgres://USER:PASSWORD@HOST:PORT/DATABASE
+```
+
+### Connect with External Tools (pgAdmin, DBeaver, TablePlus)
+
+Use the connection details above, or run:
+
+```bash
+heroku pg:credentials:url --app dubs-server-prod
+```
+
+⚠️ **Important:** Heroku Postgres requires SSL. Set `sslmode=require` in your connection settings.
+
+### Database Backup & Restore
+
+```bash
+# Create manual backup
+heroku pg:backups:capture --app dubs-server-prod
+
+# List backups
+heroku pg:backups --app dubs-server-prod
+
+# Download latest backup
+heroku pg:backups:download --app dubs-server-prod
+
+# Restore from backup
+heroku pg:backups:restore b001 DATABASE_URL --app dubs-server-prod
+```
+
+### Database Maintenance
+
+```bash
+# View database info
+heroku pg:info --app dubs-server-prod
+
+# View active connections
+heroku pg:psql --app dubs-server-prod -c "SELECT * FROM pg_stat_activity WHERE datname = current_database();"
+
+# Kill idle connections (if needed)
+heroku pg:killall --app dubs-server-prod
+```
+
+---
+
+## ⚙️ Configuration Variables (Complete Reference)
+
+This section documents **every** environment variable used by the production server, organized by function.
+
+---
+
+### 🔗 Solana / Blockchain
+
+These variables configure the connection to Solana and the smart contract.
+
+| Variable | Value | Used By | Description |
+|----------|-------|---------|-------------|
+| `PROGRAM_ID` | `85wJGp9uc8w2FeKX9CEHsudTo1UVCrmuRFy37oCcaoG1` | `server.js`, `oracleMonitor.js` | **Mainnet Sports Betting Program ID.** The deployed Solana program address for all sports betting operations (game creation, betting, resolution, payouts). |
+| `JACKPOT_PROGRAM_ID` | `85wJGp9uc8w2FeKX9CEHsudTo1UVCrmuRFy37oCcaoG1` | `jackpotService.js` | **Reserved for future jackpot program.** Currently set to same as PROGRAM_ID. ⚠️ Note: `jackpotService.js` has this **hardcoded** - the env var is not actively read. |
+| `SOLANA_NETWORK` | `https://api.mainnet-beta.solana.com` | `server.js`, `oracleMonitor.js` | **Solana RPC endpoint.** Used for all blockchain interactions (fetching accounts, sending transactions). Can be changed to a private RPC for better rate limits. |
+| `ORACLE_WALLET_JSON` | `[135,155,140,...]` (64-byte JSON array) | `oracleMonitor.js` | **Oracle keypair (private key).** The Solana wallet that signs game resolution transactions. This wallet must match the `oracle` authority in the deployed program and needs SOL for tx fees. |
+| `KEEPER_PRIVATE_KEY` | `[135,155,140,...]` (64-byte JSON array) | `jackpotService.js` | **Keeper keypair for jackpot rounds.** Used to trigger jackpot round transitions. Currently same wallet as oracle. |
+
+**🔐 Security:** `ORACLE_WALLET_JSON` and `KEEPER_PRIVATE_KEY` are **private keys**. Never expose in logs or client-side code.
+
+---
+
+### 🗄️ Database
+
+| Variable | Value | Used By | Description |
+|----------|-------|---------|-------------|
+| `DATABASE_URL` | `postgres://uddg5sp8vh4l8g:...@ec2-34-202-113-158.compute-1.amazonaws.com:5432/d6jpka002e1ept` | All services | **PostgreSQL connection string.** Auto-set by Heroku when Postgres addon is provisioned. Contains host, port, username, password, and database name. SSL is required. |
+
+**Used by:**
+- `server.js` - Main Express app database connections
+- `oracleMonitor.js` - Game state queries
+- All API routes - User data, games, chat, etc.
+
+---
+
+### ☁️ AWS / S3 Storage
+
+These variables configure avatar image uploads to S3.
+
+| Variable | Value | Used By | Description |
+|----------|-------|---------|-------------|
+| `AWS_ACCESS_KEY_ID` | `AKIAZPVQ6PRW5OIQYGUI` | `s3Service.js` | **AWS IAM access key.** Used to authenticate S3 API requests for avatar uploads. |
+| `AWS_SECRET_ACCESS_KEY` | `q0IwdvM+I/UXovupqc...` | `s3Service.js` | **AWS IAM secret key.** Paired with access key for S3 authentication. |
+
+**Note:** The S3 bucket name (`dubs-avatars-prod`) and region (`us-east-2`) are **NOT** configured via env vars. They are determined by `NODE_ENV=production` in `s3Service.js`:
+
+```javascript
+this.bucketName = process.env.NODE_ENV === 'production' 
+  ? 'dubs-avatars-prod' : 'dubs-avatars-dev';
+this.region = process.env.NODE_ENV === 'production' 
+  ? 'us-east-2' : 'us-east-1';
+```
+
+---
+
+### 🌐 API Endpoints
+
+These variables define URLs for inter-service communication.
+
+| Variable | Value | Used By | Description |
+|----------|-------|---------|-------------|
+| `API_BASE_URL` | `https://dubs-server-prod-9c91d3f01199.herokuapp.com` | Various | **This server's public URL.** Used when generating absolute URLs (e.g., in emails, redirects). |
+| `DUBS_SERVER_URL` | `https://dubs-server-prod-9c91d3f01199.herokuapp.com` | `oracleMonitor.js` | **Oracle's reference to this server.** The oracle uses this to query game data from the PostgreSQL-backed API when resolving games. |
+| `LIVE_SCORES_API_URL` | `https://dubs-api-prod-9e38ab6733f8.herokuapp.com` | `oracleMonitor.js` | **Live scores API endpoint.** Points to `dubs-api` service which provides final game scores. Oracle fetches scores from here to determine game winners. |
+| `TELEGRAM_BOT_URL` | `https://dubs-telegram-bot-eb6ad9ec87b7.herokuapp.com` | `server.js` (notifications) | **Telegram bot server URL.** Used to send push notifications to users via Telegram when games they bet on are starting. |
+
+---
+
+### 🔐 Authentication & Security
+
+| Variable | Value | Used By | Description |
+|----------|-------|---------|-------------|
+| `JWT_SECRET` | `d7ac140e29ae46324336c12b3cf58ec944c1a9...` | `authRoutes.js`, auth middleware | **JSON Web Token signing secret.** Used to sign and verify JWT tokens for user authentication. ✅ This is **different** between dev and prod (rotated). |
+| `BOT_SECRET` | `telegram-bot-secret-key` | `server.js` (bot endpoints) | **Shared secret for Telegram bot.** Used to verify requests from the Telegram bot are authentic. Used in bot-to-server communication. |
+| `TELEGRAM_BOT_TOKEN` | `7294073418:AAFJRJJzR8PB3dhGQIdMq1q0sdZ...` | `server.js` (notifications) | **Telegram Bot API token.** The token from @BotFather used to send messages via Telegram Bot API. |
+
+---
+
+### ⏱️ Timing / Polling Intervals
+
+These control how frequently background processes run.
+
+| Variable | Value (ms) | Used By | Description |
+|----------|------------|---------|-------------|
+| `ORACLE_CHECK_INTERVAL` | `60000` (60s) | `oracleMonitor.js` | **Game resolution check frequency.** How often the oracle checks for finished games that need to be resolved on-chain and payouts distributed. |
+
+**Performance Note:** These intervals affect API rate limits and database write frequency. Adjust carefully.
+
+---
+
+### 🌍 Environment
+
+| Variable | Value | Used By | Description |
+|----------|-------|---------|-------------|
+| `NODE_ENV` | `production` | Entire app | **Node.js environment mode.** Affects: S3 bucket/region selection, error verbosity, logging level, and various conditional behaviors throughout the codebase. |
+
+---
+
+### 📋 Complete Variable Summary
+
+| Variable | Category | Status |
+|----------|----------|--------|
+| `PROGRAM_ID` | Solana | ✅ Active |
+| `JACKPOT_PROGRAM_ID` | Solana | ⚠️ Set but hardcoded in code |
+| `SOLANA_NETWORK` | Solana | ✅ Active |
+| `ORACLE_WALLET_JSON` | Solana | ✅ Active (🔐 Sensitive) |
+| `KEEPER_PRIVATE_KEY` | Solana | ✅ Active (🔐 Sensitive) |
+| `DATABASE_URL` | Database | ✅ Active (🔐 Sensitive) |
+| `AWS_ACCESS_KEY_ID` | AWS | ✅ Active |
+| `AWS_SECRET_ACCESS_KEY` | AWS | ✅ Active (🔐 Sensitive) |
+| `API_BASE_URL` | API URLs | ✅ Active |
+| `DUBS_SERVER_URL` | API URLs | ✅ Active |
+| `LIVE_SCORES_API_URL` | API URLs | ✅ Active |
+| `TELEGRAM_BOT_URL` | API URLs | ✅ Active |
+| `JWT_SECRET` | Security | ✅ Active (🔐 Sensitive) |
+| `BOT_SECRET` | Security | ✅ Active |
+| `TELEGRAM_BOT_TOKEN` | Security | ✅ Active (🔐 Sensitive) |
+| `ORACLE_CHECK_INTERVAL` | Timing | ✅ Active |
+| `LIVE_GAME_DISCOVERY_INTERVAL` | Timing | ✅ Active |
+| `LIVE_GAME_POLL_INTERVAL` | Timing | ✅ Active |
+| `LIVE_GAME_STATS_INTERVAL` | Timing | ✅ Active |
+| `NODE_ENV` | Environment | ✅ Active |
+
+**Total: 20 active variables** (7 are sensitive/secrets)
+
+---
+
+### View All Config
+
+```bash
+heroku config --app dubs-server-prod
+```
+
+### Update Config
+
+```bash
+# Set single variable
+heroku config:set VARIABLE_NAME=value --app dubs-server-prod
+
+# Set multiple variables
+heroku config:set VAR1=value1 VAR2=value2 --app dubs-server-prod
+
+# Remove a variable
+heroku config:unset VARIABLE_NAME --app dubs-server-prod
+```
+
+---
+
+## 🔌 API Endpoints Reference
+
+This section documents all API endpoints, their security status, and usage by the `dubs-jackpot-spa` frontend.
+
+### Legend
+
+| Symbol | Meaning |
+|--------|---------|
+| 🔐 | **Secured** - Requires JWT token in `Authorization: Bearer <token>` header |
+| 🌐 | **Public** - No authentication required |
+| ✅ | Used by SPA (`dubs-jackpot-spa/app/v2/`) |
+| ❌ | Not used by SPA (internal/bot/other) |
+
+---
+
+### 🔑 Authentication (`/auth`)
+
+| Method | Endpoint | Security | SPA | Description |
+|--------|----------|----------|-----|-------------|
+| GET | `/auth/nonce/:walletAddress` | 🌐 Public | ✅ | Get nonce for wallet signature |
+| GET | `/auth/check-username/:username` | 🌐 Public | ✅ | Check if username is available |
+| POST | `/auth/verify-signature` | 🌐 Public | ✅ | Verify wallet signature |
+| POST | `/auth/register` | 🌐 Public | ✅ | Register new user (returns JWT) |
+| POST | `/auth/login` | 🌐 Public | ✅ | Login existing user (returns JWT) |
+| GET | `/auth/user/:walletAddress` | 🌐 Public | ✅ | Get public user profile (limited data) |
+| GET | `/auth/user/me` | 🔐 Secured | ✅ | Get full authenticated user profile |
+| PUT | `/auth/user/:walletAddress` | 🔐 Secured | ✅ | Update user profile |
+| POST | `/auth/user/:walletAddress/onboarding-complete` | 🔐 Secured | ✅ | Mark onboarding complete |
+| GET | `/auth/validate-session` | 🔐 Secured | ✅ | Validate current JWT session |
+| POST | `/auth/logout` | 🔐 Secured | ✅ | Logout current session |
+| POST | `/auth/logout-all` | 🔐 Secured | ✅ | Logout all sessions |
+| POST | `/auth/user/me/generate-referral-code` | 🔐 Secured | ✅ | Generate user's referral code |
+| GET | `/auth/user/me/referred-users` | 🔐 Secured | ✅ | Get list of referred users |
+| GET | `/auth/user/me/badges` | 🔐 Secured | ✅ | Get earned badges |
+| POST | `/auth/user/me/check-badges` | 🔐 Secured | ✅ | Check and award new badges |
+| POST | `/auth/user/me/link-telegram` | 🔐 Secured | ✅ | Link Telegram account |
+| POST | `/auth/user/me/unlink-telegram` | 🔐 Secured | ✅ | Unlink Telegram account |
+| GET | `/auth/user/me/telegram` | 🔐 Secured | ✅ | Get Telegram connection status |
+| GET | `/auth/user/me/telegram-notification-preferences` | 🔐 Secured | ✅ | Get notification preferences |
+| PUT | `/auth/user/me/telegram-notification-preferences` | 🔐 Secured | ✅ | Update notification preferences |
+
+---
+
+### 👥 Social (`/social`)
+
+| Method | Endpoint | Security | SPA | Description |
+|--------|----------|----------|-----|-------------|
+| GET | `/social/search` | 🔐 Secured | ✅ | Search users by username |
+| POST | `/social/friend-request/:targetUserId` | 🔐 Secured | ✅ | Send friend request |
+| GET | `/social/friend-requests` | 🔐 Secured | ✅ | Get pending friend requests |
+| POST | `/social/request/:requestId/accept` | 🔐 Secured | ✅ | Accept friend request |
+| POST | `/social/request/:requestId/reject` | 🔐 Secured | ✅ | Reject friend request |
+| GET | `/social/friends` | 🔐 Secured | ✅ | Get friends list |
+| DELETE | `/social/friend/:targetUserId` | 🔐 Secured | ✅ | Remove friend |
+
+---
+
+### 💬 Direct Messages (`/dm`)
+
+| Method | Endpoint | Security | SPA | Description |
+|--------|----------|----------|-----|-------------|
+| GET | `/dm/conversations` | 🔐 Secured | ✅ | Get all DM conversations |
+| GET | `/dm/conversation/:walletAddress` | 🔐 Secured | ✅ | Get conversation history |
+| POST | `/dm/send` | 🔐 Secured | ✅ | Send direct message |
+| POST | `/dm/read/:walletAddress` | 🔐 Secured | ✅ | Mark messages as read |
+| GET | `/dm/unread` | 🔐 Secured | ✅ | Get unread DM count |
+
+---
+
+### 💬 Chat (`/chat`)
+
+| Method | Endpoint | Security | SPA | Description |
+|--------|----------|----------|-----|-------------|
+| GET | `/chat/messages` | 🔐 Secured | ✅ | Get chat messages (via WebSocket primarily) |
+| POST | `/chat/messages` | 🔐 Secured | ✅ | Send chat message |
+| GET | `/chat/notifications` | 🔐 Secured | ✅ | Get chat notifications |
+| POST | `/chat/reactions` | 🔐 Secured | ✅ | Add reaction to message |
+
+---
+
+### 📊 Player Stats (`/stats`)
+
+| Method | Endpoint | Security | SPA | Description |
+|--------|----------|----------|-----|-------------|
+| GET | `/stats/player/:walletAddress` | 🌐 Public | ✅ | Get player statistics |
+| GET | `/stats/player/:walletAddress/history` | 🔐 Secured | ✅ | Get player game history (detailed betting history) |
+| GET | `/stats/leaderboard` | 🌐 Public | ✅ | Get leaderboard |
+
+---
+
+### 👤 User Profile (`/api/profile`)
+
+| Method | Endpoint | Security | SPA | Description |
+|--------|----------|----------|-----|-------------|
+| GET | `/api/profile/:walletAddress` | 🌐 Public | ✅ | Get comprehensive profile stats |
+| GET | `/api/profile/:walletAddress/summary` | 🌐 Public | ✅ | Get quick summary for tooltips |
+| GET | `/api/profile/:walletAddress/games` | 🔐 Secured | ✅ | Get user's games history (sensitive) |
+| GET | `/api/profile/:walletAddress/friends` | 🌐 Public | ✅ | Get user's friends list |
+| GET | `/api/profile/leaderboard/:type` | 🌐 Public | ✅ | Get leaderboard by type |
+| POST | `/api/profile/batch` | 🔐 Secured | ✅ | Get batch profile stats (prevents scraping) |
+
+---
+
+### ⚽ Sports (`/api/sports`, `/api/livescores`)
+
+| Method | Endpoint | Security | SPA | Description |
+|--------|----------|----------|-----|-------------|
+| GET | `/api/sports/events/:league` | 🌐 Public | ✅ | Get upcoming sports events |
+| GET | `/api/sports/teams/:league` | 🌐 Public | ✅ | Get teams for league |
+| GET | `/api/livescores` | 🌐 Public | ✅ | Get live scores (all leagues) |
+| GET | `/api/livescores/:league` | 🌐 Public | ❌ | Get live scores for specific league |
+
+---
+
+### 🎮 Games (`/api/games`, `/api/auth/games`)
+
+| Method | Endpoint | Security | SPA | Description |
+|--------|----------|----------|-----|-------------|
+| GET | `/api/games/stats` | 🌐 Public | ✅ | Get platform statistics |
+| GET | `/api/games/health` | 🌐 Public | ✅ | Server health check |
+| GET | `/api/games/pending/:walletAddress` | 🌐 Public | ✅ | Get pending games for user |
+| GET | `/api/games/active/:walletAddress` | 🌐 Public | ✅ | Get active games for user |
+| GET | `/api/games/claimable/:walletAddress` | 🌐 Public | ✅ | Get claimable games |
+| POST | `/api/auth/games/save` | 🔐 Secured | ✅ | Save game to database |
+| POST | `/api/audit/log` | 🌐 Public | ✅ | Log audit event |
+
+---
+
+### 💸 Transactions (`/api/v1/prod/transaction`)
+
+| Method | Endpoint | Security | SPA | Description |
+|--------|----------|----------|-----|-------------|
+| POST | `/api/v1/prod/transaction/build/create-and-join-automatic` | 🌐 Public | ✅ | Build sports bet transaction |
+| POST | `/api/v1/prod/transaction/build/join-game` | 🌐 Public | ✅ | Build join game transaction |
+| POST | `/api/v1/prod/transaction/build/claim` | 🌐 Public | ✅ | Build claim winnings transaction |
+
+---
+
+### 💱 Exchange Rates (`/api/exchange-rates`)
+
+| Method | Endpoint | Security | SPA | Description |
+|--------|----------|----------|-----|-------------|
+| GET | `/api/exchange-rates` | 🌐 Public | ✅ | Get all exchange rates |
+| GET | `/api/exchange-rates/pair/:from/:to` | 🌐 Public | ✅ | Get specific currency pair |
+| GET | `/api/exchange-rates/convert` | 🌐 Public | ✅ | Convert amount between currencies |
+| GET | `/api/exchange-rates/currencies` | 🌐 Public | ✅ | Get supported currencies |
+
+---
+
+### 💰 Crypto Prices (`/api/crypto-prices`)
+
+| Method | Endpoint | Security | SPA | Description |
+|--------|----------|----------|-----|-------------|
+| GET | `/api/crypto-prices/solana` | 🌐 Public | ✅ | Get SOL price in multiple currencies |
+| GET | `/api/crypto-prices/solana/usd` | 🌐 Public | ✅ | Get SOL price in USD |
+
+---
+
+### 📈 Analytics (`/api/analytics`)
+
+| Method | Endpoint | Security | SPA | Description |
+|--------|----------|----------|-----|-------------|
+| POST | `/api/analytics/events` | 🌐 Public | ✅ | Track analytics event |
+| GET | `/api/analytics/events` | 🌐 Public | ❌ | Get analytics events (admin) |
+| GET | `/api/analytics/funnel/:funnelId` | 🌐 Public | ❌ | Get funnel data (admin) |
+| GET | `/api/analytics/summary` | 🌐 Public | ❌ | Get analytics summary (admin) |
+
+---
+
+### 📤 Upload (`/upload`)
+
+| Method | Endpoint | Security | SPA | Description |
+|--------|----------|----------|-----|-------------|
+| POST | `/upload/avatar/presigned-url` | 🔐 Secured | ✅ | Get presigned URL for avatar upload |
+| POST | `/upload/registration-avatar/presigned-url` | 🌐 Public | ✅ | Get presigned URL during registration |
+
+---
+
+### 🎰 Arcade (`/arcade`) - Not Used by SPA
+
+| Method | Endpoint | Security | SPA | Description |
+|--------|----------|----------|-----|-------------|
+| GET | `/arcade/games` | 🌐 Public | ❌ | Get arcade games |
+| POST | `/arcade/play` | 🔐 Secured | ❌ | Play arcade game |
+
+---
+
+### 🎯 Jackpot (`/jackpot`) - Not Used by SPA
+
+| Method | Endpoint | Security | SPA | Description |
+|--------|----------|----------|-----|-------------|
+| GET | `/jackpot/current-round` | 🌐 Public | ❌ | Get current jackpot round |
+| GET | `/jackpot/history` | 🌐 Public | ❌ | Get jackpot history |
+
+---
+
+### 🤖 Bot (`/api/bot`) - Internal Only
+
+| Method | Endpoint | Security | SPA | Description |
+|--------|----------|----------|-----|-------------|
+| POST | `/api/bot/notify` | 🔐 Bot Secret | ❌ | Send notification (bot-to-server) |
+| POST | `/api/bot/game-start` | 🔐 Bot Secret | ❌ | Notify game start |
+
+---
+
+### 🔧 Keeper (`/api/keeper`, `/api/keeper-webhook`) - Internal Only
+
+| Method | Endpoint | Security | SPA | Description |
+|--------|----------|----------|-----|-------------|
+| GET | `/api/keeper/health` | 🌐 Public | ❌ | Keeper health check |
+| POST | `/api/keeper-webhook/trigger` | 🔐 Internal | ❌ | Trigger keeper action |
+
+---
+
+### 🏒 Live Games (`/api/v1/live-games`)
+
+| Method | Endpoint | Security | SPA | Description |
+|--------|----------|----------|-----|-------------|
+| GET | `/api/v1/live-games` | 🌐 Public | ✅ | Get live games (via WebSocket primarily) |
+| GET | `/api/v1/live-games/:gameId` | 🌐 Public | ✅ | Get specific live game |
+| GET | `/api/v1/live-games/:gameId/plays` | 🌐 Public | ✅ | Get play-by-play data |
+
+---
+
+### 📋 Endpoint Summary
+
+| Category | Total | 🔐 Secured | 🌐 Public | ✅ SPA Uses |
+|----------|-------|------------|-----------|-------------|
+| Auth | 21 | 15 | 6 | 21 |
+| Social | 7 | 7 | 0 | 7 |
+| DM | 5 | 5 | 0 | 5 |
+| Chat | 4 | 4 | 0 | 4 |
+| Stats | 3 | 1 | 2 | 3 |
+| Profile | 6 | 2 | 4 | 6 |
+| Sports | 4 | 0 | 4 | 3 |
+| Games | 7 | 1 | 6 | 7 |
+| Transactions | 3 | 0 | 3 | 3 |
+| Exchange Rates | 4 | 0 | 4 | 4 |
+| Crypto Prices | 2 | 0 | 2 | 2 |
+| Analytics | 4 | 0 | 4 | 1 |
+| Upload | 2 | 1 | 1 | 2 |
+| Arcade | 2 | 1 | 1 | 0 |
+| Jackpot | 2 | 0 | 2 | 0 |
+| Bot | 2 | 2 | 0 | 0 |
+| Keeper | 2 | 1 | 1 | 0 |
+| Live Games | 3 | 0 | 3 | 3 |
+| **TOTAL** | **83** | **40** | **43** | **71** |
+
+---
+
+### 🔒 Security Notes
+
+1. **Secured endpoints** require `Authorization: Bearer <JWT_TOKEN>` header
+2. **Public endpoints** can be called without authentication
+3. **Bot endpoints** use `BOT_SECRET` for authentication
+4. **All user-modifying actions** (profile updates, messages, friends) require authentication
+5. **Read-only data** (stats, profiles, scores) is generally public
+
+---
+
+## 🚀 Deployment
+
+### Deploy from Local
+
+```bash
+cd /path/to/dubs-server
+
+# Deploy main branch to production
+git push heroku-prod main
+
+# Deploy specific branch
+git push heroku-prod feature-branch:main
+```
+
+### Rollback
+
+```bash
+# View releases
+heroku releases --app dubs-server-prod
+
+# Rollback to previous release
+heroku rollback --app dubs-server-prod
+
+# Rollback to specific version
+heroku rollback v10 --app dubs-server-prod
+```
+
+---
+
+## 📊 Monitoring & Logs
+
+### View Logs
+
+```bash
+# Tail all logs
+heroku logs --tail --app dubs-server-prod
+
+# View specific dyno logs
+heroku logs --tail --dyno web.1 --app dubs-server-prod
+heroku logs --tail --dyno oracle.1 --app dubs-server-prod
+
+# View last N lines
+heroku logs -n 500 --app dubs-server-prod
+
+# Filter by source
+heroku logs --source app --app dubs-server-prod
+heroku logs --source heroku --app dubs-server-prod
+```
+
+### Check Dyno Status
+
+```bash
+# View running dynos
+heroku ps --app dubs-server-prod
+
+# Restart all dynos
+heroku restart --app dubs-server-prod
+
+# Restart specific dyno
+heroku restart web.1 --app dubs-server-prod
+heroku restart oracle.1 --app dubs-server-prod
+```
+
+### Database Monitoring
+
+```bash
+# View database metrics
+heroku pg:info --app dubs-server-prod
+
+# View slow queries (requires pg:diagnose)
+heroku pg:diagnose --app dubs-server-prod
+
+# View table sizes
+heroku pg:psql --app dubs-server-prod -c "
+SELECT 
+  schemaname,
+  tablename,
+  pg_size_pretty(pg_total_relation_size(schemaname||'.'||tablename)) as size
+FROM pg_tables 
+WHERE schemaname = 'public' 
+ORDER BY pg_total_relation_size(schemaname||'.'||tablename) DESC;
+"
+```
+
+---
+
+## 🔐 Security Notes
+
+### Sensitive Variables
+
+The following variables contain sensitive data - **NEVER commit to git**:
+
+- `DATABASE_URL` - Database connection string with password
+- `JWT_SECRET` - Token signing secret
+- `ORACLE_WALLET_JSON` - Oracle private key
+- `KEEPER_PRIVATE_KEY` - Keeper private key
+- `TELEGRAM_BOT_TOKEN` - Bot authentication token
+- `AWS_SECRET_ACCESS_KEY` - AWS S3 access
+
+### Oracle Wallet
+
+The oracle wallet is stored in `ORACLE_WALLET_JSON` as a JSON array (Solana keypair format).
+
+**Public Key:** `FWUJCthDfPcgmTvdQWM5uofxxiYjqJFMMwiLYvS7LBFa`
+
+This wallet is hardcoded in the Solana program and receives 0.2% oracle fees.
+
+---
+
+## 🔧 Maintenance Tasks
+
+### Run Database Migrations
+
+```bash
+# Run complete schema setup
+heroku pg:psql --app dubs-server-prod < scripts/setup-complete-database.sql
+
+# Run specific migration
+heroku pg:psql --app dubs-server-prod < scripts/add-preferred-currency.sql
+```
+
+### Scale Dynos
+
+```bash
+# Scale up (more dynos or bigger size)
+heroku ps:scale web=2:standard-2x --app dubs-server-prod
+
+# Scale down
+heroku ps:scale web=1:standard-1x --app dubs-server-prod
+
+# Turn off oracle (if needed)
+heroku ps:scale oracle=0 --app dubs-server-prod
+```
+
+### Run One-Off Commands
+
+```bash
+# Run a script
+heroku run node scripts/some-script.js --app dubs-server-prod
+
+# Open a shell
+heroku run bash --app dubs-server-prod
+```
+
+### S3 Bucket Management
+
+```bash
+# List avatars
+aws s3 ls s3://dubs-avatars-prod/avatars/ --summarize
+
+# View bucket size
+aws s3 ls s3://dubs-avatars-prod/ --recursive --summarize
+
+# Delete old avatars (use with caution)
+aws s3 rm s3://dubs-avatars-prod/avatars/OLD_FILE.jpg
+
+# Check bucket policy
+aws s3api get-bucket-policy --bucket dubs-avatars-prod
+
+# Check CORS
+aws s3api get-bucket-cors --bucket dubs-avatars-prod
+```
+
+---
+
+## 🚨 Troubleshooting
+
+### App Not Responding
+
+1. Check dyno status: `heroku ps --app dubs-server-prod`
+2. Check logs: `heroku logs --tail --app dubs-server-prod`
+3. Restart: `heroku restart --app dubs-server-prod`
+
+### Database Connection Issues
+
+1. Check connection count: `heroku pg:info --app dubs-server-prod`
+2. Kill idle connections: `heroku pg:killall --app dubs-server-prod`
+3. Restart app: `heroku restart --app dubs-server-prod`
+
+### Oracle Not Resolving Games
+
+1. Check oracle logs: `heroku logs --tail --dyno oracle.1 --app dubs-server-prod`
+2. Verify `ORACLE_WALLET_JSON` is set correctly
+3. Check Solana RPC endpoint is responsive
+4. Verify oracle wallet has SOL for transaction fees
+
+### High Memory Usage
+
+1. Check metrics: `heroku ps --app dubs-server-prod`
+2. Scale to larger dyno: `heroku ps:scale web=1:standard-2x --app dubs-server-prod`
+
+### Avatar Upload Issues
+
+1. Check S3 credentials: `heroku config:get AWS_ACCESS_KEY_ID --app dubs-server-prod`
+2. Verify bucket exists: `aws s3 ls s3://dubs-avatars-prod/`
+3. Check CORS: `aws s3api get-bucket-cors --bucket dubs-avatars-prod`
+4. Test presigned URL endpoint: `curl -X POST https://dubs-server-prod-9c91d3f01199.herokuapp.com/upload/avatar/presigned-url -H "Authorization: Bearer TOKEN" -d '{"walletAddress":"...","fileExtension":"png"}'`
+
+---
+
+## 💰 Cost Summary
+
+| Resource | Monthly Cost |
+|----------|--------------|
+| Postgres Standard-0 | $50 |
+| Standard-1X Dyno (web) | ~$25 |
+| Standard-1X Dyno (oracle) | ~$25 |
+| **Total Estimated** | **~$100/month** |
+
+---
+
+## 🔗 Related Resources
+
+- **Mainnet Deployment Docs:** `../dubs/docs/LATEST_MAINNET_DEPLOYMENT.md`
+- **Program ID:** `85wJGp9uc8w2FeKX9CEHsudTo1UVCrmuRFy37oCcaoG1`
+- **Solana Explorer:** https://explorer.solana.com/address/85wJGp9uc8w2FeKX9CEHsudTo1UVCrmuRFy37oCcaoG1
+
+---
+
+## 📞 Quick Commands Cheat Sheet
+
+```bash
+# Logs
+heroku logs --tail --app dubs-server-prod
+
+# Restart
+heroku restart --app dubs-server-prod
+
+# Deploy
+git push heroku-prod main
+
+# Database shell
+heroku pg:psql --app dubs-server-prod
+
+# Config
+heroku config --app dubs-server-prod
+
+# Status
+heroku ps --app dubs-server-prod
+
+# Open in browser
+heroku open --app dubs-server-prod
+```
+
+---
+
+**Document maintained by:** Dubs Team  
+**For questions:** Check Heroku dashboard or logs first