This project is a game server for Intellector, an exciting board game for 2 players.
Live version - https://intellector.info/game/?p=home
Join us on Discord - https://discord.gg/5ycEqRS8Es
Frontend repo - https://github.com/Gulvan0/Intellector
This project is written in Python 3.14. It works with a MySQL 8 database.
See requirements.txt for the authoritative list (requirements-dev.txt for dev/test stage).
Major frameworks:
This repo doesn't have any custom style conventions. Adhere to the commonly accepted Python code style standards, respect PEP8, keep flake8 and mypy happy and stay idiomatic.
Domain packages share a common layout; each part exists only where needed:
routes.py(orroutes/) - the FastAPI routermethods.py(ormethods/) - the logic the routes callmodels.py(ormodels/) - SQLModel tables and the REST/WS payloads derived from themdatatypes.py- the domain's enums and plain modelsdependencies.py- the domain's FastAPI dependenciessamples.py- generators of example payloads, attached to the WS events (payload_examples)
Domains:
auth- guest tokens, sign-in, registration,whoami. Password hashes are kept in theintellector_sensitivedatabase, where every table holding secrets belongs: the read-only search user may read all ofmainchallenge- challenges: validation, creation, merging a matching pair into a game, cancellationgame- gamesroutes-common(search, reading a game, chat, adding time, ...),internal(games between two connected players: plies, offers, resignation),external(games computed on a client, such as bot games, and uploaded ply by ply)methods- creation, plies, offers, rollbacks, timeouts, presence, endingmodels- games, plies, chat, offers, rollbacks, time controls, presence, suspensions, outcomes;models/restholds the game endpoints' payloads
player- profiles, search, game stats and Elo history, follows, roles and restrictions, online statuses (status.py)study- studies (saved ply trees) and their validationnotification- announcements of new public challenges and started games to VK and Discord, Telegram messages to the admin, the VK antispam limitother- endpoints outside any domain: API version (api_version.py), health, client error reports, admin shutdown and state inspection
Core:
main.py- the entry point: assembles the app from the routers and the WS handlers, adds the middlewares and runs uvicorn (prod: one server on the loopback behind Caddy; test: TLS on8443plus plain HTTP on8080)net- the app itself:App(the FastAPI subclass holding the configs, the DB engine and the state),MutableState(in-memory tokens, WS subscribers, game action locks), WS connection handling, routes that log and rate-limit requests, the middlewarespubsub- WebSocket PubSub: channels, the handlers of incoming messages (session,sub,unsub), outgoing events (refresh- a channel's full state,update- a change)log- logs of the REST/WS traffic and of client errors, kept in theintellector_logsdatabasejobs- jobs run by systemd timers outside the server process:log_archivemoves old log days to the backup storageconfig-STAGEselection, loadingresources/config/*.yaml(thecommonsection merged with the stage's one), the config modelsboard- game rules: positions, plies and their validation, SIP (position string) serialization, notation, openingscommon- shared across domains: user references (players, guests, bots), FastAPI dependencies, DB field types, time controls, the bot registryutils- generic helpers, not specific to Intellector
Standalone scripts:
api_lock.py- guards against forgetting to bump the API version (check/confirm)migrator.py(with themigrationpackage) - the one-time import of the previous iteration's datadrawer.py- a debug tool drawing a board with Pillow
alembic(plusalembic.ini) - DB schema migrations. The server never creates tables itselfresourcesconfig-main.yaml(tunables: keep-alive, Elo, rules, limits, rate limits, VK antispam) andsecret.yaml(credentials; untracked, template insecret.example.yaml)sql- raw SQL queriespieces- piece images fordrawer.pycert- the local TLS certificate (untracked)
infra- the production VPSdeploy.py- one-command deploy from the developer's PC: publishes the client to the static hosting and a new server release to the VPSbootstrap.sh- one-time setup of a fresh VPS: packages, users, folders, MySQL, Pythonapply.sh- installs the configs belowictl- the operator CLI on the VPScaddy,mysql,journald,systemd- service configs; the systemd units and timers run the server, backups, restore tests, log archiving and the watchdogscripts- backup, restore, health check, alerts
api.lock- the API version and the OpenAPI schema hash it was last confirmed for
Note: Frontend repo has its own Quick Start in its own README. If you wish to work on the frontend, make sure to follow it as well.
Python 3.14MySQL 8mkcert(for the local TLS ceritificate)
https://github.com/Gulvan0/IntellectorServer
Run everything from the repo root, with STAGE=test environment variable set.
-
Python environment
python -m venv .venv- Activate the venv
pip install -r requirements-dev.txt
-
MySQL
- Create
main,intellector_logsandintellector_sensitivedatabases - Give one user full rights on all three
- Create
-
Certificate
mkcert -installmkcert localhost 127.0.0.1insideresources/cert/.cert/is gitignored, so each developer makes their own
-
Secrets
Write
resources/config/secret.yaml(you can just copyresources/config/secret.example.yamland fill in the values). -
Schema
python -m alembic upgrade head -
Running the server
python src/main.py(will listen onhttps://localhost:8443andhttp://localhost:8080)