Skip to content

Latest commit

 

History

History
89 lines (70 loc) · 4.99 KB

README.md

File metadata and controls

89 lines (70 loc) · 4.99 KB

Sophikron backend

FastAPI, SQLAlchemy asyncio, psycopg and PostgreSQL. Application endpoints are registered through app/api/router.py under /api/v1; /health is an unversioned infrastructure readiness check.

See authentication for identity encryption, key generation, initial administrator setup, API contracts, SMTP, sessions and verification. See database operations for database roles, secrets and Alembic.

See administration for integer account IDs, generated immutable usernames, four encrypted identity fields, explicit permissions, promotions, fuzzy name search and activity. The shared responsive frontend uses these contracts; see frontend and BFF. Complete school profiles keep optional private information encrypted in users, with administrator editing and scoped teacher orientation editing; see profile contracts.

Development prerequisites

For native tests, use Python 3.13 (the Docker/CI version), Docker with Linux containers and Compose v2. Run from the repository root. Reuse an existing project environment if already configured.

Windows PowerShell:

py -3.13 -m venv .venv
./.venv/Scripts/python.exe -m pip install -e "./backend[dev]"
cd backend
../.venv/Scripts/python.exe run_tests.py

Linux shell:

python3.13 -m venv .venv
.venv/bin/python -m pip install -e './backend[dev]'
cd backend
../.venv/bin/python run_tests.py

For frontend checks, install Node 24 and run npm ci in frontend/, then follow release verification.

Install into the configured Python environment with python -m pip install -e ".[dev]". Run:

python -m pytest -q -m "not integration"
ruff check .

The complete python -m pytest -q suite includes real PostgreSQL tests only when explicitly enabled against sophikron_test. Tests never substitute SQLite for PostgreSQL constraints or concurrency.

PyCharm Run / Debug

Use the single Python configuration run_tests, targeting backend/run_tests.py with the local interpreter of the sophikron-api module and working directory backend/. Its persistent local configuration is in .idea/runConfigurations/run_tests.xml (IDE settings are excluded from Git). The same entry point is available from the terminal with python run_tests.py in backend/.

With Docker Desktop running, click Run or Debug. The launcher creates synthetic secrets in a private temporary directory and a unique sophikron-tests-<random> Compose project. It reuses compose.yaml and compose.local.yaml without reading .env, builds/starts PostgreSQL and the API, waits for migrations and health, then runs all backend tests locally, including PostgreSQL integration tests. Docker assigns free loopback-only ports; no fixed ports or local secrets need configuring.

The launcher removes its containers, networks, volumes and project image tags in a finally block, including after test/startup failures and normal interruption. It then removes its temporary secrets. Development containers, volumes and secrets are never selected. Docker build cache may remain for faster subsequent runs. If Docker becomes unavailable or the process is forcibly killed, cleanup cannot be guaranteed: the console prints the exact disposable project name for manual recovery.

Pytest runs in the Python configuration's process, so Debug supports breakpoints in tests and API services called through ASGI. The output is a pytest console summary rather than the IDE's pytest tree. The live API process remains in Docker; debugging that process requires a separate setup. The first run may take longer while Docker builds images. By default only backend services/tests run. Set BFF_INTEGRATION=1 for the real HTTP frontend journey, and additionally BFF_BROWSER_INTEGRATION=1 for Playwright desktop/mobile interactions using installed Edge (BFF_BROWSER_CHANNEL can select another installed Playwright channel).

Normal local startup uses docker compose up -d --build from the repository root. Compose runs the migration service before the API. A fresh installation requires AUTH_BOOTSTRAP_USERNAME and a mounted bootstrap password; complete it through POST /api/v1/auth/setup. The installation secret is separate from permanent passwords: it may be simple or empty. New permanent passwords require 10–128 ASCII characters with lowercase, uppercase, digits and punctuation. Login failure budgets are configurable through AUTH_LOGIN_IP_LIMIT (20), AUTH_LOGIN_IDENTITY_LIMIT (5 per IP/identifier) and AUTH_RATE_WINDOW_SECONDS (900). Successful logins do not consume or reset these budgets. Authentication/admin bodies are capped at 16 KiB before JSON parsing, and password-worker queues are bounded. See the authentication guide for overload responses and baseline schema compatibility. Swagger documents the X-CSRF-Protection header (enter 1 on writes), and uses the browser cookie automatically.