Languard Server Manager

A multi-game server management platform with a Python/FastAPI backend and React/TypeScript frontend. Currently supports Arma 3 with an extensible adapter system for adding more games.

Tech Stack

Backend

• Python 3.12+ / FastAPI — async REST API
• SQLite with WAL mode — zero-config database
• SQLAlchemy — raw SQL via text() queries (no ORM)
• BattlEye RCon — UDP protocol v2 for remote admin
• APScheduler — background cleanup jobs
• psutil — process monitoring and resource metrics
• JWT (python-jose) + bcrypt — authentication
• Fernet (cryptography) — sensitive config field encryption

Frontend

• React 19 / TypeScript 6 / Vite 8
• TanStack Query v5 — server state management
• Zustand 5 — client state (auth, UI)
• Tailwind CSS — dark neumorphic design system
• Playwright — E2E testing (23 tests)
• Vitest + React Testing Library — unit tests (69 tests)

Quick Start

Backend

cd backend
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env       # Edit with your settings
uvicorn main:app --reload

First run prints a generated admin password. Change it immediately via PUT /api/auth/password.

Frontend

cd frontend
npm install
npm run dev

Opens at http://localhost:5173. The dev server proxies /api to the backend on port 8000.

Running Tests

Frontend Unit Tests

cd frontend
npm test                  # Watch mode
npx vitest run            # Single run
npx vitest run --coverage # With coverage

Frontend E2E Tests

cd frontend
# Start backend + frontend dev server first
npx playwright test                    # All tests (mocked + integration)
npx playwright tests-e2e/integration/   # Full-stack integration tests only

Project Structure

languard-servers-manager/
├── backend/
│   ├── main.py                  # FastAPI app factory, lifespan, middleware
│   ├── config.py               # Pydantic Settings (env vars)
│   ├── database.py              # SQLAlchemy engine, migration runner
│   ├── dependencies.py          # FastAPI deps: auth, admin, server, adapter
│   ├── adapters/                # Game adapter system
│   │   ├── protocols.py         # Protocol definitions (7 capabilities)
│   │   ├── registry.py          # GameAdapterRegistry singleton
│   │   ├── exceptions.py        # Typed adapter exceptions
│   │   └── arma3/               # Arma 3 adapter (7/7 capabilities)
│   ├── core/
│   │   ├── auth/                # JWT auth, user CRUD
│   │   ├── servers/             # Server service, routers, process manager
│   │   ├── games/               # Game type discovery
│   │   ├── system/              # Health and status endpoints
│   │   ├── websocket/           # WS manager, broadcast thread
│   │   ├── threads/             # Background thread registry
│   │   ├── dal/                 # Data access layer (repositories)
│   │   ├── jobs/                # APScheduler cleanup jobs
│   │   ├── utils/               # Crypto, file utils, port checker
│   │   └── migrations/          # SQL migration scripts
│   └── requirements.txt
├── frontend/
│   ├── src/
│   │   ├── App.tsx              # Router + auth guard
│   │   ├── pages/               # LoginPage, DashboardPage
│   │   ├── components/         # Sidebar, ServerCard, StatusLed
│   │   ├── hooks/               # useServers, useWebSocket
│   │   ├── store/               # auth.store, ui.store (Zustand)
│   │   ├── lib/                 # api.ts (Axios client)
│   │   └── __tests__/          # Vitest unit tests
│   ├── tests-e2e/               # Playwright E2E tests
│   └── playwright.config.ts
├── API.md                       # REST + WebSocket API reference
├── ARCHITECTURE.md              # System architecture overview
├── DATABASE.md                  # Database schema reference
├── FRONTEND.md                  # Frontend architecture and components
├── MODULES.md                   # Module-by-module reference
└── THREADING.md                 # Background threading model

Environment Variables

Variable	Default	Description
LANGUARD_SECRET_KEY	(required)	JWT signing key
LANGUARD_ENCRYPTION_KEY	(required)	Fernet key for sensitive config fields
LANGUARD_DB_PATH	./languard.db	SQLite database path
LANGUARD_SERVERS_DIR	./servers	Base directory for server data
LANGUARD_HOST	0.0.0.0	Listen host
LANGUARD_PORT	8000	Listen port
LANGUARD_CORS_ORIGINS	["http://localhost:5173"]	CORS allowed origins
LANGUARD_LOG_RETENTION_DAYS	7	Log cleanup retention
LANGUARD_METRICS_RETENTION_DAYS	30	Metrics cleanup retention
LANGUARD_PLAYER_HISTORY_RETENTION_DAYS	90	Player history retention
LANGUARD_JWT_EXPIRE_HOURS	24	JWT token expiry
LANGUARD_ARMA3_DEFAULT_EXE	(required for Arma 3)	Default Arma 3 executable path

Documentation

• ARCHITECTURE.md — System design, component diagram, security model
• API.md — Complete REST + WebSocket API reference
• DATABASE.md — Schema, tables, indexes, migration system
• FRONTEND.md — React component tree, state management, design system
• MODULES.md — File-by-file module reference
• THREADING.md — Background thread model and concurrency