languard-servers-manager/CLAUDE.md

Languard Server Manager

Quick Start

# Backend (from backend/)
python -m uvicorn main:app --host 0.0.0.0 --port 8000 --reload

# Frontend (from frontend/)
npx vite --host

• Backend API: http://localhost:8000 (docs: http://localhost:8000/docs)
• Frontend: http://localhost:5173
• Default admin: admin / (random, printed at first startup; reset via python -c "from core.auth.utils import hash_password; print(hash_password('admin123'))" then update SQLite)

Architecture

FastAPI + SQLite backend, React 19 + TypeScript + Vite frontend. See ARCHITECTURE.md for full details.

Key Rules

• Frontend types must match API response shapes, NOT database schema columns
• There is no REST endpoint for logs — logs are only pushed via WebSocket events
• WebSocket onEvent callback is the mechanism for receiving real-time log entries
• Config updates use optimistic locking (config_version) — 409 on conflict
• Sensitive config fields are encrypted at rest with Fernet

Current Implementation Status

Backend: Fully implemented (42+ endpoints)

All routers, services, repositories, game adapter system, WebSocket, background threads, and scheduled cleanup are complete.

Frontend: Mostly implemented

Route	Status	Notes
/login	Complete	Zod + react-hook-form validation
/	Complete	Dashboard with server grid
/servers/:id	Complete	7-tab detail page (overview, config, players, bans, missions, mods, logs)
/servers/new	Partial	4-step wizard; known bug: form validation issues cause silent failure on submit
/settings	Complete	Password change + admin user management

Known Bugs (as of 2026-04-17)

1. Create Server silent failure: The 4-step wizard's "Next" buttons don't validate before advancing steps, so users can reach step 3 with invalid data. handleSubmit then silently fails because validation errors prevent onSubmit from firing. Fix: validate on each "Next" click using trigger() from react-hook-form.

Frontend Type Mapping (API → Frontend)

API Resource	Frontend Type	Key Fields
Server (enriched)	Server in useServers.ts	game_port, current_players, max_players, cpu_percent, ram_mb
Mission	Mission in useServerDetail.ts	name, filename, size_bytes
Mod	Mod in useServerDetail.ts	name, path, size_bytes, enabled
Ban	Ban in useServerDetail.ts	id, server_id, guid, name, reason, banned_by, banned_at, expires_at, is_active, game_data
Player	Player in useServerDetail.ts	id, slot_id, name, guid, ip, ping

Test Commands

# Frontend unit tests
cd frontend && npx vitest run

# Frontend type check
cd frontend && npx tsc --noEmit

# Backend (no test suite yet)

Future Enhancements (user requested)

• Config sub-tab redesign for user-friendliness (non-technical users)
• "Choose mission" button that auto-selects mission for server config
• Mission rotation management