# gsmanagerxz/gameservermanager architecture

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

- Interactive diagram: https://gitdiagram.com/gsmanagerxz/gameservermanager
- Repository: https://github.com/gsmanagerxz/gameservermanager

## Overview

1. **Repository shape**
   - This is a monorepo with two primary runtime boundaries: `client/` for the browser UI and `server/` for the Node.js backend.  
   - The backend owns all privileged operations: filesystem access, process/PTY control, SteamCMD/game deployment, scheduling, and persistent data management.

2. **Client-side application**
   - The frontend is a React 18 + TypeScript app built with Vite, Ant Design, TailwindCSS, Zustand, Monaco Editor, Xterm.js, and Socket.IO client.
   - `src/pages/` defines the main screens: home, login, file manager, instance manager, terminal, plugins, settings, deployment, scheduled tasks, environment management, and a developer page.
   - `src/components/` contains reusable UI and modal/dialog workflows for destructive actions, file editing conflicts, upload/compress confirmation, onboarding, network warnings, and system alerts.

3. **Client state and live updates**
   - Zustand stores in `src/stores/` hold cross-page application state such as auth, files, notifications, theme, wallpaper, console logs, network status, onboarding, and system alerts.
   - The client uses a mixed data model: REST-style API utilities for transactional operations and Socket.IO for live terminal output, console logs, notifications, and status refreshes.

4. **Backend application boundary**
   - The server is a TypeScript Node.js + Express app with modular routing under `src/routes/`.
   - `src/index.ts` is the entry point, and middleware such as `src/middleware/auth.ts` enforces authenticated access to protected APIs.
   - The server is the only layer that touches local OS resources directly.

5. **Core backend domain modules**
   - The backend is organized around managers in `src/modules/`, each encapsulating a domain:
     - `auth` for login/JWT/captcha flows
     - `instance` for game instance lifecycle
     - `game` and `gameConfig` for game-specific deployment and config handling
     - `file` and `task` for file watching, uploads, compression, and background operations
     - `terminal` for PTY-backed interactive shells
     - `rcon` for remote console control
     - `scheduler` for timed jobs
     - `system` for system-level monitoring/state
     - `plugin` for plugin lifecycle and API exposure
     - `backup` for backup creation/management
     - `steamcmd` and `environment` for runtime prerequisites and installers

6. **Data and control flow**
   - User actions in the UI typically flow: page/component → client utility/store → backend route → module manager → filesystem/process/network side effect.
   - Real-time flows, such as terminal output or instance status, go through Socket.IO instead of only polling.
   - File uploads and long-running jobs are offloaded to task managers/workers so the UI can observe progress rather than block.

7. **File, upload, and compression subsystem**
   - Large file handling is a major subsystem: `chunkUploadManager`, `chunkUpload.ts`, and related tests indicate resumable/chunked uploads with integrity and preservation concerns.
   - Compression/extraction work is isolated into worker-based logic under `server/src/modules/task/` and guarded by tar/zip security utilities.
   - File watching is handled separately so UI state can reflect external edits or deletions.

8. **Game deployment and configuration management**
   - Game-specific deployment is centralized in `GameManager`, `InstanceManager`, `SteamCMDManager`, and route handlers such as `gameDeployment`, `games`, `minecraft`, and `moreGames`.
   - Configuration is treated as first-class data: `gameConfig` manages visual/config-file templates, with sample YAML configs stored under `server/data/gameconfig/`.
   - This strongly suggests a deployment pipeline: select game/template → install via SteamCMD or game-specific logic → write instance/config files → start/manage the server process.

9. **Terminal, RCON, and system integration**
   - Interactive server control uses a PTY abstraction in `src/utils/ptyManager.ts` and terminal session management modules.
   - Game consoles can also be controlled through RCON, which is exposed as a separate backend concern rather than being mixed into the terminal layer.
   - System utilities and environment managers cover prerequisites like Java, DirectX, VC++ redistributables, package installation, and general host inspection.

