# adityaxjain/typearena architecture

> Architecture diagram of the GitHub repository adityaxjain/typearena, 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/adityaxjain/typearena
- Repository: https://github.com/adityaxjain/typearena

## Overview

##### Project Type & Purpose
- Full-stack, React/Next.js application with real-time multiplayer features.
- Frontend pages and marketing content live under `src/app`, while API endpoints live under `src/app/api`.
- Real-time game interactions use Socket.io (via an Express server) and persistent data is stored via your DB config and models.

##### Main Components
A. Client (Browser)
– Next.js React app
– Pages: marketing (`/about`, `/contact`, etc.), auth (`/login`,`/signup`), gameplay (`/lobby`, `/playground`, `/status`), profile/leaderboard
– Socket.io client (for real-time game events)
B. Next.js Server
– Renders pages (SSR/SSG)
– Hosts static assets (`public/`, CSS, fonts)
– API Routes (`src/app/api/*/route.ts`): login, signup, logout, profile, leaderboard, store-result
– Utilities in `src/lib` (token parsing, ratelimit, etc.)
C. Real-Time Engine
– Express + Socket.io server (could be co-hosted or separate)
– Event handling: room creation/join, text dispatch, progress updates, live scoreboard broadcasts
– Uses `src/data` for sample paragraphs or patterns
D. Database
– Connection & config in `src/dbconfig/dbconfig.ts`
– Models in `src/models` (e.g. `user.model.ts`)
– Stores user credentials, game results
E. State Management (Client-side)
– Zustand or custom store in `src/store/useStore.ts`
F. Deployment & Hosting
– Vercel for Next.js (frontend + serverless API)
– Separate Node server host (for Socket.io/Express) or integrated in Vercel Edge Functions
– Environment via `.env` (see `.env.example`)

##### Relationships & Data Flows
1. HTTP Requests
– Browser → Next.js API Routes (signup/login/profile) → DB
– Browser → Next.js SSR for initial page load
2. WebSocket (Socket.io)
– Browser ↔ Socket.io Server (join room, realtime typing events, scoreboard)
– Socket.io Server ↔ DB (persist match results via HTTP or direct DB writes)
3. State Updates
– Socket events update client store (`useStore.ts`), which drives UI components in `src/components/*`

##### Architectural Patterns & Principles
- Separation of Concerns:
– UI (React components under `src/components`) versus logic (API routes, Socket.io handlers) versus data (models + DB).
- Modular Folder Structure:
– `/app` splits auth, marketing, dynamic pages.
– `/components` splits custom vs. UI primitives.
- Stateless API + JWT:
– `getDataFromToken.ts` decodes tokens; API routes are stateless.
- Real-time Microservice:
– Decouple game-loop/socket layer from SSR/API layer for scalability.

