Backend for a Tokemons game built with FastAPI, SQLAlchemy 2.0 (async), and PostgreSQL.
Python 3.14 · FastAPI · SQLAlchemy 2.0 · PostgreSQL 17 · Alembic · dishka (DI) · uv
- Python 3.14+
- uv
- PostgreSQL 17+
cp .env.example .env # configure environment
uv sync --all-groups # install dependencies
uv run alembic upgrade head # apply migrations
uv run uvicorn main:app --host 0.0.0.0 --port 8000Copy .env.example to .env and fill in the values. Env vars use __ as nested delimiter (e.g. DB__HOST).
Required:
| Variable | Description |
|---|---|
DB__HOST, DB__PORT, DB__NAME, DB__USERNAME, DB__PASSWORD |
PostgreSQL connection. Defaults work for local postgres:postgres on port 5432 |
JWT__SECRET |
Secret key for signing JWT tokens. Generate a strong random string for production (openssl rand -hex 32) |
Auth providers (needed for login to work):
| Variable | Description | Where to get |
|---|---|---|
TELEGRAM__BOT_TOKEN |
Telegram Bot API token | @BotFather — create a bot, copy the token |
TELEGRAM__OAUTH_CLIENT_SECRET |
Secret for Telegram OAuth flow | Same bot settings or your OAuth provider config |
TELEGRAM__OAUTH_ALLOWED_HOSTS |
Allowed redirect hosts for OAuth | Your frontend domain(s) |
TON__ALLOWED_DOMAINS |
Domains allowed for TON Connect proof verification | Your frontend domain(s) |
TON__NETWORK |
mainnet or testnet |
Depends on your TON environment |
Optional:
| Variable | Description |
|---|---|
SENTRY__DSN |
Sentry DSN for error tracking. Leave empty to disable |
CORS__ALLOW_ORIGINS |
Allowed CORS origins (default: ["*"]) |
RATE_LIMIT__ENABLED |
Enable rate limiting (default: true) |
SPRITES__BASE_URL |
Base URL for creature sprite assets |
SWAGGER_TONCONNECT_MANIFEST_URL |
TonConnect manifest URL for Swagger UI |
SWAGGER_TELEGRAM_OAUTH_ENABLED |
Enable Telegram OAuth button in Swagger |
ENVIRONMENT |
development / production (default: development) |
LOGGING_LEVEL |
DEBUG, INFO, WARNING, ERROR, CRITICAL (default: INFO) |
Game balance settings (ECONOMY__*, GAME__*) have sensible defaults — see src/config.py for the full list.
make # fmt + lint + db check + test
make ci # full CI pipeline
make fmt # format code
make lint # ruff + mypy
make test # run tests
make db # check migrationsArchitecture and specs are in docs/ — includes C4 diagrams, 17 ADRs, and feature specifications for 15 modules.