# fanyuuu2006/labag-web architecture

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

- Interactive diagram: https://gitdiagram.com/fanyuuu2006/labag-web
- Repository: https://github.com/fanyuuu2006/labag-web

## Overview

##### Project Type and Purpose
- This is a full-stack web game application (“啦八機”) implemented with a Next.js/React frontend and an Express/TypeScript backend.
- The frontend renders the game UI, manages game logic (random symbol generation, score calculation, modes), and consumes backend APIs for authentication and score persistence.
- The backend exposes RESTful endpoints for user authentication (via Google OAuth + JWT), rate-limiting, and CRUD operations on user profiles and game records.

##### File Structure Analysis
- Top level:
- frontend/ – Next.js application (app directory, pages, components, contexts, public assets, styling, TypeScript config).
- backend/  – Express server (src folder structured by config, controllers, middlewares, routes, utils, types, plus tsconfig.json and Vercel deployment config).
- Patterns:
- Backend follows an MVC-inspired layering:
– config/ (dotenv, Passport setup, Google API keys)
– routes/ → controllers/ → utils/types
– middlewares (auth, rate-limit, request signing)
- Frontend uses component-based React organization, Next.js “app” directory routing, plus React Context for global state (User, Music, Mode).
- Deployment cues: Vercel configuration in backend and Next.js config in frontend suggest serverless or cloud deployment.

##### Key Insights from README
- Multi-mode game logic (normal, SuperHHH, GreenWei, PiKaChu), dynamic symbol generation, real-time score display.
- Score upload via API → real-time leaderboard.
- Uses audio/image assets stored in /public served by Next.js static hosting.

a. Main Components
1. Client (Browser)
- Next.js React App
- Game Engine & UI Components
- Context Providers (UserContext, MusicContext, ModeContext)
2. Backend API
- Express Server
- Auth Layer (Passport + Google OAuth, JWT issuance)
- Rate-Limit & Signing Middleware
- Controllers: authController, userController, recordController
3. Database
- Users Table/Collection (profiles, OAuth IDs)
- Records Table/Collection (user scores, timestamps)
4. External Services
- Google OAuth
- (Optional) Cloud Hosting (Vercel)
b. Relationships & Data Flows
- User ➔ Frontend: page requests, static asset fetch.
- Frontend ➔ Backend:
- POST /auth/google → OAuth handshake → JWT token
- GET/POST /data/users → fetch/update user profile
- GET/POST /data/records → fetch/submit scores
- Backend ➔ Database: CRUD on users & records
- Backend ➔ Google OAuth: token exchange, profile fetch
- Frontend: context-driven internal data flow (game state ➔ UI components)
c. Architectural Patterns & Design Principles
- Separation of Concerns: UI, business logic, persistence layers
- MVC-style layering on backend, component-driven approach on frontend
- Stateless REST API with JWT authentication
- Use of middleware for cross-cutting concerns (auth, rate limiting)
d. Key Technologies & Frameworks
- Frontend: Next.js (React + SSR/SSG), React Context, TypeScript
- Backend: Node.js, Express, TypeScript, Passport.js, dotenv, rate-limit libraries
- Deployment: Vercel (frontend & potentially backend)

## Diagram (Mermaid)