10. **Plugin and extension architecture**
   - The repository supports plugins as a runtime extension boundary: `server/data/plugins/` contains plugin packages and documentation, while `pluginApi` and `PluginManager` handle loading and exposure.
   - There is also a dedicated developer module on both client and server sides, suggesting an internal admin/developer surface for inspecting or packaging the system.

11. **Persistent storage layout**
   - Runtime data is concentrated under `server/data/`, including game state, plugin data, RCON state, startup markers, and game configuration templates.
   - This means the backend is not stateless; the filesystem is part of the application model and should be treated as a primary persistence boundary in any diagram.

12. **Operational and packaging layer**
   - Docker files, compose files, and ARM64 scripts show that deployment is containerized and also supports non-x86 environments.
   - GitHub Actions workflows indicate CI for builds and PR checks, while the `scripts/` tree contains platform-specific bootstrapping for ARM64 and packaging.
   - Tests are present for critical utility areas like 7z tooling and chunk uploads, reinforcing that file operations and archive handling are operationally sensitive parts of the system.

Main entry points: [`server/src/routes`](https://github.com/gsmanagerxz/gameservermanager/tree/main/server/src/routes) (Routes), [`client/src/App.tsx`](https://github.com/gsmanagerxz/gameservermanager/blob/main/client/src/App.tsx) (UI shell), [`client/src/utils`](https://github.com/gsmanagerxz/gameservermanager/tree/main/client/src/utils) (API layer), [`server/src/index.ts`](https://github.com/gsmanagerxz/gameservermanager/blob/main/server/src/index.ts) (Server entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_client_app["UI shell<br/>React/Vite app<br/>[App.tsx]"]
  node_client_pages["Pages<br/>screens"]
  node_client_components["UI components<br/>shared views"]
  node_client_stores[("Zustand stores<br/>client state")]
  node_client_api["API layer<br/>REST/Socket.IO client"]
  node_client_developer["Developer module<br/>admin UI"]
end

subgraph group_server["Server"]
  node_server_entry["Server entry<br/>Express bootstrap<br/>[index.ts]"]
  node_server_routes["Routes<br/>HTTP API"]
  node_server_auth["Auth middleware<br/>access control<br/>[auth.ts]"]
  node_server_instance["Instance manager<br/>lifecycle<br/>[InstanceManager.ts]"]
  node_server_game["Game deployment<br/>[GameManager.ts]"]
  node_server_gameconfig["Game config<br/>templates"]
  node_server_file_task["File & tasks<br/>storage/jobs"]
  node_server_terminal["Terminal<br/>PTY sessions<br/>[TerminalManager.ts]"]
  node_server_rcon["RCON<br/>remote console<br/>[RconManager.ts]"]
  node_server_scheduler["Scheduler<br/>timed jobs"]
  node_server_system_env["System & env<br/>host services<br/>[SystemManager.ts]"]
  node_server_plugin["Plugin runtime<br/>extension boundary<br/>[PluginManager.ts]"]
  node_server_data[("Runtime data<br/>filesystem state")]
  node_server_developer["Developer API<br/>admin backend"]
  node_server_ops["Task workers"]
end

subgraph group_ops["Ops"]
  node_ops_ci["CI workflows<br/>GitHub Actions<br/>[workflows]"]
  node_ops_deploy["Deploy scripts<br/>container/ARM64<br/>[docker-compose.yml]"]
end

node_client_app -->|"renders"| node_client_pages
node_client_app -->|"uses"| node_client_components
node_client_app -->|"reads/writes"| node_client_stores
node_client_pages -->|"calls"| node_client_api
node_client_components -->|"binds"| node_client_stores
node_client_api -->|"requests"| node_server_routes
node_client_api -->|"socket connect"| node_server_entry
node_client_developer -->|"uses"| node_client_api
node_server_entry -->|"mounts"| node_server_routes
node_server_routes -->|"protects"| node_server_auth
node_server_routes -->|"orchestrates"| node_server_instance
node_server_routes -->|"deploys"| node_server_game
node_server_routes -->|"handles"| node_server_file_task
node_server_routes -->|"opens"| node_server_terminal
node_server_routes -->|"controls"| node_server_rcon
node_server_routes -->|"schedules"| node_server_scheduler
node_server_routes -->|"inspects"| node_server_system_env
node_server_routes -->|"exposes"| node_server_plugin
node_server_routes -->|"serves"| node_server_developer
node_server_game -->|"applies"| node_server_gameconfig
node_server_game -->|"depends on"| node_server_system_env
node_server_file_task -->|"offloads"| node_server_ops
node_server_ops -->|"reads/writes"| node_server_data
node_server_plugin -->|"loads"| node_server_data
node_server_terminal -->|"persists"| node_server_data
node_server_rcon -->|"persists"| node_server_data
node_ops_ci -->|"builds"| node_server_entry
node_ops_ci -->|"builds"| node_client_app
node_ops_deploy -->|"packages"| node_server_entry
node_ops_deploy -->|"packages"| node_client_app

click node_client_app "https://github.com/gsmanagerxz/gameservermanager/blob/main/client/src/App.tsx"
click node_client_pages "https://github.com/gsmanagerxz/gameservermanager/tree/main/client/src/pages"
click node_client_components "https://github.com/gsmanagerxz/gameservermanager/tree/main/client/src/components"
click node_client_stores "https://github.com/gsmanagerxz/gameservermanager/tree/main/client/src/stores"
click node_client_api "https://github.com/gsmanagerxz/gameservermanager/tree/main/client/src/utils"
click node_client_developer "https://github.com/gsmanagerxz/gameservermanager/tree/main/client/src/modules/developer"
click node_server_entry "https://github.com/gsmanagerxz/gameservermanager/blob/main/server/src/index.ts"
click node_server_routes "https://github.com/gsmanagerxz/gameservermanager/tree/main/server/src/routes"
click node_server_auth "https://github.com/gsmanagerxz/gameservermanager/blob/main/server/src/middleware/auth.ts"
click node_server_instance "https://github.com/gsmanagerxz/gameservermanager/blob/main/server/src/modules/instance/InstanceManager.ts"
click node_server_game "https://github.com/gsmanagerxz/gameservermanager/blob/main/server/src/modules/game/GameManager.ts"
click node_server_gameconfig "https://github.com/gsmanagerxz/gameservermanager/blob/main/server/src/modules/gameConfig/GameConfigManager.ts"
click node_server_file_task "https://github.com/gsmanagerxz/gameservermanager/blob/main/server/src/modules/file/FileWatchManager.ts"
click node_server_terminal "https://github.com/gsmanagerxz/gameservermanager/blob/main/server/src/modules/terminal/TerminalManager.ts"
click node_server_rcon "https://github.com/gsmanagerxz/gameservermanager/blob/main/server/src/modules/rcon/RconManager.ts"
click node_server_scheduler "https://github.com/gsmanagerxz/gameservermanager/blob/main/server/src/modules/scheduler/SchedulerManager.ts"
click node_server_system_env "https://github.com/gsmanagerxz/gameservermanager/blob/main/server/src/modules/system/SystemManager.ts"
click node_server_plugin "https://github.com/gsmanagerxz/gameservermanager/blob/main/server/src/modules/plugin/PluginManager.ts"
click node_server_data "https://github.com/gsmanagerxz/gameservermanager/tree/main/server/data"
click node_server_developer "https://github.com/gsmanagerxz/gameservermanager/tree/main/server/src/modules/developer"
click node_server_ops "https://github.com/gsmanagerxz/gameservermanager/tree/main/server/src/modules/task"
click node_ops_ci "https://github.com/gsmanagerxz/gameservermanager/blob/main/.github/workflows"
click node_ops_deploy "https://github.com/gsmanagerxz/gameservermanager/blob/main/docker-compose.yml"

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_client_app,node_client_pages,node_client_components,node_client_stores,node_client_api,node_client_developer toneBlue
class node_server_entry,node_server_routes,node_server_auth,node_server_instance,node_server_game,node_server_gameconfig,node_server_file_task,node_server_terminal,node_server_rcon,node_server_scheduler,node_server_system_env,node_server_plugin,node_server_data,node_server_developer,node_server_ops toneAmber
class node_ops_ci,node_ops_deploy toneMint
```

## Components

### Client

Browser UI runtime and shared state

- [UI shell](https://github.com/gsmanagerxz/gameservermanager/blob/main/client/src/App.tsx): React/Vite app · Application bootstrap and route-level composition for the browser client · `client/src/App.tsx`
- [Pages](https://github.com/gsmanagerxz/gameservermanager/tree/main/client/src/pages): screens · Main screens for login, files, instances, terminal, plugins, deployment, settings, and admin surfaces · `client/src/pages`
- [UI components](https://github.com/gsmanagerxz/gameservermanager/tree/main/client/src/components): shared views · Reusable dialogs, modals, layout pieces, warnings, editors, and terminal widgets · `client/src/components`
- [Zustand stores](https://github.com/gsmanagerxz/gameservermanager/tree/main/client/src/stores): client state · Cross-page state for auth, files, notifications, theme, wallpaper, console logs, network, onboarding, and alerts · `client/src/stores`
- [API layer](https://github.com/gsmanagerxz/gameservermanager/tree/main/client/src/utils): REST/Socket.IO client · Client utilities for transactional API calls, file operations, and real-time Socket.IO events · `client/src/utils`
- [Developer module](https://github.com/gsmanagerxz/gameservermanager/tree/main/client/src/modules/developer): admin UI · Dedicated internal developer/admin surface with auth, tools, and packaging flows · `client/src/modules/developer`

### Server

Node.js backend and privileged operations

- [Server entry](https://github.com/gsmanagerxz/gameservermanager/blob/main/server/src/index.ts): Express bootstrap · Backend startup and top-level application wiring · `server/src/index.ts`
- [Routes](https://github.com/gsmanagerxz/gameservermanager/tree/main/server/src/routes): HTTP API · Modular route layer for auth, files, instances, deployment, plugins, tasks, system, terminal, and more · `server/src/routes`
- [Auth middleware](https://github.com/gsmanagerxz/gameservermanager/blob/main/server/src/middleware/auth.ts): access control · Authenticated access gate for protected backend APIs · `server/src/middleware/auth.ts`
- [Instance manager](https://github.com/gsmanagerxz/gameservermanager/blob/main/server/src/modules/instance/InstanceManager.ts): lifecycle · Game instance lifecycle and orchestration · `server/src/modules/instance/InstanceManager.ts`
- [Game deployment](https://github.com/gsmanagerxz/gameservermanager/blob/main/server/src/modules/game/GameManager.ts): deployment · Game-specific install and deploy logic, including game adapters · `server/src/modules/game/GameManager.ts`
- [Game config](https://github.com/gsmanagerxz/gameservermanager/blob/main/server/src/modules/gameConfig/GameConfigManager.ts): templates · Visual and file-based game configuration templates and persistence · `server/src/modules/gameConfig/GameConfigManager.ts`
- [File & tasks](https://github.com/gsmanagerxz/gameservermanager/blob/main/server/src/modules/file/FileWatchManager.ts): storage/jobs · File watching, chunked uploads, compression, extraction, and background file operations · `server/src/modules/file/FileWatchManager.ts`
- [Terminal](https://github.com/gsmanagerxz/gameservermanager/blob/main/server/src/modules/terminal/TerminalManager.ts): PTY sessions · PTY-backed interactive shell sessions and terminal control · `server/src/modules/terminal/TerminalManager.ts`
- [RCON](https://github.com/gsmanagerxz/gameservermanager/blob/main/server/src/modules/rcon/RconManager.ts): remote console · Remote game console control separate from PTY terminal sessions · `server/src/modules/rcon/RconManager.ts`
- [Scheduler](https://github.com/gsmanagerxz/gameservermanager/blob/main/server/src/modules/scheduler/SchedulerManager.ts): timed jobs · Timed and background job orchestration · `server/src/modules/scheduler/SchedulerManager.ts`
- [System & env](https://github.com/gsmanagerxz/gameservermanager/blob/main/server/src/modules/system/SystemManager.ts): host services · Host monitoring plus prerequisite and installer management such as Java, DirectX, VC++ redistributables, and packages · `server/src/modules/system/SystemManager.ts`
- [Plugin runtime](https://github.com/gsmanagerxz/gameservermanager/blob/main/server/src/modules/plugin/PluginManager.ts): extension boundary · Plugin loading, plugin API exposure, and runtime extension management · `server/src/modules/plugin/PluginManager.ts`
- [Runtime data](https://github.com/gsmanagerxz/gameservermanager/tree/main/server/data): filesystem state · Persistent application data under server/data including game state, plugins, RCON state, startup markers, and config templates · `server/data`
- [Developer API](https://github.com/gsmanagerxz/gameservermanager/tree/main/server/src/modules/developer): admin backend · Developer-specific backend controller, routes, middleware, and service layer · `server/src/modules/developer`
- [Task workers](https://github.com/gsmanagerxz/gameservermanager/tree/main/server/src/modules/task): workers · Worker-based compression and file operation execution for long-running jobs · `server/src/modules/task`

### Ops

Packaging, deployment, and CI

- [CI workflows](https://github.com/gsmanagerxz/gameservermanager/blob/main/.github/workflows): GitHub Actions · Build and PR validation workflows · `.github/workflows`
- [Deploy scripts](https://github.com/gsmanagerxz/gameservermanager/blob/main/docker-compose.yml): container/ARM64 · Docker, compose, ARM64 bootstrap, and packaging scripts · `docker-compose.yml`

## Connections

- UI shell → Pages: renders · UI shell composes the page-level application screens
- UI shell → UI components: uses · Shared UI building blocks and dialogs are assembled into the app
- UI shell → Zustand stores: reads/writes · Application state is coordinated through Zustand stores
- Pages → API layer: calls · Pages trigger REST actions and subscribe to live updates through the client API layer
- UI components → Zustand stores: binds · Global modals, banners, and widgets reflect store-backed state
- API layer → Routes: requests · Client utilities communicate with backend route handlers
- API layer → Server entry: socket connect · Realtime features connect to the server runtime for live events
- Developer module → API layer: uses · Developer UI talks to dedicated developer endpoints
- Server entry → Routes: mounts · Top-level Express bootstrap installs the route modules
- Routes → Auth middleware: protects · Protected APIs are gated by authentication middleware
- Routes → Instance manager: orchestrates · Instance-related endpoints delegate lifecycle control to the instance manager
- Routes → Game deployment: deploys · Deployment and game selection routes use game manager logic
- Routes → File & tasks: handles · File and task routes offload to file-watch and background job handling
- Routes → Terminal: opens · Terminal routes manage interactive PTY sessions
- Routes → RCON: controls · RCON routes expose remote console control
- Routes → Scheduler: schedules · Scheduled task routes delegate to the scheduler manager
- Routes → System & env: inspects · System and environment routes query host state and prerequisites
- Routes → Plugin runtime: exposes · Plugin and plugin API routes delegate to the plugin runtime
- Routes → Developer API: serves · Developer routes reach the backend developer module
- Game deployment → Game config: applies · Game deployment uses configuration templates and saved config data
- Game deployment → System & env: depends on · Game installation and runtime preparation require host tooling and prerequisites
- File & tasks → Task workers: offloads · Long-running archive and file operations run in workers
- Task workers → Runtime data: reads/writes · Workers and managers persist runtime files and state under server/data
- Plugin runtime → Runtime data: loads · Plugin packages and metadata are stored in the persistent data tree
- Terminal → Runtime data: persists · Terminal and startup-related state is stored on disk when needed
- RCON → Runtime data: persists · RCON state and credentials/data are stored under the runtime data tree
- CI workflows → Server entry: builds · CI validates the server and repo build pipelines
- CI workflows → UI shell: builds · CI validates the client build pipeline
- Deploy scripts → Server entry: packages · Docker and ARM64 scripts package and launch the backend
- Deploy scripts → UI shell: packages · Deployment scripts include the browser client build and runtime