languard-servers-manager/docs/ANALYSIS.md

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