# AGENTS.md

REST API (Django + django-ninja) for managing the virtual domains, users and aliases that Postfix and Dovecot read
from the database. Deployed as mxapi.neuf.no.

## Setup and commands

Tools are managed by [mise](https://mise.jdx.dev) (Python, uv, prek) and Python deps by uv.

```sh
mise install            # Python, uv, prek
uv sync                 # deps + dev tools
prek install            # git hooks
uv run pytest           # tests, must keep 100% coverage
prek run --all-files    # ruff check, ruff format and file hygiene hooks
```

## Rules

- Use [Conventional Commits](https://www.conventionalcommits.org/) for commit messages, e.g.
  `feat: add alias search`, `fix(api): reject unknown domains`, `chore(deps): bump django`.
- Postfix and Dovecot query the `dpdapi_domain`, `dpdapi_alias` and `dpdapi_user` tables directly. Never rename
  tables or columns, or change how values are stored (addresses are lowercased, passwords are SHA-512 crypt).
  `tests/test_schema.py` guards this.
- Django stays on 5.2 LTS (and Python 3.14) until lynx has MySQL 8.4, which Django 6 requires.
- [mailadmin](https://git.neuf.no/edb/mailadmin) is the main API client. Don't change URLs, status codes or response fields it relies on;
  `tests/test_mailadmin_contract.py` replays its calls.
- Test the API through HTTP in `tests/`, using pytest and the fixtures in `tests/conftest.py`.
- Keep coverage at 100%; `pytest` fails below it.
- Production-only deps (`gunicorn`, `mysqlclient`) live in the `prod` dependency group. Production settings come from
  the environment (`dpdapisite/settings_prod.py`).