# jainsamyak15/masskribbl architecture

> Architecture diagram of the GitHub repository jainsamyak15/masskribbl, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jainsamyak15/masskribbl
- Repository: https://github.com/jainsamyak15/masskribbl

## Overview

##### Project Type and Purpose
- Frontend: Next.js app (React + TypeScript + Tailwind + Radix UI + Framer Motion).
- Real-time layer: Socket.IO server (Node.js).
- Persistence & auth: Supabase (Postgres + Auth).
- State management: Zustand.
- Utilities & word lists on both client (lib/words.ts) and server (server/words.js).

##### High-Level Architecture Components
A. Frontend (Next.js)
- Pages & routing (app/ directory)
– Home / Lobby (/page.tsx, lobby create/join/quick)
– Game room (/game/[roomCode]/page.tsx)
- UI Components (components/auth, /lobby, /game, /ui)
- Global styles: Tailwind (app/globals.css)
- Client libraries (lib/)
– Socket.IO client (lib/socket.ts)
– Supabase client (lib/supabase.ts)
– Zustand store (lib/store.ts)
– Utility modules (lib/utils.ts, lib/words.ts)

B. Real-Time Backend (Node.js + Socket.IO)
- socket-server.js: handles namespace, events (joinRoom, startGame, drawStroke, chatMessage, endTurn)
- words.js: server-side word lists & random selection
- supabase.js: optional persistence calls (game history, user events)

