spb/spinza

1# Spinza — original product brief (2026-09-07)23Condensed transcription of the founding CLAUDE.md brief. `../CLAUDE.md` is the working guide; this document is the product contract.45## 1–3. Identity & principles6- **Spinza**, https://www.spinza.dev — premium fictional social casino. Tagline: *Play. Spin. Unlock.* Disclaimer: *Virtual credits only. No deposits. No withdrawals. No cash value.*7- No real money, deposits, withdrawals, crypto, purchasable/exchangeable credits, monetary prizes, cash-out, marketplace. Closer to a premium gaming platform than gambling.8- Every account receives **10,000 Spinza Credits (SC)**; ~**20 original games**, all built from scratch (no cloned slots, assets, math or branding from any studio).9- Feel: premium, cinematic, fast, modern, mobile-first, immersive, polished. Avoid generic casino templates, cheap UI, identical card grids, excessive gradients, Bootstrap look, crypto aesthetics, fake money marketing.1011## 4–8. Accounts12- Username + password only. No email/phone/social login/verification/email reset.13- Username unique, 3–24 chars, lowercase, letters/numbers/_/-, profanity filter, reserved list (admin, administrator, root, system, support, spenza, spinza, staff, moderator, api, www, security…).14- Passwords: Argon2id (`argon2`), min 8 chars, store `password_hash` only, never log, never expose.15- Recovery code `SPZ-XXXX-XXXX-XXXX` generated at signup, shown once with the warning that lost password + code = unrecoverable account; only a hash is stored. Recovery flow: username + code + new password.16- Initial balance 10,000 SC; never displayed with $ € £ CAD USD BTC ETH.1718## 9–13. Economy & responsible design19- No store, packages, microtransactions, payment provider, Stripe/PayPal/crypto, ads for credits. Credits only from gameplay systems: start grant, daily rewards, achievements, level rewards, missions, tournaments, bonus drops, streaks.20- Daily reward: 1,000 / 1,250 / 1,500 / 1,750 / 2,000 / 2,500 / 5,000 SC (days 1–7), soft reset on missed days.21- Rescue Credits at 0 SC: 2,500 SC, 12 h cooldown, admin-configurable.22- Settings: session reminder (30/60/90/120/off), break reminder, animation intensity, sound, reduce motion. Periodic "You've been playing for 60 minutes. Take a break anytime."23- 18+ confirmation at signup (no DOB stored).2425## 14–21. Game platform26- Shared Spinza Game Engine: definition → math engine → RNG → result generator → game state → animation → renderer.27- **Server-authoritative**: `POST /api/games/:slug/spin` validates balance, generates RNG result, calculates wins, writes atomically, returns balance; frontend only renders.28- RNG: `crypto.randomInt`/`randomBytes`, never `Math.random`.29- Each game defines RTP (94–98 %, default 96 %), volatility, hit frequency, max multiplier, reels, symbols, weights, wilds, scatters, bonuses, free spins, multipliers, jackpot probabilities. JSON/TS `GameDefinition`.30- Engine modules: rng, reels, symbols, ways, paylines, wilds, scatters, multipliers, free-spins, cascades, jackpots, bonus-games, simulation, validation.31- Simulator: 1K → 10M spins without rendering; metrics: observed RTP, hit rate, bonus frequency, avg/median/max win, std dev, distribution, wagered/returned, free-spin & feature frequency.32- Internal certification report per game (configured vs observed RTP, deviation, PASS/FAIL); no `published` without passing.3334## 22. Game library (20)3501 Neon Vault (cyberpunk heist, 5×4, 1024 ways, expanding wilds, vault multipliers, Hack the Vault) · 02 Cosmic Collapse (cascades, gravity multipliers ×1→×13, black-hole wilds) · 03 Golden Emperor (5×3, sticky golden wilds, dragon multiplier) · 04 Diamond Heist (lock-and-respin, Mini/Minor/Major/Grand fictional jackpots) · 05 Arctic Fortune (ice wilds, avalanche cascades, frozen multipliers) · 06 Inferno Reels (high vol, exploding wilds, lava multiplier, chain reactions) · 07 Quantum Jackpot (Quantum Split probabilistic symbols) · 08 Midnight Tokyo (neon respins, stacked wilds, night multiplier) · 09 Pharaoh Protocol (artifact collection, scanning wilds, pyramid bonus) · 10 Lucky Circuit (low vol, frequent small wins) · 11 Void Miner (iron/plasma/crystals/dark matter, dark matter multipliers) · 12 Royal Circuit (laps, boost multiplier, pit-stop bonus) · 13 Dragon Core (dragon charge → Dragon Mode) · 14 Deep Treasure (descending levels, persistent multipliers, chests) · 15 Moonbase 77 (moon gravity, floating wilds, orbital bonus) · 16 Wild Temple (moving wilds, temple chambers, artifact bonuses) · 17 Zero Gravity (grid 5×3 → 6×4 → 7×5 in one bonus) · 18 Reel Reactor (heat meter raises multipliers/volatility/bonus chance) · 19 Obsidian (minimal black luxury, extreme volatility, up to 50,000×) · 20 Spinza Original (flagship: cascades, persistent multipliers, mystery symbols, feature drops, free spins, mega feature).3637## 23–36. Product surfaces38- Game card: artwork, name, volatility, favourite, play. RTP only in Game Info.39- Home: Hero (flagship), Continue Playing, Featured, New Releases, Popular, High Volatility, Relaxed, Jackpot, All Games. Desktop: sidebar + top nav + hero + horizontal collections. Mobile: logo, balance, categories, grid, bottom nav (Home, Games, Rewards, Leaderboard, Profile).40- Game screen: canvas, balance, bet, win, SPIN (always obvious), auto spin (10/25/50/100 with visible STOP; stops on low balance, bonus, stop, boundaries), info, sound, settings. Bets 10/20/50/100/200/500/1,000 SC.41- Win classes WIN 5× · BIG 20× · MEGA 50× · EPIC 100× · LEGENDARY 500×.42- Audio per game (ambient, reels, buttons, wins, bonus, big win) with master/music/effects/mute saved in DB.43- Achievements (First Spin, First Big Win, 100/1,000/10,000 Spins, First Bonus, Jackpot Hunter, Explorer, Play 10 Games, Play Every Game, 100× Club, 1,000× Club), levels 1–100 with XP, missions (daily/weekly), leaderboards (biggest win today/week, biggest multiplier, most spins, highest level; opt-out; no internal IDs), profile, game history with round IDs `spz_rnd_…`.4445## 37–60. Data, security, API46- Immutable ledger `credit_transactions` (INITIAL_GRANT, BET, WIN, DAILY_REWARD, ACHIEVEMENT, MISSION, RESCUE_CREDITS, ADMIN_ADJUSTMENT). Atomic balance: lock wallet → verify → subtract → generate → add → write round → ledger → commit. BIGINT, never floats.47- PostgreSQL + Drizzle. Tables: users, sessions, wallets, credit_transactions, games, game_versions, game_rounds, game_statistics, achievements, user_achievements, missions, user_missions, daily_rewards, player_levels, leaderboards, favorites, user_settings, recovery_codes, security_events. Game versioning `slug@x.y.z` stored on every round.48- Admin `/admin`: dashboard (users, DAU/WAU/MAU, sessions, spins, wagered/won, effective RTP, avg session, top games, highest wins, latency, errors), users, games, simulator (10K–10M with charts), economy, analytics, missions, achievements, daily rewards, system health, security. Admin auth = username + password + TOTP, optional IP restriction.49- Redis for session cache, rate limits, leaderboard cache, live counts, stats; never the wallet source of truth.50- Opaque sessions: HttpOnly Secure SameSite=Lax cookie `spinza_session`, 256-bit token, hash stored. CSRF via SameSite/Origin. Rate limits on login/register/recovery/spin/admin. Login error always "Invalid username or password." Security events logged.51- API: auth (register/login/logout/recover), user, wallet, games, spin, history, rewards/daily(+claim), achievements, missions, leaderboards. Spin request `{bet, clientRoundId}` → `{roundId, game, bet, win, multiplier, balance, result}`; idempotent on `(user_id, client_round_id)`.5253## 61–70. Frontend54- Own design system: dark luxury, deep charcoal, subtle metallic surfaces, high contrast, cinematic art, restrained accent, Geist font. Mobile-first, 44×44 targets. LCP < 2 s, API p95 < 150 ms, spin p95 < 250 ms, 60 FPS. Lazy per-game bundles. Original assets (SVG/procedural). PixiJS reels, GSAP/Framer UI. Particle engine (coins, sparks, fire, snow, stars, energy, diamonds, confetti). Splash "SPINZA / artwork / Loading %"; audio loads progressively.5556## 71–94. Infrastructure & quality57- Private Apple Silicon cluster, ngrok ingress for www.spinza.dev (+ apex redirect), gateway node, internal proxy, web/api/admin/sim services, Postgres/Redis internal only; ports web 3000 / api 3100 / admin 3200 / sim 3300 (cluster uses 8230/8231). PM2 or Docker. Health `/api/health[/database|/redis|/game-engine]`. Structured Pino logs without secrets. Daily Postgres backups with restore tests. Analytics per game. Minimal privacy footprint, no trackers/ads/data sale. SEO for landing only ("Spinza — The Virtual Casino Playground"). Landing → register → welcome +10,000 SC → choose first game (Neon Vault, Cosmic Collapse, Spinza Original). Polished empty/error states, maintenance mode, feature flags, dev/staging/prod, game lifecycle draft→simulation→approved→staging→published→disabled. Tests: Vitest + Playwright (auth, wallet atomicity, RNG, math, duplicate spin, sessions, daily rewards, recovery, leaderboards, admin). Wallet invariants. k6 load tests (100–5,000).5859## 95–102. Future & quality bar60Live events, tournaments (no real prizes), AI Game Factory (still simulated/approved/versioned), `@spinza/game-sdk defineGame(...)`. Spinza is a fictional gaming universe around probability, animation, progression and statistics. Never: copy games/assets/branding, misuse real-money terms, add payments/withdrawals/crypto, plaintext passwords, Math.random outcomes, client-side wins, balance updates without ledger, expose Postgres/Redis, ship an unsimulated game. No fake buttons, dead navigation, placeholder functionality, demo balances, client-side outcomes or static mockups.61