docs: add arma-server-web-admin analysis reference docs

Brings in ANALYSIS.md, HOW_IT_WORKS.md, and CHERRY_PICK.md generated from deep analysis of the arma-server-web-admin benchmark project. These docs inform the Arma 3 UX enhancement plan (.claude/plan/arma3-ux-enhancement.md) and provide context for implementing agents without needing to re-read the source project.
2026-04-17 14:55:59 +07:00
parent 5d009d50d1
commit 4ba199dd62
3 changed files with 716 additions and 0 deletions
--- a/docs/ANALYSIS.md
+++ b/docs/ANALYSIS.md
@@ -0,0 +1,155 @@
+# Arma Server Web Admin — Full Analysis
+
+## Project Overview
+
+**Arma Server Web Admin** is a Node.js/Express web application providing a browser-based administration panel for managing one or more Arma game server instances (Arma 1/2/2OA/3, CWA, OFP).
+
+It consolidates all day-to-day server management tasks into a single UI:
+- Launch and stop game server processes
+- Monitor live player counts, current mission, and server state
+- Upload and rotate missions (.pbo files, including Steam Workshop)
+- Discover and assign mods per server
+- Browse and download server log files
+- Configure every server setting (ports, passwords, difficulty, mods, MOTD, etc.)
+- Deploy headless clients automatically alongside the server process
+
+---
+
+## Technology Stack
+
+| Layer | Technology |
+|-------|-----------|
+| HTTP server | Node.js + Express.js |
+| Real-time | Socket.IO 2.x |
+| Game process | arma-server (Node wrapper) |
+| Game query | Gamedig |
+| Steam Workshop | steam-workshop |
+| File helpers | fs.extra, glob, multer |
+| Async control | async 2.x |
+| Frontend SPA | Backbone.js + Marionette.js |
+| Templating | Underscore.js |
+| UI framework | Bootstrap 3 |
+| Build | Webpack v1 |
+| Auth | express-basic-auth (optional) |
+
+---
+
+## Directory Structure
+
+```
+arma-server-web-admin/
+├── app.js                   # Entry point: Express + Socket.IO + route wiring
+├── config.js.example        # All configuration options with defaults
+├── config.docker.js         # Docker-specific config overrides
+├── webpack.config.js        # Frontend bundling
+├── package.json
+│
+├── lib/                     # Backend business logic
+│   ├── manager.js           # Multi-server lifecycle manager (EventEmitter)
+│   ├── server.js            # Single server wrapper (start/stop/query/persist)
+│   ├── missions.js          # Mission file discovery, upload, Workshop download
+│   ├── logs.js              # Log file discovery, cleanup, platform paths
+│   ├── settings.js          # Config accessor (public subset for client)
+│   ├── setup-basic-auth.js  # Optional HTTP Basic Auth middleware
+│   └── mods/
+│       ├── index.js         # Mod discovery + parallel metadata resolution
+│       ├── folderSize.js    # Recursive folder size calculator
+│       ├── modFile.js       # Parses mod.cpp for display name
+│       └── steamMeta.js     # Parses meta.cpp for Steam Workshop ID
+│
+├── routes/                  # Express routers (each returns a router factory)
+│   ├── servers.js           # /api/servers/* (CRUD + start/stop)
+│   ├── missions.js          # /api/missions/* (list/upload/download/delete)
+│   ├── mods.js              # /api/mods/* (list/delete)
+│   ├── logs.js              # /api/logs/* (list/view/download/delete)
+│   └── settings.js          # /api/settings (GET public settings)
+│
+└── public/                  # Single-page frontend (built by Webpack)
+    ├── index.html
+    ├── css/styles.css
+    └── js/
+        ├── app.js           # RequireJS bootstrap + Socket.IO init
+        └── app/
+            ├── router.js    # Backbone Router (5 routes)
+            ├── models/      # Backbone Models
+            ├── collections/ # Backbone Collections
+            └── views/       # Marionette views
+```
+
+---
+
+## Feature Inventory
+
+### Server Lifecycle
+- Create / edit / delete server definitions persisted to `servers.json`
+- Start / stop server processes (Windows `.exe`, Linux binary, Wine)
+- Auto-start servers on application launch (`auto_start` flag)
+- Process ID tracking
+- 5-second polling via Gamedig for live state (players, mission, status)
+
+### Configuration
+- Title, port, max players
+- Player password, admin password
+- Message of the Day (MOTD, multi-line)
+- BattleEye, VoN, signature verification, file patching, persistent mode
+- Difficulty override (Recruit / Regular / Veteran / Custom)
+- Per-server additional `server.cfg` text (freeform)
+- Per-server startup parameters (e.g. `-limitFPS=100`)
+- Per-server mod selection
+- Per-server mission rotation with per-mission difficulty
+
+### Mission Management
+- List `.pbo` files from `mpmissions/`
+- Upload up to 64 `.pbo` files at once (multipart)
+- Download from Steam Workshop by ID
+- Download mission files to browser
+- Delete mission files
+- View name, world name, file size, timestamps
+
+### Mod Management
+- Auto-discover mods via glob patterns (`@*`, `csla`, `ef`, etc.)
+- Extract display name from `mod.cpp`
+- Extract Steam Workshop ID from `meta.cpp`
+- Calculate folder sizes recursively (symlink-aware)
+- Delete mod folders
+- Assign mods per server (split-pane UI)
+
+### Log Management
+- Discover `.rpt` log files from platform-appropriate paths:
+  - **Windows:** `AppData\Local\[Game]\`
+  - **Linux:** `[game_path]/logs/`
+  - **Wine:** `.wine/drive_c/users/.../Application Data/[Game]/`
+- View log contents inline
+- Download logs
+- Delete logs
+- Auto-cleanup: retain only the 20 newest log files
+
+### Headless Clients
+- Configure number of headless clients per server
+- Auto-launch when server starts, auto-kill when server stops
+- Connect to `127.0.0.1:[server_port]`
+
+### Real-Time Updates
+- Socket.IO push for: server state, mission list, mod list, settings
+- All connected clients receive updates simultaneously
+
+### Authentication
+- Optional HTTP Basic Auth (single or multiple users)
+- Credentials in `config.js`; no database
+
+### Platform Support
+- Windows, Linux, Wine, Docker
+
+---
+
+## Data Persistence
+
+| Data | Storage |
+|------|---------|
+| Server definitions | `servers.json` (plain JSON, in-memory on load) |
+| Mission files | `[game_path]/mpmissions/` (filesystem) |
+| Mod files | `[game_path]/[mod_dirs]/` (filesystem) |
+| Log files | Platform-specific log directory |
+| App config | `config.js` (static, not written at runtime) |
+
+No database. All runtime state lives in the `Manager` class and is flushed to `servers.json` on every mutation.