# saurav4359/squiz architecture

> Architecture diagram of the GitHub repository saurav4359/squiz, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/saurav4359/squiz
- Repository: https://github.com/saurav4359/squiz

## Overview

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: [`src/screens`](https://github.com/saurav4359/squiz/tree/main/src/screens) (Screens), [`src/services/wallet/solanaWallet.ts`](https://github.com/saurav4359/squiz/blob/main/src/services/wallet/solanaWallet.ts) (Wallet bridge), [`backend/server.ts`](https://github.com/saurav4359/squiz/blob/main/backend/server.ts) (Backend server), [`App.tsx`](https://github.com/saurav4359/squiz/blob/main/App.tsx) (App shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Mobile client"]
  node_app_shell["App shell<br/>expo entry<br/>[App.tsx]"]
  node_entry_point["Entry<br/>[index.ts]"]
  node_theme_polyfills["Theme setup<br/>ui runtime<br/>[theme.ts]"]
  node_auth_wallet_hooks["Auth hooks<br/>state hooks<br/>[useAuth.ts]"]
  node_local_store[("Local store<br/>persisted state<br/>[store.ts]")]
  node_local_storage[("Storage<br/>[storage.ts]")]
  node_screens["Screens<br/>navigation flows"]
  node_wallet_bridge["Wallet bridge<br/>solana wallet<br/>[solanaWallet.ts]"]
  node_token_utils["Token utils<br/>wallet tokens<br/>[tokenUtils.ts]"]
  node_explorer_client["Explorer<br/>solscan client<br/>[solscan.ts]"]
  node_matchmaking_client["Matchmaking<br/>live game<br/>[liveMatchmaking.ts]"]
  node_ai_fairness["AI fairness<br/>content + anti-cheat"]
end

subgraph group_backend["Realtime backend"]
  node_backend_server["Backend server<br/>bun realtime server<br/>[server.ts]"]
  node_backend_query["Query layer<br/>db access<br/>[query.js]"]
end

subgraph group_infra["Persistence and chain"]
  node_schema_migrations[("Schema<br/>sql migrations<br/>[schema.sql]")]
  node_database[("Postgres<br/>[database.ts]")]
  node_solana_chain(("Solana<br/>chain boundary"))
  node_external_wallets{{"Wallet adapter<br/>[withMWA.js]"}}
end

node_entry_point -->|"boot"| node_app_shell
node_app_shell -->|"setup"| node_theme_polyfills
node_app_shell -->|"render"| node_screens
node_screens -->|"session"| node_auth_wallet_hooks
node_auth_wallet_hooks -->|"persist"| node_local_store
node_local_store -->|"backing"| node_local_storage
node_screens -->|"connect"| node_wallet_bridge
node_wallet_bridge -->|"sign"| node_external_wallets
node_wallet_bridge -->|"balance"| node_token_utils
node_wallet_bridge -->|"submit"| node_solana_chain
node_screens -->|"play"| node_matchmaking_client
node_matchmaking_client -->|"sync"| node_backend_server
node_matchmaking_client -->|"validate"| node_ai_fairness
node_ai_fairness -->|"verify"| node_backend_server
node_backend_server -->|"read/write"| node_backend_query
node_backend_query -->|"persist"| node_database
node_database -->|"defined by"| node_schema_migrations
node_backend_server -->|"settle"| node_solana_chain
node_screens -->|"inspect"| node_explorer_client

click node_app_shell "https://github.com/saurav4359/squiz/blob/main/App.tsx"
click node_entry_point "https://github.com/saurav4359/squiz/blob/main/index.ts"
click node_theme_polyfills "https://github.com/saurav4359/squiz/blob/main/src/config/theme.ts"
click node_auth_wallet_hooks "https://github.com/saurav4359/squiz/blob/main/src/hooks/useAuth.ts"
click node_local_store "https://github.com/saurav4359/squiz/blob/main/src/lib/store.ts"
click node_local_storage "https://github.com/saurav4359/squiz/blob/main/src/lib/storage.ts"
click node_screens "https://github.com/saurav4359/squiz/tree/main/src/screens"
click node_wallet_bridge "https://github.com/saurav4359/squiz/blob/main/src/services/wallet/solanaWallet.ts"
click node_token_utils "https://github.com/saurav4359/squiz/blob/main/src/services/wallet/tokenUtils.ts"
click node_explorer_client "https://github.com/saurav4359/squiz/blob/main/src/services/explorer/solscan.ts"
click node_matchmaking_client "https://github.com/saurav4359/squiz/blob/main/src/services/matchmaking/liveMatchmaking.ts"
click node_ai_fairness "https://github.com/saurav4359/squiz/blob/main/src/services/ai/questionGenerator.ts"
click node_backend_server "https://github.com/saurav4359/squiz/blob/main/backend/server.ts"
click node_backend_query "https://github.com/saurav4359/squiz/blob/main/backend/query.js"
click node_schema_migrations "https://github.com/saurav4359/squiz/blob/main/schema.sql"
click node_database "https://github.com/saurav4359/squiz/blob/main/src/services/db/database.ts"
click node_external_wallets "https://github.com/saurav4359/squiz/blob/main/withMWA.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app_shell,node_entry_point,node_theme_polyfills,node_auth_wallet_hooks,node_local_store,node_local_storage,node_screens,node_wallet_bridge,node_token_utils,node_explorer_client,node_matchmaking_client,node_ai_fairness toneBlue
class node_backend_server,node_backend_query toneAmber
class node_schema_migrations,node_database,node_solana_chain,node_external_wallets toneMint
```

## Components

### Mobile client

Expo React Native app, screens, local state, and device-side wallet flows.

- [App shell](https://github.com/saurav4359/squiz/blob/main/App.tsx): expo entry · Application bootstrap and runtime setup. · `App.tsx`
- [Entry](https://github.com/saurav4359/squiz/blob/main/index.ts): native entry · Native app entry used to start the Expo bundle. · `index.ts`
- [Theme setup](https://github.com/saurav4359/squiz/blob/main/src/config/theme.ts): ui runtime · Shared theme and compatibility polyfills for the app shell. · `src/config/theme.ts`
- [Auth hooks](https://github.com/saurav4359/squiz/blob/main/src/hooks/useAuth.ts): state hooks · Client session and wallet state orchestration. · `src/hooks/useAuth.ts`
- [Local store](https://github.com/saurav4359/squiz/blob/main/src/lib/store.ts): persisted state · Local app state and persistence layer. · `src/lib/store.ts`
- [Storage](https://github.com/saurav4359/squiz/blob/main/src/lib/storage.ts): MMKV storage · Low-latency on-device storage helpers. · `src/lib/storage.ts`
- [Screens](https://github.com/saurav4359/squiz/tree/main/src/screens): navigation flows · Primary player journeys across onboarding, hub, gameplay, and history. · `src/screens`
- [Wallet bridge](https://github.com/saurav4359/squiz/blob/main/src/services/wallet/solanaWallet.ts): solana wallet · On-device wallet adapter and signing integration. · `src/services/wallet/solanaWallet.ts`
- [Token utils](https://github.com/saurav4359/squiz/blob/main/src/services/wallet/tokenUtils.ts): wallet tokens · Balance and token formatting helpers for deposits and settlement. · `src/services/wallet/tokenUtils.ts`
- [Explorer](https://github.com/saurav4359/squiz/blob/main/src/services/explorer/solscan.ts): solscan client · External blockchain explorer enrichment. · `src/services/explorer/solscan.ts`
- [Matchmaking](https://github.com/saurav4359/squiz/blob/main/src/services/matchmaking/liveMatchmaking.ts): live game · Client-side queueing, presence, stats, and rating support. · `src/services/matchmaking/liveMatchmaking.ts`
- [AI fairness](https://github.com/saurav4359/squiz/blob/main/src/services/ai/questionGenerator.ts): content + anti-cheat · 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](https://github.com/saurav4359/squiz/blob/main/backend/server.ts): bun realtime server · Central coordination, websocket orchestration, and durable write authority. · `backend/server.ts`
- [Query layer](https://github.com/saurav4359/squiz/blob/main/backend/query.js): db access · Thin database helper and query abstraction for the backend. · `backend/query.js`

### Persistence and chain

Database schema, migrations, and external execution boundaries.

- [Schema](https://github.com/saurav4359/squiz/blob/main/schema.sql): sql migrations · Database schema and migration history for treasury, quests, and gameplay records. · `schema.sql`
- [Postgres](https://github.com/saurav4359/squiz/blob/main/src/services/db/database.ts): Neon postgres · Hosted persistence for match, quest, and leaderboard data. · `src/services/db/database.ts`
- **Solana**: chain boundary · On-chain escrow, staking, and settlement boundary.
- [Wallet adapter](https://github.com/saurav4359/squiz/blob/main/withMWA.js): mobile wallet adapter · User-controlled signing interface on device. · `withMWA.js`

## Connections

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