How saurav4359/squiz works
1. System shape
- This repo is split into a mobile client and a real-time Bun backend.
- The client is a React Native / Expo app; the backend is the game coordination layer, database gateway, and likely WebSocket host.
- On-chain Solana actions are a separate boundary: the app signs transactions through a wallet adapter, while the backend tracks game state and persistence.
2. Mobile app shell
- The app entry points are index.ts, App.tsx, and Expo config files.
- The UI is organized by screen-level flows in src/screens, with navigation implied around onboarding, matchmaking, battle, results, profile, and history.
- src/config/theme.ts and src/polyfills.ts support the app shell and UI/runtime compatibility.
3. Primary user journeys
- ConnectWalletScreen handles onboarding into the Web3 flow.
- HomeScreen, ProfileScreen, and DailyQuestsScreen are the player hub.
- DepositScreen handles funding the in-game balance.
- MatchmakingScreen, BattleScreen, and ResultsScreen are the core gameplay loop.
- LeaderboardScreen and MatchHistoryScreen provide post-game progression and social proof.
4. Client state and persistence boundary
- src/hooks/useAuth.ts and src/hooks/useWallet.ts encapsulate user/session and wallet state.
- src/lib/store.ts and src/lib/storage.ts indicate local persisted state, likely using MMKV as described in the README.
- This means transient game state, wallet/session data, and UI preferences are kept locally for fast startup and low-latency gameplay.
5. Solana and wallet integration
- src/services/wallet/solanaWallet.ts is the main bridge to Solana wallet functionality.
- The app uses Solana Mobile Wallet Adapter-style flows, so signing happens on-device rather than through a hosted custodial wallet.
- src/services/wallet/tokenUtils.ts likely centralizes balance, token formatting, and stake/escrow-related token logic.
- src/services/explorer/solscan.ts suggests the UI can enrich transactions or accounts with external explorer data.
6. Real-time matchmaking and game coordination
- src/services/matchmaking/liveMatchmaking.ts appears to own queueing and opponent pairing.
- src/services/matchmaking/livePresence.ts likely tracks whether players are online/available.
- src/services/matchmaking/matchStats.ts and src/services/matchmaking/ratingSystem.ts support match outcomes, scoring, and rank updates.
- This is the main live-game subsystem and is the most likely consumer of Socket.io-style server events.
7. Gameplay content and fairness
- src/services/ai/questionGenerator.ts is responsible for trivia generation.
- src/services/ai/antiCheat.ts indicates the game has a trust/fairness layer, likely validating answer timing or detecting suspicious behavior.
- Together, these services sit between content creation and competitive integrity, not in the rendering path.
8. Backend runtime
- The backend lives under backend/ and is centered on backend/server.ts with Bun as the runtime.
- backend/query.js implies a thin database access layer or SQL helper.
- The backend is where matchmaking coordination, leaderboard writes, match history persistence, and any WebSocket orchestration would be centralized.
- The README’s Socket.io claim suggests the server is the live synchronization authority for multiplayer sessions.
9. Database and schema management
- schema.sql plus the migrations/ directory define the persistent game model.
- Migration names like 001_treasury_columns.sql and 005_skr_quests.sql show the schema includes:
- treasury/stake accounting
- quest progression
- likely match records, player stats, and leaderboard materialization
- This is a separate persistence boundary from the mobile app’s local MMKV store.
10. Data flow through the game
- The typical flow is: wallet connect → local auth/wallet state → deposit/fund balance → matchmaking queue → live battle → settlement/results → database writeback → profile/leaderboard updates.
- The client owns presentation and user action capture.
- The backend owns pairing, match state, and durable statistics.
- On-chain escrow is the trust layer for stakes and prize distribution.
11. External infrastructure
- The README specifies Neon PostgreSQL as the hosted database.
- Solana is the blockchain dependency for staking and settlement.
- The app also depends on mobile wallet integration and an explorer service for blockchain visibility.
- No heavy cloud microservice topology is visible; this looks like a focused client + single realtime backend architecture.
12. Repo-level boundaries to diagram
- Presentation boundary: src/screens, src/config/theme.ts
- Client state boundary: hooks, MMKV-backed storage, store
- Game logic boundary: matchmaking, rating, stats, anti-cheat, question generation
- Web3 boundary: wallet adapter, token utilities, explorer integration
- Server boundary: Bun backend and query layer
- Persistence boundary: SQL schema + migrations + Neon Postgres
- Chain boundary: Solana escrow/settlement
Main entry points: screens Screens · solanaWallet.ts Wallet bridge · server.ts Backend server · App.tsx App shell
Components 18
Mobile client
Expo React Native app, screens, local state, and device-side wallet flows.
- App shell · Application bootstrap and runtime setup.
App.tsx - Entry · Native app entry used to start the Expo bundle.
index.ts - Theme setup · Shared theme and compatibility polyfills for the app shell.
src/config/theme.ts - Auth hooks · Client session and wallet state orchestration.
src/hooks/useAuth.ts - Local store · Local app state and persistence layer.
src/lib/store.ts - Storage · Low-latency on-device storage helpers.
src/lib/storage.ts - Screens · Primary player journeys across onboarding, hub, gameplay, and history.
src/screens - Wallet bridge · On-device wallet adapter and signing integration.
src/services/wallet/solanaWallet.ts - Token utils · Balance and token formatting helpers for deposits and settlement.
src/services/wallet/tokenUtils.ts - Explorer · External blockchain explorer enrichment.
src/services/explorer/solscan.ts - Matchmaking · Client-side queueing, presence, stats, and rating support.
src/services/matchmaking/liveMatchmaking.ts - AI fairness · Question generation and trust/fairness checks for gameplay.
src/services/ai/questionGenerator.ts
Realtime backend
Bun server and persistence/query layer for coordination and writes.
- Backend server · Central coordination, websocket orchestration, and durable write authority.
backend/server.ts - Query layer · Thin database helper and query abstraction for the backend.
backend/query.js
Persistence and chain
Database schema, migrations, and external execution boundaries.
- Schema · Database schema and migration history for treasury, quests, and gameplay records.
schema.sql - Postgres · Hosted persistence for match, quest, and leaderboard data.
src/services/db/database.ts - Solana · On-chain escrow, staking, and settlement boundary.
- Wallet adapter · User-controlled signing interface on device.
withMWA.js
Connections 19
- Entry → App shell: boot · Starts the mobile app runtime.
- App shell → Theme setup: setup · Loads shared UI theme and compatibility shims.
- App shell → Screens: render · Hosts the screen-level user journeys.
- Screens → Auth hooks: session · Screens consume auth and wallet state.
- Auth hooks → Local store: persist · Session and UI state are cached locally.
- Local store → Storage: backing · Store is backed by on-device storage.
- Screens → Wallet bridge: connect · Onboarding and deposit flows trigger wallet actions.
- Wallet bridge → Wallet adapter: sign · Transactions are signed through the device wallet adapter.
- Wallet bridge → Token utils: balance · Token helpers support funding and settlement views.
- Wallet bridge → Solana: submit · Signed transactions are sent to the chain boundary.
- Screens → Matchmaking: play · Matchmaking and battle screens drive live game flow.
- Matchmaking → Backend server: sync · Live queue, presence, and match events flow to the server.
- Matchmaking → AI fairness: validate · Gameplay uses content generation and anti-cheat checks.
- AI fairness → Backend server: verify · Fairness and match outcomes feed authoritative coordination.
- Backend server → Query layer: read/write · Server uses a query layer for persistence operations.
- Query layer → Postgres: persist · Queries target the hosted Postgres database.
- Postgres → Schema: defined by · Schema and migrations define the persistent model.
- Backend server → Solana: settle · Server coordinates game state around on-chain settlement.
- Screens → Explorer: inspect · UI can surface transaction or account details from explorers.