# Repository Guidelines

## Project Structure & Module Organization
Core Django apps live at the repo root (`atlas_record_cleaner_report/`, `species_alert/`, `uksi_browser/`, `eventhub/` etc.), each with its own `models.py`, `views.py`, and `templates/` subtree. Shared configuration sits in `config/` plus `manage.py` at the root; reusable UI pieces live in `components/`, and global templates/static assets are under `templates/` and `staticfiles/`. Keep migrations beside their app, and place new assets in the matching app-level `static/<app>/` directory to avoid namespace collisions.

## Build, Test, and Development Commands
- `uv sync` — install or update Python dependencies from `pyproject.toml`/`uv.lock` (run after cloning or whenever deps change).
- `python manage.py migrate` — apply database changes before running the server or tests.
- `python manage.py runserver` — start the local server at `http://localhost:8000` with hot reload.
- `python manage.py test [app_label]` — execute Django tests; target a single app to keep feedback fast.
- `npm run minify:js` — rebuild the minified `habitats_and_biotopes` JavaScript bundle after editing `home.js`.

## Coding Style & Naming Conventions
Follow PEP 8 with 4-space indentation, 88-character lines, and snake_case module/function names. Keep Django models singular (e.g., `SpeciesAlert`) and use verbose, descriptive template names such as `species_alert/list.html`. Store settings in environment variables via `django-environ`; never hard-code credentials. Run formatters/linters in your editor or via `ruff`/`black` equivalents if configured locally before sending a PR.

## Testing Guidelines
Prefer Django’s `TestCase` and factory helpers in each app’s `tests.py` or `tests/` package. Name tests after behavior (`test_record_cleaner_flags_failed_records`). Maintain coverage across serializers, management commands, and views; add regression tests for every bug fix. Use `python manage.py test atlas_record_cleaner_report.tests.test_views` when iterating, then run the full suite before review.

## Commit & Pull Request Guidelines
Write short, imperative commit messages (“Add species alert filters”) and limit commits to a single purpose. Pull requests should summarize the change, link any issues, call out migrations or config updates, and include screenshots/CLI output for UI or management command changes. Highlight deployment steps (e.g., rerun `collectstatic`) so reviewers can verify quickly.

## Security & Configuration Tips
Secrets live in `.env`; create one via `./setup_config.sh` and set `APP_CONFIG_DIR` when deploying to shared hosts. Never commit `.env` or generated keys. Use `env.example` to document new settings and ensure new management commands fail fast when required env vars are missing.