- Clear, concise labels (component name + folder reference)
- Brief notes on major libraries/frameworks per component

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client (Browser UI)" 
        direction TB
        Pages["Pages & Routes\n(src/app)"]:::frontend
        CustomUI["UI Components\n(custom)"]:::frontend
        UIPrimitives["UI Components\n(ui)"]:::frontend
        GlobalStyles["Global Styles & Layout"]:::frontend
        StateStore["State Management\n(useStore.ts)"]:::frontend
    end

    %% Next.js Server Layer
    subgraph "Next.js Server" 
        direction TB
        SSRServer["SSR/SSG\nNext.js"]:::backend
        StaticAssets["Static Assets\n(public/)"]:::backend
        NextConfig["next.config.mjs"]:::backend
        TSConfig["tsconfig.json"]:::backend
        TailwindConfig["tailwind.config.ts"]:::backend
    end

    %% API Routes Layer
    subgraph "API Routes (src/app/api)" 
        direction TB
        Login["login/route.ts"]:::backend
        Signup["signup/route.ts"]:::backend
        Logout["logout/route.ts"]:::backend
        Profile["profile/route.ts"]:::backend
        PlayerProfile["player-profile/route.ts"]:::backend
        Leaderboard["leaderboard/route.ts"]:::backend
        StoreResult["store-result/route.ts"]:::backend
    end

    %% Utilities Layer
    subgraph "Utilities (src/lib)" 
        direction TB
        TokenUtil["getDataFromToken.ts"]:::backend
        RateLimit["ratelimit.ts"]:::backend
        Utils["utils.ts"]:::backend
    end

    %% Real-Time Engine Layer
    subgraph "Real-Time Engine" 
        direction TB
        SampleParagraphs["sampleParagraphs.ts"]:::realtime
        Pattern["pattern.ts"]:::realtime
        SocketServer["Socket.io Server\n(Express)"]:::realtime
    end

    %% Database Layer
    subgraph "Database" 
        direction TB
        DBConfig["dbconfig.ts"]:::db
        UserModel["user.model.ts"]:::db
    end

    %% External Hosting
    Vercel["Vercel"]:::external

    %% Connections
    Pages -->|"HTTP"| SSRServer
    SSRServer --> Login
    SSRServer --> Signup
    SSRServer --> Logout
    SSRServer --> Profile
    SSRServer --> PlayerProfile
    SSRServer --> Leaderboard
    SSRServer --> StoreResult

    Login -->|"DB Read/Write"| DBConfig
    Signup --> DBConfig
    Logout --> DBConfig
    Profile --> DBConfig
    PlayerProfile --> DBConfig
    Leaderboard --> DBConfig
    StoreResult --> DBConfig

    CustomUI --> Pages
    UIPrimitives --> Pages
    GlobalStyles --> Pages

    StateStore --> Pages
    StateStore --> SocketServer

    Pages <-->|"WebSocket"| SocketServer
    SocketServer -->|"DB Write"| UserModel

    SSRServer --> Vercel
    StaticAssets --> Vercel

    TokenUtil --> Login
    RateLimit --> Signup
    Utils --> StoreResult

    SampleParagraphs --> SocketServer
    Pattern --> SocketServer

    %% Click Events
    click Pages "https://github.com/adityaxjain/typearena/blob/main/src/app/(auth)/*/page.tsx"
    click CustomUI "https://github.com/adityaxjain/typearena/tree/main/src/components/custom/*"
    click UIPrimitives "https://github.com/adityaxjain/typearena/tree/main/src/components/ui/*"
    click GlobalStyles "https://github.com/adityaxjain/typearena/blob/main/src/app/globals.css"
    click StateStore "https://github.com/adityaxjain/typearena/blob/main/src/store/useStore.ts"
    click StaticAssets "https://github.com/adityaxjain/typearena/tree/main/public/"
    click NextConfig "https://github.com/adityaxjain/typearena/blob/main/next.config.mjs"
    click TSConfig "https://github.com/adityaxjain/typearena/blob/main/tsconfig.json"
    click TailwindConfig "https://github.com/adityaxjain/typearena/blob/main/tailwind.config.ts"
    click Login "https://github.com/adityaxjain/typearena/blob/main/src/app/api/login/route.ts"
    click Signup "https://github.com/adityaxjain/typearena/blob/main/src/app/api/signup/route.ts"
    click Logout "https://github.com/adityaxjain/typearena/blob/main/src/app/api/logout/route.ts"
    click Profile "https://github.com/adityaxjain/typearena/blob/main/src/app/api/profile/route.ts"
    click PlayerProfile "https://github.com/adityaxjain/typearena/blob/main/src/app/api/player-profile/route.ts"
    click Leaderboard "https://github.com/adityaxjain/typearena/blob/main/src/app/api/leaderboard/route.ts"
    click StoreResult "https://github.com/adityaxjain/typearena/blob/main/src/app/api/store-result/route.ts"
    click TokenUtil "https://github.com/adityaxjain/typearena/blob/main/src/lib/getDataFromToken.ts"
    click RateLimit "https://github.com/adityaxjain/typearena/blob/main/src/lib/ratelimit.ts"
    click Utils "https://github.com/adityaxjain/typearena/blob/main/src/lib/utils.ts"
    click SampleParagraphs "https://github.com/adityaxjain/typearena/blob/main/src/data/sampleParagraphs.ts"
    click Pattern "https://github.com/adityaxjain/typearena/blob/main/src/data/pattern.ts"
    click DBConfig "https://github.com/adityaxjain/typearena/blob/main/src/dbconfig/dbconfig.ts"
    click UserModel "https://github.com/adityaxjain/typearena/blob/main/src/models/user.model.ts"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef backend fill:#90EE90,stroke:#000,stroke-width:1px
    classDef db fill:#FFA500,stroke:#000,stroke-width:1px
    classDef realtime fill:#DDA0DD,stroke:#000,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:1px
```
