How fanyuuu2006/labag-web works
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)