languard-servers-manager/ARCHITECTURE.md

Languard Servers Manager — System Architecture

Overview

Languard is a web-based management panel for Arma 3 dedicated servers. It provides a Python backend that manages one or more arma3server_x64.exe processes, exposes a REST + WebSocket API to a React frontend, and persists all state in SQLite.

---

Technology Stack

Layer	Technology	Rationale
Backend framework	FastAPI (Python 3.11+)	Async-native, built-in WebSocket, OpenAPI docs auto-generated
Database	SQLite via SQLAlchemy (sync)	Zero-config, file-based, sufficient for single-host server manager; all access is synchronous (WAL mode for concurrent reads)
Process management	subprocess + threading	Wrap arma3server.exe, watch stdout/stderr, check exit codes; cwd set to server instance dir for relative paths; on Windows terminate() is a hard kill (no SIGTERM)
Real-time comms	WebSocket (FastAPI)	Push log lines, player lists, server status to React
RCon client	Custom UDP client	BattlEye RCon protocol for in-game admin commands
Config generation	Python structured builder	Generate server.cfg, basic.cfg, server.Arma3Profile with proper escaping (no f-string injection)
Scheduling	APScheduler (BackgroundScheduler)	Auto-restart, mission rotation timers, log/metrics cleanup (sync DB ops → BackgroundScheduler, not AsyncIOScheduler)
Auth	JWT (python-jose) + bcrypt	Secure the API; React stores token in localStorage
Frontend	React + TypeScript (external repo)	Connects to this backend's API

---

High-Level Architecture

┌─────────────────────────────────────────────────────────────┐
│                        React Frontend                        │
│   Server List │ Server Detail │ Logs │ Players │ Config UI  │
└────────────────────────┬────────────────────────────────────┘
                         │  HTTP REST + WebSocket
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                    FastAPI Application                        │
│                                                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  │
│  │  Auth Router │  │ Server Router│  │  Config Router   │  │
│  └──────────────┘  └──────────────┘  └──────────────────┘  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  │
│  │Mission Router│  │  Mod Router  │  │  WS Router       │  │
│  └──────────────┘  └──────────────┘  └──────────────────┘  │
│                                                              │
│  ┌─────────────────────────────────────────────────────┐   │
│  │                  Service Layer                        │   │
│  │  ServerService │ ConfigService │ RConService         │   │
│  │  LogService    │ MetricsService│ MissionService      │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                              │
│  ┌─────────────────────────────────────────────────────┐   │
│  │                 Thread Pool                           │   │
│  │  ProcessMonitorThread (per server)                   │   │
│  │  LogTailThread (per server)                          │   │
│  │  MetricsCollectorThread (per server)                 │   │
│  │  RConPollerThread (per server)                       │   │
│  │  BroadcastThread (global)                            │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                              │
│  ┌─────────────────────────────────────────────────────┐   │
│  │              Data Access Layer (DAL)                  │   │
│  │  ServerRepository │ PlayerRepository                 │   │
│  │  LogRepository    │ MetricsRepository                │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                              │
│  ┌───────────────────┐  ┌────────────────────────────────┐ │
│  │   SQLite (DB)     │  │  Filesystem                    │ │
│  │   languard.db     │  │  servers/{id}/server.cfg       │ │
│  │                   │  │  servers/{id}/basic.cfg        │ │
│  │                   │  │  servers/{id}/server/           │ │ ← profile dir (Arma3 -name=server)
│  │                   │  │    server.Arma3Profile          │ │ ← profile settings
│  │                   │  │    arma3server_*.rpt            │ │ ← RPT logs (tailable)
│  │                   │  │  servers/{id}/battleye/         │ │
│  │                   │  │    beserver.cfg                 │ │ ← RCon config
│  │                   │  │  servers/{id}/mpmissions/       │ │
│  └───────────────────┘  └────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
                         │  subprocess
                         ▼
┌─────────────────────────────────────────────────────────────┐
│            Arma 3 Server Processes (OS level)                │
│   arma3server_x64.exe  (port 2302)                          │
│   arma3server_x64.exe  (port 2402)                          │
│   ...                                                        │
└─────────────────────────────────────────────────────────────┘

---

Component Responsibilities

FastAPI Routers

• Validate input (Pydantic models)
• Call service layer
• Return JSON responses
• Handle WebSocket connections

Service Layer

• Orchestrate operations (start server = generate config + launch process + start threads)
• No direct DB access — delegates to repositories
• No direct process access — delegates to ProcessManager

ProcessManager