```mermaid
graph TB
    %% Client
    Browser["User's Browser"]:::external

    %% Frontend Layer
    subgraph "Frontend" 
        direction TB
        NextJs["Next.js React App"]:::frontend
        subgraph "Pages (app Directory)" 
            direction TB
            GamePage["Game Page"]:::frontend
            GameOverPage["GameOver Page"]:::frontend
            LoginPage["Login Page"]:::frontend
            ProfilePage["Profile Page"]:::frontend
            RankPage["Rank Page"]:::frontend
        end
        GameEngine["Game Engine & Logic"]:::frontend
        UIComponents["Game UI Components"]:::frontend
        subgraph "Static Assets" 
            direction TB
            StaticAudio["Audio Assets"]:::frontend
            StaticIcons["Icon Assets"]:::frontend
        end
        subgraph "Context Providers"
            direction TB
            UserContext["UserContext"]:::frontend
            MusicContext["MusicContext"]:::frontend
            NowModeContext["NowModeContext"]:::frontend
        end
    end

    %% Backend Layer
    subgraph "Backend (Express API)"
        direction TB
        subgraph "Entry Points"
            direction TB
            ServerTS["server.ts"]:::backend
            AppTS["app.ts"]:::backend
        end
        subgraph "Config"
            direction TB
            Dotenv["dotenv Config"]:::backend
            PassportCfg["Passport Setup"]:::backend
            GoogleAPICfg["Google API Config"]:::backend
        end
        subgraph "Middlewares"
            direction TB
            AuthMiddleware["Auth Middleware"]:::backend
            RateLimit["RateLimit Middleware"]:::backend
            SignMiddleware["Sign Middleware"]:::backend
        end
        subgraph "Routes"
            direction TB
            AuthRoutes["auth.ts"]:::backend
            DataRoutes["data.ts"]:::backend
            UserRoutes["users.ts"]:::backend
            RecordRoutes["records.ts"]:::backend
        end
        subgraph "Controllers"
            direction TB
            AuthController["Auth Controller"]:::backend
            UserController["User Controller"]:::backend
            RecordController["Record Controller"]:::backend
        end
        subgraph "Utils"
            direction TB
            JWTUtil["jwt.ts"]:::backend
            URLUtil["url.ts"]:::backend
            UserUtil["user.ts"]:::backend
        end
        subgraph "Types"
            direction TB
            UserType["user.ts"]:::backend
            RecordType["record.ts"]:::backend
        end
    end

    %% Database and External
    Database["MongoDB Users & Records"]:::database
    GoogleOAuth["Google OAuth Service"]:::external

    %% Connections
    Browser --> NextJs
    NextJs --> GamePage
    NextJs --> GameOverPage
    NextJs --> LoginPage
    NextJs --> ProfilePage
    NextJs --> RankPage
    NextJs --> GameEngine
    GameEngine --> UIComponents
    NextJs --> StaticAudio
    NextJs --> StaticIcons
    NextJs --> UserContext
    NextJs --> MusicContext
    NextJs --> NowModeContext

    NextJs -->|REST API Calls| ServerTS
    AppTS --> AuthMiddleware
    AppTS --> RateLimit
    AppTS --> SignMiddleware
    AppTS --> AuthRoutes
    AppTS --> DataRoutes
    AuthRoutes --> AuthController
    DataRoutes --> UserRoutes
    DataRoutes --> RecordRoutes
    UserRoutes --> UserController
    RecordRoutes --> RecordController

    AuthController --> JWTUtil
    AuthController --> UserType
    UserController --> UserUtil
    UserController --> UserType
    RecordController --> UserUtil
    RecordController --> RecordType

    ServerTS --> AppTS
    AppTS --> Dotenv
    AppTS --> PassportCfg
    AppTS --> GoogleAPICfg

    AppTS --> Database
    AppTS --> GoogleOAuth

    %% Click Events
    click NextJs "https://github.com/fanyuuu2006/labag-web/tree/main/frontend/"
    click GamePage "https://github.com/fanyuuu2006/labag-web/blob/main/frontend/src/app/Game/page.tsx"
    click GameOverPage "https://github.com/fanyuuu2006/labag-web/blob/main/frontend/src/app/GameOver/page.tsx"
    click LoginPage "https://github.com/fanyuuu2006/labag-web/blob/main/frontend/src/app/Login/page.tsx"
    click ProfilePage "https://github.com/fanyuuu2006/labag-web/blob/main/frontend/src/app/Profile/[UserID]/page.tsx"
    click RankPage "https://github.com/fanyuuu2006/labag-web/blob/main/frontend/src/app/Rank/page.tsx"
    click UIComponents "https://github.com/fanyuuu2006/labag-web/tree/main/frontend/src/components/Game/"
    click GameEngine "https://github.com/fanyuuu2006/labag-web/blob/main/frontend/src/utils/game.ts"
    click StaticAudio "https://github.com/fanyuuu2006/labag-web/tree/main/frontend/public/audio/"
    click StaticIcons "https://github.com/fanyuuu2006/labag-web/tree/main/frontend/public/icons/"
    click UserContext "https://github.com/fanyuuu2006/labag-web/blob/main/frontend/src/context/UserContext.tsx"
    click MusicContext "https://github.com/fanyuuu2006/labag-web/blob/main/frontend/src/context/MusicContext.tsx"
    click NowModeContext "https://github.com/fanyuuu2006/labag-web/blob/main/frontend/src/context/NowModeContext.tsx"
    click ServerTS "https://github.com/fanyuuu2006/labag-web/blob/main/backend/src/server.ts"
    click AppTS "https://github.com/fanyuuu2006/labag-web/blob/main/backend/src/app.ts"
    click PassportCfg "https://github.com/fanyuuu2006/labag-web/blob/main/backend/src/config/passport.ts"
    click GoogleAPICfg "https://github.com/fanyuuu2006/labag-web/blob/main/backend/src/config/googleapi.ts"
    click Dotenv "https://github.com/fanyuuu2006/labag-web/blob/main/backend/src/config/dotenv.ts"
    click AuthController "https://github.com/fanyuuu2006/labag-web/blob/main/backend/src/controllers/authController.ts"
    click UserController "https://github.com/fanyuuu2006/labag-web/blob/main/backend/src/controllers/data/userController.ts"
    click RecordController "https://github.com/fanyuuu2006/labag-web/blob/main/backend/src/controllers/data/recordController.ts"
    click AuthRoutes "https://github.com/fanyuuu2006/labag-web/blob/main/backend/src/routes/auth.ts"
    click DataRoutes "https://github.com/fanyuuu2006/labag-web/blob/main/backend/src/routes/data.ts"
    click UserRoutes "https://github.com/fanyuuu2006/labag-web/blob/main/backend/src/routes/data/users.ts"
    click RecordRoutes "https://github.com/fanyuuu2006/labag-web/blob/main/backend/src/routes/data/records.ts"
    click AuthMiddleware "https://github.com/fanyuuu2006/labag-web/blob/main/backend/src/middlewares/authMiddleware.ts"
    click RateLimit "https://github.com/fanyuuu2006/labag-web/blob/main/backend/src/middlewares/rateLimitMiddleware.ts"
    click SignMiddleware "https://github.com/fanyuuu2006/labag-web/blob/main/backend/src/middlewares/signMiddleware.ts"
    click JWTUtil "https://github.com/fanyuuu2006/labag-web/blob/main/backend/src/utils/jwt.ts"
    click URLUtil "https://github.com/fanyuuu2006/labag-web/blob/main/backend/src/utils/url.ts"
    click UserUtil "https://github.com/fanyuuu2006/labag-web/blob/main/backend/src/utils/user.ts"
    click UserType "https://github.com/fanyuuu2006/labag-web/blob/main/backend/src/types/user.ts"
    click RecordType "https://github.com/fanyuuu2006/labag-web/blob/main/backend/src/types/record.ts"

    %% Styles
    classDef frontend fill:#bbdefb,stroke:#0d47a1,color:#000
    classDef backend fill:#c8e6c9,stroke:#1b5e20,color:#000
    classDef database fill:#ffe0b2,stroke:#e65100,color:#000
    classDef external fill:#eeeeee,stroke:#757575,color:#000
```