C. Database & Auth (Supabase)
- Auth: email/username (NextAuth/Supabase Auth)
- Tables (via supabase/migrations/*.sql): users, rooms, games, scores, chat_log, word_history
- Realtime subscriptions (optional)

D. (Optional) Smart Contracts Module
- contracts/assembly: AssemblyScript contracts + tests (as-pect)
- contracts/src: scripts for deploy/test (deploy.ts, hello.ts, utils.ts)
- Used for blockchain-based features (if applicable) or just CI tests

E. Deployment & CI
- Frontend: Vercel or Netlify (Next.js build)
- Socket.IO Server: Railway/Heroku (Node.js)
- CI: GitHub Actions (contracts/.github/workflows/ci-tests.yml)

##### User Flow
1. User opens https://… → Next.js renders Home page.
2. Login/Signup via Supabase Auth (components/auth/LoginForm).
3. User chooses Quick Play / Create Room / Join Room → triggers API calls (app/api/socket/route.ts) or Socket.IO “createRoom” event.
4. Server assigns roomCode, persists in Supabase.
5. Clients join Socket.IO room → Zustand store updates player list.
6. Once ≥2 players, host clicks “Start Game” → server initializes game state, selects word choices.
7. Drawer client receives word list → draws on HTML5 Canvas (components/game/DrawingCanvas + DrawingTools).
8. Drawing strokes broadcast via Socket.IO “drawStroke” events → other clients render in real time.
9. Guessers send chat messages (components/game/GameChat) → server tests guesses vs target word.
10. On correct guess or timer expiry, server calculates points → updates Supabase & broadcasts new scores.
11. GameTimer counts down per turn (components/game/GameTimer) → loop until rounds complete.
12. End of game: leaderboard shown (components/game/PlayerList + Score display), history written to Supabase.

##### Architectural Patterns & Design Principles
- Separation of concerns: UI components vs state vs network logic.
- Event-driven real-time communication (Socket.IO pub/sub model).
- Centralized state management (Zustand) for cross‐component sync.
- API layer vs WebSocket layer: Next.js API routes for REST/HTTP needs, Socket.IO for bidirectional events.
- Modular directory layout: “app/” for pages, “components/” for UI, “lib/” for client utilities.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (Next.js)" 
        direction TB
        subgraph "Pages & Routing"
            direction TB
            HomePage["Home Page"]:::fe
            GameRoomPage["Game Room Page"]:::fe
            APIRoute["Socket API Route"]:::fe
        end
        subgraph "UI Components"
            direction TB
            LoginForm["Login Form"]:::fe
            CreateRoom["Create Room"]:::fe
            JoinRoom["Join Room"]:::fe
            QuickPlay["Quick Play"]:::fe
            DrawingCanvas["Drawing Canvas"]:::fe
            DrawingTools["Drawing Tools"]:::fe
            GameChat["Game Chat"]:::fe
            GameTimer["Turn Timer"]:::fe
            PlayerList["Player List & Scores"]:::fe
            WordChoices["Word Choices"]:::fe
            WordHint["Word Hint"]:::fe
            subgraph "Shared UI Primitives"
                direction TB
                Button["Button"]:::fe
                Input["Input"]:::fe
                Card["Card"]:::fe
                Avatar["Avatar"]:::fe
                Badge["Badge"]:::fe
                Progress["Progress"]:::fe
            end
        end
        subgraph "Client Libraries & State"
            direction TB
            SocketClient["Socket.IO Client"]:::fe
            SupabaseClient["Supabase Client"]:::fe
            ZustandStore["Zustand Store"]:::fe
            Utils["Utility Functions"]:::fe
            WordsClient["Word List"]:::fe
        end
        subgraph "Styles & Layout"
            direction TB
            GlobalsCSS["Global CSS"]:::fe
            RootLayout["Root Layout"]:::fe
        end
    end

    %% Backend Layer
    subgraph "Real-Time Backend (Node.js + Socket.IO)"
        direction TB
        Server["Socket.IO Server"]:::be
        WordsServer["Word Engine"]:::be
        SupabaseAdapter["Supabase Adapter"]:::be
    end

    %% Supabase Layer
    subgraph "Supabase"
        direction TB
        AuthService["Auth Service"]:::ext
        DB[(Postgres DB)]:::db
        Migrations["SQL Migrations"]:::db
    end

    %% Optional Contracts Module
    subgraph "Smart Contracts (Optional)"
        direction TB
        Assembly["AssemblyScript Contracts"]:::ext
        ContractScripts["Deploy/Test Scripts"]:::ext
        CIWorkflow["CI Workflow"]:::ext
    end

    %% Deployment & CI
    subgraph "Deployment & CI"
        direction TB
        Vercel["Vercel (Frontend)"]:::ext
        Heroku["Railway/Heroku (Socket.IO)"]:::ext
        GitHubActions["GitHub Actions"]:::ext
    end

    %% User
    User["User (Browser)"]:::ext

    %% Relationships
    User -->|"HTTPS"| HomePage
    User -->|"HTTPS"| GameRoomPage
    HomePage -->|"REST Auth"| AuthService
    APIRoute -->|"HTTPS API"| SupabaseClient
    HomePage -->|"WSS"| Server
    GameRoomPage -->|"WSS"| Server
    Server -->|"SQL Reads/Writes"| DB
    Server -->|"Auth Check"| AuthService
    Server -->|"Word Fetch"| WordsServer
    Server -->|"Persistence"| SupabaseAdapter
    SupabaseAdapter -->|"SQL"| DB
    User -->|"Interacts"| LoginForm
    LoginForm -->|"Auth API"| AuthService
    User -->|"Interacts"| CreateRoom
    CreateRoom -->|"WSS:createRoom"| Server
    User -->|"Interacts"| JoinRoom
    JoinRoom -->|"WSS:joinRoom"| Server
    User -->|"Interacts"| QuickPlay
    QuickPlay -->|"WSS:createQuick"| Server
    User -->|"Draw/Guess"| DrawingCanvas
    DrawingCanvas -->|"WSS:drawStroke"| Server
    User -->|"Chat"| GameChat
    GameChat -->|"WSS:chatMessage"| Server
    Server -->|"Broadcast Events"| ZustandStore
    ZustandStore -->|"State Update"| DrawingCanvas
    ZustandStore -->|"State Update"| GameChat
    ============================================
    %% Optional CI/CD
    GitHubActions -->|"Runs Tests"| CIWorkflow
    CIWorkflow -->|"Deploy Contracts"| Assembly
    Vercel -->|"Deploy"| HomePage
    Heroku -->|"Deploy"| Server

    %% Click Events
    click HomePage "https://github.com/jainsamyak15/masskribbl/blob/main/app/page.tsx"
    click GameRoomPage "https://github.com/jainsamyak15/masskribbl/blob/main/app/game/[roomCode]/page.tsx"
    click APIRoute "https://github.com/jainsamyak15/masskribbl/blob/main/app/api/socket/route.ts"
    click LoginForm "https://github.com/jainsamyak15/masskribbl/blob/main/components/auth/LoginForm.tsx"
    click CreateRoom "https://github.com/jainsamyak15/masskribbl/blob/main/components/lobby/CreateRoom.tsx"
    click JoinRoom "https://github.com/jainsamyak15/masskribbl/blob/main/components/lobby/JoinRoom.tsx"
    click QuickPlay "https://github.com/jainsamyak15/masskribbl/blob/main/components/lobby/QuickPlay.tsx"
    click DrawingCanvas "https://github.com/jainsamyak15/masskribbl/blob/main/components/game/DrawingCanvas.tsx"
    click DrawingTools "https://github.com/jainsamyak15/masskribbl/blob/main/components/game/DrawingTools.tsx"
    click GameChat "https://github.com/jainsamyak15/masskribbl/blob/main/components/game/GameChat.tsx"
    click GameTimer "https://github.com/jainsamyak15/masskribbl/blob/main/components/game/GameTimer.tsx"
    click PlayerList "https://github.com/jainsamyak15/masskribbl/blob/main/components/game/PlayerList.tsx"
    click WordChoices "https://github.com/jainsamyak15/masskribbl/blob/main/components/game/WordChoices.tsx"
    click WordHint "https://github.com/jainsamyak15/masskribbl/blob/main/components/game/WordHint.tsx"
    click Button "https://github.com/jainsamyak15/masskribbl/blob/main/components/ui/button.tsx"
    click Input "https://github.com/jainsamyak15/masskribbl/blob/main/components/ui/input.tsx"
    click Card "https://github.com/jainsamyak15/masskribbl/blob/main/components/ui/card.tsx"
    click Avatar "https://github.com/jainsamyak15/masskribbl/blob/main/components/ui/avatar.tsx"
    click Badge "https://github.com/jainsamyak15/masskribbl/blob/main/components/ui/badge.tsx"
    click Progress "https://github.com/jainsamyak15/masskribbl/blob/main/components/ui/progress.tsx"
    click GlobalsCSS "https://github.com/jainsamyak15/masskribbl/blob/main/app/globals.css"
    click RootLayout "https://github.com/jainsamyak15/masskribbl/blob/main/app/layout.tsx"
    click SocketClient "https://github.com/jainsamyak15/masskribbl/blob/main/lib/socket.ts"
    click SupabaseClient "https://github.com/jainsamyak15/masskribbl/blob/main/lib/supabase.ts"
    click ZustandStore "https://github.com/jainsamyak15/masskribbl/blob/main/lib/store.ts"
    click Utils "https://github.com/jainsamyak15/masskribbl/blob/main/lib/utils.ts"
    click WordsClient "https://github.com/jainsamyak15/masskribbl/blob/main/lib/words.ts"
    click Server "https://github.com/jainsamyak15/masskribbl/blob/main/server/socket-server.js"
    click WordsServer "https://github.com/jainsamyak15/masskribbl/blob/main/server/words.js"
    click SupabaseAdapter "https://github.com/jainsamyak15/masskribbl/blob/main/server/supabase.js"
    click Migrations "https://github.com/jainsamyak15/masskribbl/tree/main/supabase/migrations"
    click Assembly "https://github.com/jainsamyak15/masskribbl/tree/main/contracts/assembly"
    click ContractScripts "https://github.com/jainsamyak15/masskribbl/blob/main/contracts/src/deploy.ts"
    click CIWorkflow "https://github.com/jainsamyak15/masskribbl/blob/main/contracts/.github/workflows/ci-tests.yml"

    %% Styles
    classDef fe fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef be fill:#DFFFE0,stroke:#228B22,color:#228B22;
    classDef db fill:#FFEFD5,stroke:#FF8C00,color:#FF8C00;
    classDef ext fill:#F0F0F0,stroke-dasharray:5 5,color:#888;
    class User ext
    class Assembly,ContractScripts,CIWorkflow,Vercel,Heroku,GitHubActions ext
```