• Singleton that owns all subprocess handles
• Thread-safe dict: {server_id: subprocess.Popen}
• start() sets cwd=servers/{server_id}/ so relative config paths resolve correctly
• On Windows: terminate() = TerminateProcess (hard kill), no graceful SIGTERM — graceful shutdown must go through RCon #shutdown first
• Provides: start(), stop(), restart(), is_running(), send_command()

Thread Pool (per running server)

Thread	Interval	Purpose
ProcessMonitorThread	1s	Detect crash / unexpected exit; update DB status; trigger auto-restart
LogTailThread	100ms	Read new lines from .rpt file; store in DB; push to WS clients
MetricsCollectorThread	5s	Collect CPU%, RAM MB for the process via psutil; write to DB
RConPollerThread	10s	Query connected players via BattlEye RCon; update DB player table
BroadcastThread	event-driven	Consume from internal queue; push JSON to all subscribed WS clients

RCon Client

• UDP socket to BattlEye RCon port (configured in beserver.cfg inside the server's battleye/ directory)
• Implements BE RCon protocol: login, keepalive, send command, parse response
• Request multiplexer: tracks pending requests by sequence byte, routes responses to the correct caller via threading.Event per request. Prevents response misrouting when RConPollerThread and API-request RConService calls share the same UDP socket.
• Used by: RConPollerThread, RConService (for admin commands from UI)

Config Generator

• Takes ServerConfig Pydantic model from DB
• Renders server.cfg, basic.cfg, *.Arma3Profile using a structured builder (NOT f-strings — prevents config injection)
• Escapes double quotes and newlines in all user-supplied string values
• Writes files to servers/{server_id}/ directory
• server.Arma3Profile written to servers/{server_id}/server/ (Arma 3 reads from the -name subdirectory)

SQLite DAL

• Sync reads/writes using SQLAlchemy Core (not ORM — simpler for this use case)
• Thread-safe via SQLAlchemy's connection pooling
• One languard.db file at project root
• PRAGMA busy_timeout=5000 — prevents "database is locked" errors under concurrent thread writes
• Thread-local connections via get_thread_db() — one connection per background thread

---

Data Flow: Start Server

Frontend  →  POST /api/servers/{id}/start
          →  ServerService.start(server_id)
               ├── Load ServerConfig from DB
               ├── ConfigGenerator.write_configs(server_id, config)
               │     ├── server.cfg → servers/{id}/server.cfg
               │     ├── basic.cfg → servers/{id}/basic.cfg
               │     ├── server.Arma3Profile → servers/{id}/server/server.Arma3Profile
               │     └── beserver.cfg → servers/{id}/battleye/beserver.cfg
               ├── ProcessManager.start(server_id, exe_path, args, cwd=servers/{id}/)
               ├── DB: update server.status = "starting"
               ├── Spawn ProcessMonitorThread(server_id)
               ├── Spawn LogTailThread(server_id) — tails servers/{id}/server/arma3server_*.rpt
               ├── Spawn MetricsCollectorThread(server_id)
               ├── Spawn RConPollerThread(server_id) [after 30s delay for server startup]
               └── BroadcastThread pushes status update to WS clients

Data Flow: Real-time Logs

arma3server.exe writes servers/{id}/server/arma3server_*.rpt
  → LogTailThread reads new lines (recursive glob for *.rpt in profile dir)
      → LogRepository.insert(server_id, line, timestamp)
      → BroadcastQueue.put({type: "log", server_id, line, timestamp})
          → BroadcastThread sends to all WS subscribers for this server
              → React frontend appends to log viewer

Data Flow: Player List

RConPollerThread (every 10s)
  → RConClient.send("players")
      → Parse response: [{id, name, guid, ping, verified}]
      → PlayerRepository.upsert_all(server_id, players)
      → BroadcastQueue.put({type: "players", server_id, players})
          → React frontend updates player list

---

Security Model

• All API routes (except POST /api/auth/login) require a valid JWT Bearer token
• JWT contains: user_id, username, role (admin | viewer)
• viewer role: read-only (GET endpoints, WebSocket)
• admin role: all operations
• CORS configured to accept only the frontend origin
• Passwords hashed with bcrypt (cost factor 12)
• serverCommandPassword and passwordAdmin stored encrypted in SQLite (AES-256 via cryptography library, key from env)
• Port conflict validation at server creation and start: checks game_port through game_port+4 (game, Steam query, Steam master, Steam auth, RCon) against all existing servers
• ban.txt sync: bans table is source of truth for UI; on ban add/delete via API, also write to battleye/ban.txt; on startup, read ban.txt and upsert into DB. Without this sync, DB-only bans are not enforced by BattlEye.
• Generated config files containing passwords (server.cfg, beserver.cfg) have restrictive file permissions (0600 on Unix, restricted ACL on Windows)
• Input sanitization on all string fields before config generation — no shell injection or config directive injection

---

Configuration (Environment Variables)

LANGUARD_SECRET_KEY=<jwt-signing-secret>
LANGUARD_ENCRYPTION_KEY=<Fernet-base64-key — generate with: python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())">
LANGUARD_DB_PATH=./languard.db
LANGUARD_SERVERS_DIR=./servers
LANGUARD_ARMA_EXE=C:/Arma3Server/arma3server_x64.exe
LANGUARD_HOST=0.0.0.0
LANGUARD_PORT=8000
LANGUARD_CORS_ORIGINS=http://localhost:5173,http://localhost:3000
LANGUARD_LOG_RETENTION_DAYS=7

