languard-servers-manager/ARCHITECTURE.md

Languard Servers Manager — System Architecture

Overview

Languard is a multi-game web-based management panel for dedicated game servers. It uses a game adapter architecture where a game-agnostic core handles server lifecycle, monitoring, and real-time communication, while game-specific behavior (config formats, remote admin protocols, log parsing, mission/mod handling) is encapsulated in pluggable adapters.

Arma 3 is the first-class, built-in adapter. Adding a new game server type requires only a new adapter package — no core code changes.

---

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 server executables, 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
Game adapters	Protocol + Registry	Each game implements capability protocols; core resolves the adapter at runtime from server.game_type
Scheduling	APScheduler (BackgroundScheduler)	Auto-restart, 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 + Vite + Tailwind	See FRONTEND.md for full design system, component architecture, and adapter-aware UI patterns

---

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                        React Frontend (see FRONTEND.md)       │
│   Dashboard │ Server List │ Server Detail │ Logs │ Config UI │
│   Game Type Selector │ Adapter-specific Panels               │
└────────────────────────┬────────────────────────────────────┘
                         │  HTTP REST + WebSocket
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                    FastAPI Application (Core)                  │
│                                                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  │
│  │  Auth Router │  │ Server Router│  │  Config Router   │  │
│  └──────────────┘  └──────────────┘  └──────────────────┘  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  │
│  │ Player Router│  │  Log Router  │  │  WS Router       │  │
│  └──────────────┘  └──────────────┘  └──────────────────┘  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  │
│  │ Metric Router│  │ Event Router │  │  Games Router    │  │
│  └──────────────┘  └──────────────┘  └──────────────────┘  │
│                                                              │
│  ┌─────────────────────────────────────────────────────┐   │
│  │              Core Service Layer                      │   │
│  │  ServerService │ ConfigService │ PlayerService      │   │
│  │  LogService    │ MetricsService│ EventService       │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                              │
│  ┌─────────────────────────────────────────────────────┐   │
│  │           Game Adapter Registry                      │   │
│  │  GameAdapterRegistry.get(game_type) → GameAdapter    │   │
│  │                                                       │   │
│  │  Delegates to:                                        │   │
│  │   • ConfigGenerator   → adapter.get_config_generator()│   │
│  │   • ProcessConfig     → adapter.get_process_config() │   │
│  │   • LogParser         → adapter.get_log_parser()     │   │
│  │   • RemoteAdmin       → adapter.get_remote_admin()   │   │
│  │   • MissionManager    → adapter.get_mission_manager() │   │
│  │   • ModManager        → adapter.get_mod_manager()    │   │
│  │   • BanManager        → adapter.get_ban_manager()    │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                              │
│  ┌─────────────────────────────────────────────────────┐   │
│  │                 Thread Pool                           │   │
│  │  ProcessMonitorThread (per server, core)             │   │
│  │  LogTailThread (per server, core + adapter parser)   │   │
│  │  MetricsCollectorThread (per server, core)           │   │
│  │  RemoteAdminPollerThread (per server, core + adapter) │   │
│  │  BroadcastThread (global)                            │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                              │
│  ┌─────────────────────────────────────────────────────┐   │
│  │              Data Access Layer (DAL)                  │   │
│  │  ServerRepository │ PlayerRepository                 │   │
│  │  LogRepository    │ MetricsRepository                │   │
│  │  ConfigRepository (game_configs table)               │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                              │
│  ┌───────────────────┐  ┌────────────────────────────────┐ │
│  │   SQLite (DB)     │  │  Filesystem                    │ │
│  │   languard.db     │  │  servers/{id}/ (layout by       │ │
│  │                   │  │    adapter.get_process_config() │ │
│  └───────────────────┘  └────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
                         │
           ┌─────────────┴─────────────────┐
           ▼                                ▼
┌──────────────────────┐  ┌──────────────────────────────────┐
│  Game Adapters        │  │  Game Server Processes (OS level) │
│                      │  │                                    │
│  ┌────────────────┐  │  │   (Any game executable)           │
│  │   Arma 3       │  │  │   Started via adapter's           │
│  │   adapter      │  │  │   build_launch_args()             │
│  │                │  │  │                                    │
│  │ • ConfigGen    │  │  └──────────────────────────────────┘
│  │ • ProcessConfig│  │
│  │ • RPTParser    │  │
│  │ • BERConClient │  │
│  │ • MissionMgr   │  │
│  │ • ModMgr       │  │
│  │ • BanMgr       │  │
│  └────────────────┘  │
│                      │
│  ┌────────────────┐  │
│  │  (Future Game) │  │
│  │   adapter      │  │
│  └────────────────┘  │
└──────────────────────┘

---

Game Adapter Architecture

Core Principle: Composition Over Inheritance

Each game adapter is a composition of capability objects implementing well-defined Protocol interfaces. Not every game supports every capability — adapters return None for unsupported features, and the core gracefully degrades.

Capability Protocols

Protocol	Purpose	Required?
ConfigGenerator	Define config schema + Pydantic models, write config files, build launch args	Yes
ProcessConfig	Exe allowlist, port conventions, directory layout	Yes
LogParser	Parse game-specific log lines, find log files	Yes
RemoteAdmin	Factory for RCon/Telnet/HTTP admin clients	No
MissionManager	Mission file format and rotation config	No
ModManager	Mod folder convention and CLI args	No
BanManager	Ban file sync between DB and game's ban file	No

Adapter Registry

# adapters/registry.py
class GameAdapterRegistry:
    _adapters: dict[str, GameAdapter] = {}

    @classmethod
    def register(cls, adapter: GameAdapter) -> None: ...

    @classmethod
    def get(cls, game_type: str) -> GameAdapter: ...

    @classmethod
    def all(cls) -> list[GameAdapter]: ...

    @classmethod
    def list_game_types(cls) -> list[dict]: ...

Adapters auto-register at import time. The core never imports adapter internals — it only resolves through the registry.

How Core Delegates to Adapter

Every server has a game_type column. When core code needs game-specific behavior, it:

1. Reads server.game_type from DB
2. Resolves adapter = GameAdapterRegistry.get(game_type)
3. Calls the appropriate adapter method

Example — Server start flow:

def start(self, server_id: int) -> dict:
    server = ServerRepository(db).get_by_id(server_id)
    adapter = GameAdapterRegistry.get(server["game_type"])
    process_config = adapter.get_process_config()

    # Core validation (game-agnostic)
    exe_basename = Path(server["exe_path"]).name
    if exe_basename not in process_config.get_allowed_executables():
        raise ValueError(f"Executable not allowed: {exe_basename}")

    # Adapter generates config files
    config_gen = adapter.get_config_generator()
    config_gen.write_configs(server_id, server_dir, config_sections)

    # Adapter builds launch args
    launch_args = config_gen.build_launch_args(config_sections, mod_args)

    # Core launches process (game-agnostic)
    pid = ProcessManager.get().start(server_id, exe_path, launch_args, cwd=server_dir)

    # Core starts threads (delegates to adapter for parsers/clients)
    ThreadRegistry.start_server_threads(server_id, db)

---

Component Responsibilities

FastAPI Routers (Core)

• Validate input (Pydantic models)
• Resolve adapter from server.game_type
• Delegate game-specific work to adapter
• Return JSON responses
• Handle WebSocket connections
• Return 404 with clear message if adapter lacks a capability

Core Service Layer

• Orchestrate operations (start server = resolve adapter + generate config + launch process + start threads)
• No direct DB access — delegates to repositories
• No direct process access — delegates to ProcessManager
• No game-specific logic — delegates to adapter

ProcessManager (Core)

• Singleton that owns all subprocess handles
• Thread-safe dict: {server_id: subprocess.Popen}
• Per-server operation lock (_operation_locks: dict[int, threading.Lock]) — serializes start/stop/restart for the same server. Prevents race conditions when two admins hit "start" simultaneously or when start+stop overlap. Each server gets its own lock; different servers operate independently.
• start() sets cwd=servers/{server_id}/ so relative config paths resolve correctly
• On Windows: terminate() = TerminateProcess (hard kill, no SIGTERM) — graceful shutdown must go through adapter's RemoteAdmin
• Provides: start(), stop(), restart(), is_running(), send_command()
• Exe validation is delegated to adapter's ProcessConfig — core no longer has a hardcoded allowlist

Thread Pool (per running server)

Thread	Source	Interval	Purpose
ProcessMonitorThread	Core	1s	Detect crash / unexpected exit; update DB status; trigger auto-restart
LogTailThread	Core + adapter's LogParser	100ms	Read new lines from log file; parse via adapter; store in DB; push to WS
MetricsCollectorThread	Core	5s	Collect CPU%, RAM MB via psutil; write to DB
RemoteAdminPollerThread	Core + adapter's RemoteAdmin	10s	Query players via adapter's admin client; update DB player table
BroadcastThread	Core	event-driven	Consume from internal queue; push JSON to all subscribed WS clients

ConfigRepository (Core)

• Manages the generic game_configs table
• Stores config as JSON blobs keyed by (server_id, section)
• Validation is delegated to adapter's Pydantic models — core never inspects config content
• Sensitive field encryption: calls adapter.get_config_generator().get_sensitive_fields(section) to identify which JSON keys to encrypt/decrypt via Fernet
• Optimistic locking: each row includes config_version (integer). On PUT, client sends the version they read. If version mismatch, return 409 Conflict.
• Schema migration: on read, if schema_version differs from adapter.get_config_version(), core calls adapter.migrate_config(old_version, config_json). On success, updates the row with migrated JSON and new schema_version. On ConfigMigrationError, keeps original config and logs a warning.
• Provides: get_section(), get_all_sections(), upsert_section(), delete_sections()

Adapter Exceptions (Standard Error Types)

Adapters raise specific exception types so the core can handle errors precisely:

Exception	When Raised	Core Action
ConfigWriteError	File write fails (disk full, permissions)	Set server status='error', return 500 with detail
ConfigValidationError	Config values violate adapter constraints	Return 400 with field-level errors
LaunchArgsError	build_launch_args() fails (missing mod, bad path)	Set server status='error', return 400
RemoteAdminError	Remote admin connection/command fails	Log warning, return 503 with detail
ExeNotAllowedError	Executable not in adapter's allowlist	Return 400 with allowed list
ConfigMigrationError	migrate_config() fails to transform old schema	Keep original config, log warning, server runs with old schema

---

Data Flow: Start Server

Frontend → POST /api/servers/{id}/start
         → ServerService.start(server_id)
              ├── Load server from DB (includes game_type)
              ├── adapter = GameAdapterRegistry.get(server.game_type)
              ├── Validate exe against adapter.get_process_config().get_allowed_executables()
              │     (raises ExeNotAllowedError → 400)
              ├── Check ALL derived ports across ALL running servers
              │     (resolve each server's adapter, get port conventions, check full set)
              ├── Load config sections from game_configs table
              ├── adapter.get_config_generator().write_configs(server_id, dir, config)
              │     ATOMIC: writes to .tmp files first, then os.replace() to final paths
              │     On failure: cleans up .tmp files, raises ConfigWriteError
              │     Core: sets status='error', returns 500
              ├── launch_args = adapter.get_config_generator().build_launch_args(config, mods)
              │     On failure: raises LaunchArgsError → 400
              ├── ProcessManager.start(server_id, exe_path, launch_args, cwd=dir)
              ├── DB: update server.status = "starting"
              ├── ThreadRegistry.start_server_threads(server_id, db)
              │     ├── ProcessMonitorThread (core, always)
              │     ├── LogTailThread(server_id, adapter.get_log_parser())
              │     ├── MetricsCollectorThread (core, always)
              │     └── RemoteAdminPollerThread(server_id, adapter.get_remote_admin())
              │         (only if adapter has remote_admin capability)
              │         Core wraps client with threading.Lock for thread safety
              └── BroadcastThread pushes status update to WS clients

Data Flow: Real-time Logs

Game server writes log file (path determined by adapter.get_log_parser().get_log_file_resolver())
  → LogTailThread reads new lines (core tailing logic, game-agnostic)
      → adapter.get_log_parser().parse_line(line) → {timestamp, level, message}
      → LogRepository.insert(server_id, entry)
      → BroadcastQueue.put({type: "log", server_id, entry})
          → BroadcastThread sends to all WS subscribers for this server
              → React frontend appends to log viewer

Data Flow: Player List

RemoteAdminPollerThread (every 10s, core thread)
  → adapter.get_remote_admin().create_client() → client instance
  → client.get_players() → list of player dicts
      → PlayerService.update_from_remote_admin(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)
• Sensitive config fields (passwords, RCon passwords) stored encrypted in game_configs JSON (AES-256 via Fernet, key from env)
• Port conflict validation at server creation and start: uses adapter's get_port_conventions() to determine all derived ports
• Ban file sync: adapter's BanManager handles bidirectional sync between DB bans table and game's ban file format
• Generated config files containing passwords 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
• Exe validation: core checks against adapter's get_allowed_executables() — prevents executing arbitrary binaries

---

Core vs Adapter Responsibility Boundary

Concern	Owner	Rationale
Server CRUD (name, description, status, game_type, ports)	Core	Universal concept
Process lifecycle (subprocess start, stop, kill)	Core	subprocess.Popen is game-agnostic
Config schema definition + file generation	Adapter	Schema, validation models, file formats, and launch args are all game-specific — unified in ConfigGenerator
Config CRUD in DB	Core	game_configs table is generic; adapter validates JSON
Process monitoring (crash detection, auto-restart)	Core	OS-level, game-agnostic
System metrics (CPU, RAM)	Core	psutil is game-agnostic
Log file tailing mechanics	Core	Tail -f is universal
Log line parsing	Adapter	RPT vs. server.log vs. custom JSON
Log file discovery	Adapter	Different naming conventions per game
Log storage and querying	Core	logs table is game-agnostic
Remote admin protocol	Adapter	BattlEye UDP vs. Source RCON vs. none
Remote admin polling	Core	Thread and interval logic are generic
Player identification	Adapter	GUID, Steam ID, UUID — game-specific
Player storage and history	Core	Generic table with game_data JSON
Ban concept	Core	Universal
Ban file sync	Adapter	battleye/ban.txt vs. banned-players.json vs. none
Mission/scenario file format	Adapter	PBO vs. PK3 vs. directory
Mission rotation config	Adapter	Game-specific format
Mission storage in DB	Core	Generic filename/metadata
Mod folder convention	Adapter	@mod_folder vs. mods/ vs. plugins/
Mod CLI argument building	Adapter	-mod= vs. +moddir vs. none
Mod storage in DB	Core	Generic mod registration
Exe name allowlist	Adapter	Game-specific binary names
Port convention (derived ports)	Adapter	Arma 3: game+1/+2/+3 for Steam; varies per game
Profile directory convention	Adapter	Arma 3: -name=server subdirectory; varies
WebSocket real-time	Core	Transport is game-agnostic
Auth and user management	Core	No game dependency
Event/audit trail	Core	Generic; adapter can define additional event types
Scheduled cleanup	Core	Cron jobs are game-agnostic

---

Configuration (Environment Variables)

LANGUARD_SECRET_KEY=<jwt-signing-secret>
LANGUARD_ENCRYPTION_KEY=<Fernet-base64-key>
LANGUARD_DB_PATH=./languard.db
LANGUARD_SERVERS_DIR=./servers
LANGUARD_HOST=0.0.0.0
LANGUARD_PORT=8000
LANGUARD_CORS_ORIGINS=http://localhost:5173,http://localhost:3000
LANGUARD_LOG_RETENTION_DAYS=7
LANGUARD_METRICS_RETENTION_DAYS=30
LANGUARD_PLAYER_HISTORY_RETENTION_DAYS=90

# Game-specific defaults (adapter may use these)
LANGUARD_ARMA3_EXE=C:/Arma3Server/arma3server_x64.exe
# LANGUARD_MINECRAFT_JAR=C:/minecraft/server.jar
# LANGUARD_RUST_EXE=C:/RustDedicated/RustDedicated.exe

---

Directory Layout

languard-servers-manager/
├── backend/
│   ├── main.py                    # FastAPI app factory
│   ├── config.py                  # Settings from env
│   ├── database.py                # SQLAlchemy engine + session
│   ├── dependencies.py            # Auth deps, server lookup
│   │
│   ├── core/                      # Game-agnostic core
│   │   ├── auth/
│   │   │   ├── router.py
│   │   │   ├── service.py
│   │   │   ├── schemas.py
│   │   │   └── utils.py
│   │   ├── servers/
│   │   │   ├── router.py          # REST endpoints for servers
│   │   │   ├── service.py         # ServerService (delegates to adapter)
│   │   │   ├── process_manager.py # ProcessManager singleton
│   │   │   └── schemas.py         # Generic Pydantic schemas
│   │   ├── players/
│   │   │   ├── router.py
│   │   │   ├── service.py
│   │   │   └── schemas.py
│   │   ├── logs/
│   │   │   ├── router.py
│   │   │   └── service.py
│   │   ├── metrics/
│   │   │   ├── router.py
│   │   │   └── service.py
│   │   ├── bans/
│   │   │   ├── router.py
│   │   │   └── service.py
│   │   ├── events/
│   │   │   ├── router.py
│   │   │   └── service.py
│   │   ├── websocket/
│   │   │   ├── router.py
│   │   │   ├── manager.py
│   │   │   └── broadcaster.py
│   │   ├── threads/
│   │   │   ├── base_thread.py
│   │   │   ├── process_monitor.py
│   │   │   ├── log_tail.py         # Generic, takes adapter LogParser
│   │   │   ├── metrics_collector.py
│   │   │   ├── remote_admin_poller.py  # Generic, takes adapter RemoteAdmin
│   │   │   └── thread_registry.py
│   │   ├── games/
│   │   │   └── router.py           # /api/games — type discovery, schemas
│   │   ├── system/
│   │   │   └── router.py
│   │   ├── dal/
│   │   │   ├── base_repository.py
│   │   │   ├── server_repository.py
│   │   │   ├── config_repository.py    # game_configs table
│   │   │   ├── player_repository.py
│   │   │   ├── log_repository.py
│   │   │   ├── metrics_repository.py
│   │   │   ├── mission_repository.py
│   │   │   ├── mod_repository.py
│   │   │   ├── ban_repository.py
│   │   │   └── event_repository.py
│   │   ├── migrations/
│   │   │   ├── runner.py
│   │   │   └── 001_initial_schema.sql
│   │   └── utils/
│   │       ├── crypto.py
│   │       ├── file_utils.py
│   │       └── port_checker.py
│   │
│   └── adapters/                  # Game-specific adapters
│       ├── __init__.py
│       ├── registry.py            # GameAdapterRegistry
│       ├── protocols.py           # All capability Protocol definitions
│       │
│       └── arma3/                 # Arma 3 adapter (built-in)
│           ├── __init__.py         # Exports ARMA3_ADAPTER, registers on import
│           ├── adapter.py          # Arma3Adapter class
│           ├── config_generator.py # Pydantic models + server.cfg, basic.cfg, Arma3Profile, beserver.cfg
│           ├── rcon_client.py      # BERConClient (BattlEye UDP protocol)
│           ├── rcon_service.py     # Wraps BERConClient for RemoteAdmin protocol
│           ├── log_parser.py       # RPTParser
│           ├── mission_manager.py  # PBO upload, mission rotation config
│           ├── mod_manager.py      # @mod_folder convention, -mod=/-serverMod=
│           ├── process_config.py   # Exe allowlist, port conventions, profile dir
│           ├── ban_manager.py      # battleye/ban.txt bidirectional sync
│           ├── schemas.py          # Arma 3 specific request/response models
│           └── migrations/
│               └── 001_arma3_metadata.sql  # Arma 3 specific tables (if any)
│
├── servers/                       # Runtime data per server instance
│   └── {server_id}/               # Layout determined by adapter.get_process_config()
│       └── (Arma 3: server.cfg, basic.cfg, server/, battleye/, mpmissions/)
│
├── frontend/                      # React app
├── requirements.txt
├── .env.example
├── ARCHITECTURE.md
├── DATABASE.md
├── API.md
├── MODULES.md
├── THREADING.md
├── FRONTEND.md
└── IMPLEMENTATION_PLAN.md

---

Adding a New Game Adapter

To add support for a new game, create an adapter package:

adapters/<game_type>/
├── __init__.py           # Export adapter, register in registry
├── adapter.py            # Implement GameAdapter protocol
├── config_generator.py   # Pydantic models + write game config files
├── log_parser.py         # Parse game log format
├── process_config.py     # Exe allowlist, port conventions
├── ...                   # Optional: rcon_client, mission_manager, mod_manager, ban_manager
└── migrations/           # Optional: game-specific DB extensions

Steps:

1. Implement the required protocols: ConfigGenerator, ProcessConfig, LogParser
2. Implement optional protocols as needed: RemoteAdmin, MissionManager, ModManager, BanManager
3. Create the GameAdapter class composing all capabilities
4. Register the adapter — either:
   • Built-in: register in adapters/__init__.py via import
   • Third-party: register via setuptools entry_point in pyproject.toml:

     [project.entry-points."languard.adapters"]
     mygame = "mygame_adapter:MYGAME_ADAPTER"
     

     Core scans languard.adapters entry_point group at startup and auto-registers.
5. No core code changes, no DB migrations required

---

Key Design Decisions

Decision	Choice	Reason
Game-specific logic	Adapter pattern with Protocol + Registry	Structural subtyping with mypy enforcement; optional capabilities return None; zero core changes per game
Capability probe	has_capability() on GameAdapter	Instead of scattered None checks, GameAdapter.has_capability(name) returns bool. Core code uses this to check support before calling get methods. Cleaner than if adapter.get_remote_admin() is not None: everywhere.
Protocol granularity	7 protocols (ConfigGenerator merged from ConfigSchema+ConfigGenerator)	ConfigSchema and ConfigGenerator always co-occur (no game has schema without generation). Merged into single ConfigGenerator with schema + generation methods. ProcessConfig kept separate — may evolve independently.
Config storage	Hybrid: core normalized + game_configs JSON	Core tables stay clean; config is always whole-read/write; adapter Pydantic models validate; zero migration per new game
Sync vs async DB	Sync SQLAlchemy only	All DB access is synchronous; background threads are non-async; no aiosqlite dependency
WebSocket auth	JWT in query param on connect	Browser WS API doesn't support headers
Process ownership	ProcessManager singleton	Single source of truth; prevents duplicate launches
Server operation safety	Per-server operation lock	ProcessManager holds a lock per server_id that serializes start/stop/restart. Two concurrent start requests for the same server: the second waits for the first to complete, then sees the server is already running. Different servers are independent (no cross-server locking).
Config files	Adapter regenerates on each start	Always fresh from DB; no sync drift; adapter's structured builder prevents config injection
Config write failure	Atomic write + rollback	Adapter writes to temp files first, then atomic rename. On failure, temp files are cleaned up — original files remain untouched. Server start never proceeds with partial config.
Sensitive field encryption	Adapter declares via get_sensitive_fields()	ConfigGenerator protocol returns list of JSON keys per section that need Fernet encryption. Core's ConfigRepository handles encrypt/decrypt transparently.
Adapter schema versioning	config_version in game_configs row	Each config section row stores a version string. On adapter update, if version differs, core calls adapter.migrate_config(old_version, config_json) which returns the migrated dict. On migration failure (ConfigMigrationError), core keeps the original config and logs a warning — the server can still run with the old schema.
Adapter error communication	Typed adapter exceptions	Adapters raise specific exception types (ConfigWriteError, ConfigValidationError, LaunchArgsError, RemoteAdminError). Core catches specifically and sets appropriate DB status + returns clear API errors.
Remote admin thread safety	Core wraps with lock	Core wraps RemoteAdminClient calls with a threading.Lock. Adapter clients don't need to be thread-safe. One lock per server — API requests and poller thread share safely.
Third-party adapter loading	Setuptools entry_points	Third-party adapters register via languard.adapters entry_point group. Core scans entry_points at startup and auto-registers. Built-in adapters registered on import.
Port conflict detection	Full cross-game check	When checking ports for a new/starting server, query ALL running servers, resolve each adapter, get port conventions for that game, and check the full derived port set.
Config preview	Dict of label → content	preview_config() returns {label: rendered_content}. File-based games use filename as label; env-var games use variable name; CLI games use argument name. Frontend renders all as labeled text blocks.
Ban file sync timing	Immediate + startup	On every ban add/delete via API, adapter's BanManager syncs to file immediately. On startup, adapter reads ban file and upserts into DB. Ensures consistency.
Config concurrency	Optimistic locking	game_configs rows include config_version (integer). On PUT, client sends the version they read. If version mismatch, return 409 Conflict. Frontend re-reads and merges.
game_data JSON schema	Adapter declares via get_game_data_schema()	Each capability protocol (MissionManager, ModManager, etc.) optionally returns a Pydantic model for the game_data JSON. Core validates on write.
Log storage	DB + rolling file	DB for fast queries/streaming; raw logs preserved on disk
Player identification	slot_id (string) + game_data JSON	Flexible across games; Arma 3 uses int slot, others may use UUID
Route URLs	Game-agnostic with adapter delegation	Frontend doesn't need game-type-specific URLs; 404 if adapter lacks capability
API route registration	Core defines all routes; adapter dispatch at request time	Simpler than dynamic route mounting; clear 404 for unsupported features