# nabrothers/gml architecture

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

- Interactive diagram: https://gitdiagram.com/nabrothers/gml
- Repository: https://github.com/nabrothers/gml

## Overview

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: [`api/utils`](https://github.com/nabrothers/gml/tree/main/api/utils) (Utils), [`api/routes`](https://github.com/nabrothers/gml/tree/main/api/routes) (Routes), [`src/App.tsx`](https://github.com/nabrothers/gml/blob/main/src/App.tsx) (App), [`src/pages`](https://github.com/nabrothers/gml/tree/main/src/pages) (Pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend SPA"]
  node_src_main["main.tsx<br/>entrypoint<br/>[main.tsx]"]
  node_src_app["App<br/>shell<br/>[App.tsx]"]
  node_src_api["API client<br/>network boundary<br/>[api.ts]"]
  node_src_pages["Pages<br/>routes"]
  node_src_components["Components<br/>ui domain"]
  node_src_stores["Stores<br/>client state"]
  node_src_data["Reference data<br/>static content"]
end

subgraph group_backend["API Server"]
  node_api_index["index.ts<br/>server entry<br/>[index.ts]"]
  node_api_app["app.ts<br/>server composition<br/>[app.ts]"]
  node_api_routes["Routes<br/>domain endpoints"]
  node_api_utils["Utils<br/>services"]
  node_api_upload["Upload mw<br/>middleware<br/>[upload.ts]"]
end

subgraph group_domain["Domain Data"]
  node_shared_types["Types<br/>shared contract<br/>[types.ts]"]
  node_config_files["Config files<br/>rules data"]
end

subgraph group_storage["Storage"]
  node_db[("Database<br/>persistence<br/>[database.ts]")]
  node_gacha_db[("Gacha DB<br/>persistence<br/>[gachaDatabase.ts]")]
  node_file_storage[("File storage<br/>asset store<br/>[fileStorage.ts]")]
  node_points_cache(("Points cache<br/>[pointsCache.ts]"))
end

node_src_main -->|"mounts"| node_src_app
node_src_app -->|"renders"| node_src_pages
node_src_app -->|"composes"| node_src_components
node_src_app -->|"reads state"| node_src_stores
node_src_pages -->|"calls"| node_src_api
node_src_pages -->|"shows"| node_src_data
node_src_components -->|"renders"| node_src_data
node_src_api -->|"requests"| node_api_routes
node_api_index -->|"starts"| node_api_app
node_api_app -->|"mounts"| node_api_routes
node_api_routes -->|"uses"| node_api_utils
node_api_routes -->|"accepts files"| node_api_upload
node_api_utils -->|"persists"| node_db
node_api_utils -->|"persists"| node_gacha_db
node_api_utils -->|"stores files"| node_file_storage
node_api_utils -->|"caches"| node_points_cache
node_api_utils -->|"loads"| node_config_files
node_api_routes -.->|"shares models"| node_shared_types
node_src_stores -.->|"shares models"| node_shared_types

click node_src_main "https://github.com/nabrothers/gml/blob/main/src/main.tsx"
click node_src_app "https://github.com/nabrothers/gml/blob/main/src/App.tsx"
click node_src_api "https://github.com/nabrothers/gml/blob/main/src/lib/api.ts"
click node_src_pages "https://github.com/nabrothers/gml/tree/main/src/pages"
click node_src_components "https://github.com/nabrothers/gml/tree/main/src/components"
click node_src_stores "https://github.com/nabrothers/gml/tree/main/src/stores"
click node_src_data "https://github.com/nabrothers/gml/tree/main/src/data"
click node_api_index "https://github.com/nabrothers/gml/blob/main/api/index.ts"
click node_api_app "https://github.com/nabrothers/gml/blob/main/api/app.ts"
click node_api_routes "https://github.com/nabrothers/gml/tree/main/api/routes"
click node_api_utils "https://github.com/nabrothers/gml/tree/main/api/utils"
click node_api_upload "https://github.com/nabrothers/gml/blob/main/api/middleware/upload.ts"
click node_shared_types "https://github.com/nabrothers/gml/blob/main/shared/types.ts"
click node_config_files "https://github.com/nabrothers/gml/tree/main/config"
click node_db "https://github.com/nabrothers/gml/blob/main/api/utils/database.ts"
click node_gacha_db "https://github.com/nabrothers/gml/blob/main/api/utils/gachaDatabase.ts"
click node_file_storage "https://github.com/nabrothers/gml/blob/main/api/utils/fileStorage.ts"
click node_points_cache "https://github.com/nabrothers/gml/blob/main/api/utils/pointsCache.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_src_main,node_src_app,node_src_api,node_src_pages,node_src_components,node_src_stores,node_src_data toneBlue
class node_api_index,node_api_app,node_api_routes,node_api_utils,node_api_upload toneAmber
class node_shared_types,node_config_files toneMint
class node_db,node_gacha_db,node_file_storage,node_points_cache toneRose
```

## Components

### Frontend SPA

React/Vite client, pages, components, and local state.

- [main.tsx](https://github.com/nabrothers/gml/blob/main/src/main.tsx): entrypoint · Client bootstraps the SPA. · `src/main.tsx`
- [App](https://github.com/nabrothers/gml/blob/main/src/App.tsx): shell · Top-level app composition and routing. · `src/App.tsx`
- [API client](https://github.com/nabrothers/gml/blob/main/src/lib/api.ts): network boundary · Frontend request layer to the backend. · `src/lib/api.ts`
- [Pages](https://github.com/nabrothers/gml/tree/main/src/pages): routes · User and admin screens for gameplay, accounts, and configuration. · `src/pages`
- [Components](https://github.com/nabrothers/gml/tree/main/src/components): ui domain · Reusable Mahjong, ranking, and admin widgets. · `src/components`
- [Stores](https://github.com/nabrothers/gml/tree/main/src/stores): client state · Global auth, game, and user state. · `src/stores`
- [Reference data](https://github.com/nabrothers/gml/tree/main/src/data): static content · Frontend-facing quotes and yaku reference data. · `src/data`

### API Server

Node/TypeScript server routes and runtime bootstrap.

- [index.ts](https://github.com/nabrothers/gml/blob/main/api/index.ts): server entry · Server startup entrypoint. · `api/index.ts`
- [app.ts](https://github.com/nabrothers/gml/blob/main/api/app.ts): server composition · Composes middleware and API routes. · `api/app.ts`
- [Routes](https://github.com/nabrothers/gml/tree/main/api/routes): domain endpoints · Auth, users, games, ranking, gacha, items, and config endpoints. · `api/routes`
- [Utils](https://github.com/nabrothers/gml/tree/main/api/utils): services · Business logic, config managers, database access, cache, and storage helpers. · `api/utils`
- [Upload mw](https://github.com/nabrothers/gml/blob/main/api/middleware/upload.ts): middleware · Handles file upload ingestion. · `api/middleware/upload.ts`

### Domain Data

Shared models, config files, and runtime rule loaders.

- [Types](https://github.com/nabrothers/gml/blob/main/shared/types.ts): shared contract · Shared frontend/backend type definitions. · `shared/types.ts`
- [Config files](https://github.com/nabrothers/gml/tree/main/config): rules data · Editable game, gacha, rank, item, and achievement rules. · `config`

### Storage

Database, caches, and file upload persistence.

- [Database](https://github.com/nabrothers/gml/blob/main/api/utils/database.ts): persistence · Primary server-side persistent store. · `api/utils/database.ts`
- [Gacha DB](https://github.com/nabrothers/gml/blob/main/api/utils/gachaDatabase.ts): persistence · Specialized storage for gacha domain state. · `api/utils/gachaDatabase.ts`
- [File storage](https://github.com/nabrothers/gml/blob/main/api/utils/fileStorage.ts): asset store · Stores uploaded or generated files. · `api/utils/fileStorage.ts`
- [Points cache](https://github.com/nabrothers/gml/blob/main/api/utils/pointsCache.ts): cache · In-memory cache for ranking/points calculations. · `api/utils/pointsCache.ts`

## Connections

- 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.
