Project structure:

mot.fastapi/
├── app/
│   ├── config/
│   ├── controllers/
│   ├── core/
│   ├── db/
│   ├── models/
│   ├── routes/
│   ├── security/
│   ├── services/
│   └── main.py
├── migrations/
├── scripts/
├── seeds/
├── tests/
├── alembic.ini
├── docker-compose.yaml
├── Dockerfile
├── pyproject.toml
├── pytest.ini
└── ruff.toml

Local development

Clone this repo snrub.api and the frontend snrub.client into a folder adjacent to each other.

In snrub.api Copy .env.example -> .env.development and fill in the values

Build with docker for local development

docker-compose up -d --build

API Documentation

API documentation is available via Scalar at:

http://localhost:8000/docs

Stop and remove the containers

$ docker compose down

Logs

Log output from the application:

docker compose logs -f api

docker compose logs -f client

Email in local development

Mailhog is used for password reset flows it can be accessed on

http://localhost:8025/

Migrations

Hit this endpoint with with token (must be super admin)

GET http://localhost:8000/api/admin/migrate

Or with Docker

To generate a new migration file, run the following command:

docker compose exec api alembic revision --autogenerate -m "Your migration message"

Run migrations:

docker compose exec api alembic upgrade head

Use Docker CLI to Access the Database

Connect to the PostgreSQL container:

docker-compose exec db psql -U postgres -d mot_database

Once connected, you can run SQL commands:

postgres=# SELECT * FROM users;  # View users table

Testing

Docker needs to be up and running for integration tests to work.

Run all tests

APP_ENV=test uv run pytest

Just run integration tests

APP_ENV=test uv run pytest tests/integration

Updating Seed Data

Export current dev DB state (new users + incident reports) to seed-friendly format:

docker compose exec api python scripts/export_seed_data.py

• New users are printed as dicts to append to seeds/data/users.py, photos written to seeds/data/photos/
• Incident reports are printed as the full INCIDENT_REPORTS list for seeds/data/incident_reports.py

Seeds run automatically on docker compose up. To re-seed manually:

docker compose exec api python -m seeds.seed_runner

Ruff Linting / formating

uv run ruff check . --fix
uv run ruff format .