How nabrothers/gml works
1. Overall shape
This is a two-part application: a React + TypeScript + Vite frontend in src/ and a Node/TypeScript API backend in api/. The project is organized around a Mahjong/gacha/ranking product with an admin surface, user accounts, game-related analytics, and configurable domain rules.
2. Frontend delivery boundary
The frontend is a single-page app bootstrapped from src/main.tsx and src/App.tsx. Vite handles bundling and local dev, while index.html is the app shell. The frontend talks to the backend through src/lib/api.ts, which is the main network boundary for all server interaction.
3. Page-level feature partitions
The user-facing UI is split into route-like pages under src/pages/: Home, Login, Profile, Ranking, Collection, Gacha, MatchHistory, Scoring, YakuGuide, PaiLi, Settings, plus admin pages such as Admin, AdminConfig, AdminGacha, and UserManagement. This suggests the UI is not just informational; it includes account management, gameplay support, collection/gacha actions, and administrative configuration.
4. Client state management
Global state is centralized in src/stores/ with separate stores for authStore, gameStore, and userStore. That implies authentication/session data, user profile/domain data, and game state are managed independently and shared across pages/components rather than passed deeply through props.
5. Reusable UI and domain widgets
src/components/ contains a large set of domain-specific components: Mahjong tiles/hands, scoring and efficiency calculators, ranking charts/editors, achievement badges, item images, avatars, and decorative/interaction components. The presence of components like RankCurveEditor, TingPaiAnalyzer, YakuGuideTab, and PointsChart indicates the UI includes both gameplay education tools and admin visualization/editing surfaces.
6. Domain data in the frontend
Static/reference content lives in src/data/, including mahjongQuotes.ts and yakuData.ts. Frontend-only derived helpers such as src/utils/rankConfigs.ts likely mirror server-side ranking rules so the UI can preview or render them consistently.
7. Backend API surface
The backend is split into route modules under api/routes/: auth, users, games, ranking, gacha, items, config, and gachaConfig. This is a strong signal that the server is organized by domain capability rather than by technical layer, with each route handling a separate business area.
8. Backend composition and server entry
api/index.ts, api/app.ts, and api/server.ts form the server bootstrap path. app.ts is likely where middleware and routes are composed, while server.ts/index.ts handle startup concerns. This separation usually indicates a reusable app instance for both local development and deployment entrypoints.
9. Persistence and domain engines
The api/utils/ folder contains the business/data layer: database.ts, gachaDatabase.ts, fileStorage.ts, pointsCache.ts, and several config managers. This points to a hybrid backend where some state is persisted in a database, some configuration is file-backed, and some computed data is cached in memory for performance.
10. Config-driven gameplay and ranking
The config/ directory contains editable domain rules: achievements.conf, gacha.conf, gachaPools.conf, game.conf, items.conf, and ranks.conf. The server-side managers (achievementEngine.ts, configManager.ts, gachaConfigManager.ts, itemConfigManager.ts, poolConfigManager.ts) likely load these files and expose them through admin/config endpoints, making game balance and progression rules data-driven rather than hardcoded.
11. File upload and asset storage
api/middleware/upload.ts and api/utils/fileStorage.ts indicate support for uploaded assets or user-provided files. This is probably tied to admin-managed content such as item images, user avatars, or other media referenced by the frontend components like Avatar and ItemImage.
12. Authentication and user lifecycle
The auth and users routes, together with src/stores/authStore.ts and the Login, Profile, and UserManagement pages, define the identity boundary. The frontend appears to maintain login state locally while the backend owns credential/session validation and user record management.
13. Ranking, points, and match/game flows
The ranking and games routes, plus frontend components like PointsDisplay, CurveChart, RankPreview, and RankManagement, suggest a flow where gameplay or match records produce points/rank outcomes that are stored server-side and visualized client-side. The pointsCache.ts utility implies ranking/points calculations are performance-sensitive.
14. Deployment and build tooling
The repo is set up for modern TypeScript builds with Vite, Tailwind/PostCSS, ESLint, and TypeScript config files. vercel.json and .vercelignore suggest the frontend and possibly serverless API are deployed on Vercel, while build.sh and build.bat provide cross-platform build automation.
15. Architecture diagram summary
A good diagram would show:
- a browser SPA layer with routes/pages/components/stores,
- an API server layer with domain route modules,
- a config/data layer backed by .conf files and utility managers,
- a persistence/storage layer for database state and uploaded files,
- and a shared types contract in shared/types.ts that links frontend and backend models.
Main entry points: utils Utils · routes Routes · App.tsx App · pages Pages
Components 18
Frontend SPA
React/Vite client, pages, components, and local state.
- main.tsx · Client bootstraps the SPA.
src/main.tsx - App · Top-level app composition and routing.
src/App.tsx - API client · Frontend request layer to the backend.
src/lib/api.ts - Pages · User and admin screens for gameplay, accounts, and configuration.
src/pages - Components · Reusable Mahjong, ranking, and admin widgets.
src/components - Stores · Global auth, game, and user state.
src/stores - Reference data · Frontend-facing quotes and yaku reference data.
src/data
API Server
Node/TypeScript server routes and runtime bootstrap.
- index.ts · Server startup entrypoint.
api/index.ts - app.ts · Composes middleware and API routes.
api/app.ts - Routes · Auth, users, games, ranking, gacha, items, and config endpoints.
api/routes - Utils · Business logic, config managers, database access, cache, and storage helpers.
api/utils - Upload mw · Handles file upload ingestion.
api/middleware/upload.ts
Domain Data
Shared models, config files, and runtime rule loaders.
- Types · Shared frontend/backend type definitions.
shared/types.ts - Config files · Editable game, gacha, rank, item, and achievement rules.
config
Storage
Database, caches, and file upload persistence.
- Database · Primary server-side persistent store.
api/utils/database.ts - Gacha DB · Specialized storage for gacha domain state.
api/utils/gachaDatabase.ts - File storage · Stores uploaded or generated files.
api/utils/fileStorage.ts - Points cache · In-memory cache for ranking/points calculations.
api/utils/pointsCache.ts
Connections 19
- main.tsx → App: mounts · Bootstraps the SPA shell.
- App → Pages: renders · Routes pages into the app shell.
- App → Components: composes · Uses shared UI and domain widgets.
- App → Stores: reads state · Connects pages to global client state.
- Pages → API client: calls · All server interaction flows through the API client.
- Pages → Reference data: shows · Uses local reference content in education screens.
- Components → Reference data: renders · Some widgets are driven by local reference data.
- API client → Routes: requests · Frontend API calls are served by backend routes.
- index.ts → app.ts: starts · Server startup delegates to app composition.
- app.ts → Routes: mounts · Registers domain route modules.
- Routes → Utils: uses · Routes rely on service and persistence helpers.
- Routes → Upload mw: accepts files · Some routes are backed by upload middleware.
- Utils → Database: persists · Primary domain data storage.
- Utils → Gacha DB: persists · Gacha-specific state storage.
- Utils → File storage: stores files · Uploaded assets and generated files.
- Utils → Points cache: caches · Speeds up points and ranking calculations.
- Utils → Config files: loads · Managers read editable game and balance rules.
- Routes → Types: shares models · Backend contracts align with client types.
- Stores → Types: shares models · Client state mirrors shared domain models.