b7d670a91c
- Add Playwright E2E for all 5 UX phases (Config/Missions/Mods/Players/Logs) with ServerDetailPage POM and fully mocked API routes - Add logger.test.ts: dynamic module re-import pattern for level-gating tests - Add useUpdateServer + useKillServer tests to useServers.test.tsx - Add CreateServerPage edge cases: non-admin gate, API error handling, step 2 render - Add auth.store rehydration and null-branch coverage tests - Update FRONTEND.md, MODULES.md, API.md, README.md to reflect current state (167 unit tests, 38 E2E tests, 9 useServers hooks, all UX phases implemented)
139 lines
5.9 KiB
Markdown
139 lines
5.9 KiB
Markdown
# 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 (38 tests)
|
|
- **Vitest** + **React Testing Library** — unit tests (167 tests)
|
|
|
|
## Quick Start
|
|
|
|
### Backend
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
cd frontend
|
|
npm test # Watch mode
|
|
npx vitest run # Single run
|
|
npx vitest run --coverage # With coverage
|
|
```
|
|
|
|
### Frontend E2E Tests
|
|
|
|
```bash
|
|
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, ServerDetailPage, CreateServerPage, SettingsPage
|
|
│ │ ├── components/ # Sidebar, ServerCard, ConfigEditor, PlayerTable, BanTable, MissionList, ModList, LogViewer, StatusLed
|
|
│ │ ├── hooks/ # useServers, useServerDetail, useAuth, useGames, useWebSocket
|
|
│ │ ├── store/ # auth.store, ui.store (Zustand)
|
|
│ │ ├── lib/ # api.ts (Axios client)
|
|
│ │ └── __tests__/ # Vitest unit tests (~120 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](ARCHITECTURE.md)** — System design, component diagram, security model
|
|
- **[API.md](API.md)** — Complete REST + WebSocket API reference
|
|
- **[DATABASE.md](DATABASE.md)** — Schema, tables, indexes, migration system
|
|
- **[FRONTEND.md](FRONTEND.md)** — React component tree, state management, design system
|
|
- **[MODULES.md](MODULES.md)** — File-by-file module reference
|
|
- **[THREADING.md](THREADING.md)** — Background thread model and concurrency |