SPB Git forge
spboucher.ai ↗

spb/spinza

Public
8commits 1branches 0releases
1.6 MBsize
maindefault branch
16 days agolast push
TypeScript 97.6% SQL 1.4% JavaScript 0.5%
9.6 KB
View source Raw Blame History

# Spinza — original product brief (2026-09-07)

Condensed transcription of the founding CLAUDE.md brief. ../CLAUDE.md is the working guide; this document is the product contract.

# 1–3. Identity & principles

  • Spinza, https://www.spinza.dev — premium fictional social casino. Tagline: Play. Spin. Unlock. Disclaimer: Virtual credits only. No deposits. No withdrawals. No cash value.
  • No real money, deposits, withdrawals, crypto, purchasable/exchangeable credits, monetary prizes, cash-out, marketplace. Closer to a premium gaming platform than gambling.
  • 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).
  • 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.

# 4–8. Accounts

  • Username + password only. No email/phone/social login/verification/email reset.
  • Username unique, 3–24 chars, lowercase, letters/numbers/_/-, profanity filter, reserved list (admin, administrator, root, system, support, spenza, spinza, staff, moderator, api, www, security…).
  • Passwords: Argon2id (argon2), min 8 chars, store password_hash only, never log, never expose.
  • 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.
  • Initial balance 10,000 SC; never displayed with $ € £ CAD USD BTC ETH.

# 9–13. Economy & responsible design

  • 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.
  • 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.
  • Rescue Credits at 0 SC: 2,500 SC, 12 h cooldown, admin-configurable.
  • 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."
  • 18+ confirmation at signup (no DOB stored).

# 14–21. Game platform

  • Shared Spinza Game Engine: definition → math engine → RNG → result generator → game state → animation → renderer.
  • Server-authoritative: POST /api/games/:slug/spin validates balance, generates RNG result, calculates wins, writes atomically, returns balance; frontend only renders.
  • RNG: crypto.randomInt/randomBytes, never Math.random.
  • 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.
  • Engine modules: rng, reels, symbols, ways, paylines, wilds, scatters, multipliers, free-spins, cascades, jackpots, bonus-games, simulation, validation.
  • 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.
  • Internal certification report per game (configured vs observed RTP, deviation, PASS/FAIL); no published without passing.

# 22. Game library (20)

01 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).

# 23–36. Product surfaces

  • Game card: artwork, name, volatility, favourite, play. RTP only in Game Info.
  • 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).
  • 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.
  • Win classes WIN 5× · BIG 20× · MEGA 50× · EPIC 100× · LEGENDARY 500×.
  • Audio per game (ambient, reels, buttons, wins, bonus, big win) with master/music/effects/mute saved in DB.
  • 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_….

# 37–60. Data, security, API

  • 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.
  • 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.
  • 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.
  • Redis for session cache, rate limits, leaderboard cache, live counts, stats; never the wallet source of truth.
  • 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.
  • 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).

# 61–70. Frontend

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

# 71–94. Infrastructure & quality

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

# 95–102. Future & quality bar

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