---

Directory Layout

languard-servers-manager/
├── backend/
│   ├── main.py                    # FastAPI app factory
│   ├── config.py                  # Settings from env
│   ├── database.py                # SQLAlchemy engine + session
│   ├── auth/
│   │   ├── router.py
│   │   ├── service.py
│   │   └── schemas.py
│   ├── servers/
│   │   ├── router.py              # REST endpoints for servers
│   │   ├── service.py             # ServerService
│   │   ├── process_manager.py     # ProcessManager singleton
│   │   ├── config_generator.py    # server.cfg / basic.cfg / beserver.cfg writer
│   │   └── schemas.py             # Pydantic schemas
│   ├── rcon/
│   │   ├── client.py              # BattlEye RCon UDP client
│   │   └── service.py             # RConService
│   ├── players/
│   │   ├── router.py
│   │   ├── service.py
│   │   └── schemas.py
│   ├── missions/
│   │   ├── router.py
│   │   └── service.py
│   ├── mods/
│   │   ├── router.py
│   │   └── service.py
│   ├── logs/
│   │   ├── router.py
│   │   └── service.py
│   ├── metrics/
│   │   ├── router.py
│   │   └── service.py
│   ├── websocket/
│   │   ├── router.py              # WS connection handler
│   │   ├── manager.py             # ConnectionManager (per-server subscriptions)
│   │   └── broadcaster.py        # BroadcastThread + queue
│   ├── threads/
│   │   ├── process_monitor.py     # ProcessMonitorThread
│   │   ├── log_tail.py            # LogTailThread
│   │   ├── metrics_collector.py  # MetricsCollectorThread
│   │   └── rcon_poller.py        # RConPollerThread
│   ├── system/
│   │   └── router.py              # GET /system/status, GET /system/health
│   ├── dal/
│   │   ├── server_repository.py
│   │   ├── config_repository.py
│   │   ├── player_repository.py
│   │   ├── log_repository.py
│   │   ├── metrics_repository.py
│   │   ├── mission_repository.py
│   │   ├── mod_repository.py
│   │   ├── ban_repository.py
│   │   └── event_repository.py
│   └── migrations/
│       └── 001_initial_schema.sql
├── servers/                       # Runtime data per server instance
│   └── {server_id}/
│       ├── server.cfg
│       ├── basic.cfg
│       ├── server/                # Arma 3 profile dir (matches -name=server)
│       │   ├── server.Arma3Profile
│       │   └── arma3server_*.rpt  # Timestamped RPT logs
│       ├── battleye/
│       │   └── beserver.cfg       # BattlEye RCon config (generated on start)
│       └── mpmissions/
├── frontend/                      # React app (separate repo or subfolder)
├── requirements.txt
├── .env.example
├── ARCHITECTURE.md
├── DATABASE.md
├── API.md
├── MODULES.md
├── THREADING.md
└── IMPLEMENTATION_PLAN.md

---

Key Design Decisions

Decision	Choice	Reason
Sync vs async DB	Sync SQLAlchemy only	All DB access is synchronous; background threads are non-async; get_thread_db() provides thread-local connections; no aiosqlite dependency
ORM vs Core	SQLAlchemy Core	Simpler SQL control, less magic for embedded use case
WebSocket auth	JWT in query param on connect	Browser WS API doesn't support headers; query param ?token=...
Process ownership	ProcessManager singleton	Single source of truth; prevents duplicate launches
Log storage	DB + rolling file	DB for fast queries/streaming; raw .rpt preserved on disk
Config files	Regenerate on each start	Always fresh from DB; no sync drift between DB and filesystem; structured builder (not f-strings) prevents config injection
RCon port convention	User-configurable	BattlEye RCon port is set in beserver.cfg (inside battleye/ dir). Default suggestion: game port + 4 (e.g., 2302 → 2306). Must not conflict with game (2302), Steam query (2303), VON (2304), or Steam auth (2305) ports. Note: RCon config changes require server restart — BattlEye reads beserver.cfg only at startup.