Guidance for coding agents working in this repository.
## Project Overview
Jama is a Django application for media/resource storage, metadata, IIIF/HLS processing, RPC APIs, and UI views.
Important source packages live under `src/`:
-`jama`: Django settings, CLI entry point, shared project wiring.
-`resources`: core models, ACL, file handling, media helpers, management commands.
-`rpc`: RPC methods, serializers, views, tests, and API-facing behavior.
-`annotations`: annotation model and tests.
-`iiif` and `hls`: derived media serving/processing.
-`ui`: Django UI plus a Vite/Yarn frontend under `src/ui/front`.
## Common Commands
Prefer the project commands already defined in the `Makefile`.
- Install/update dependencies: `uv sync`
- Run migrations: `uv run jama migrate`
- Run development services: `make run`
- Format: `make format`
- Full test suite: `make test`
- Focused Django tests: `JAMA_VAR_DIR=.jama_data uv run jama test rpc`
- Lint one file: `uv run ruff check src/rpc/methods.py`
- Format one file: `uv run ruff format src/rpc/methods.py`
- Build package: `make build`
`make test` runs from `src/` with `JAMA_VAR_DIR=.jama_test_data` and an in-memory SQLite database, then removes `.jama_test_data`. When running tests manually with another `JAMA_VAR_DIR`, remove that generated directory after the test run as well.
## Environment Notes
- Runtime/test data is controlled by `JAMA_VAR_DIR`.
- Local scratch data such as `.jama_data/`, `.jama_test_data/`, caches, virtualenvs, and frontend `node_modules` should not be committed.
- Clean up generated `JAMA_VAR_DIR` directories after tests unless the user explicitly wants to inspect them.
- If a command needs access to the shared `uv` cache outside the workspace, rerun it with the appropriate approval instead of changing dependency paths.
- Avoid destructive cleanup unless explicitly requested. Generated local data may belong to the user or a previous run.
## Code Style
- Python code is formatted and linted with Ruff.
- Keep edits ASCII unless the file already uses non-ASCII or the text/domain requires it.
- Prefer explicit, descriptive local names over one-letter variables.
- Keep comments sparse and useful; explain non-obvious behavior, not routine assignments.
- Follow existing Django patterns in the touched app before introducing new abstractions.
## Django/RPC Conventions
- RPC methods live in `src/rpc/methods.py`; every public RPC function receives `user: User` as its first argument.
- RPC return values must be JSON-serializable.
- Reuse `ServiceException` and constants from `rpc.const` for RPC errors.
- Use `UserAccess` for ACL checks before exposing or mutating project data.
- Prefer existing serializers in `src/rpc/serializers.py` for API response shape.
- When optimizing ORM queries, account for every field touched by serializers, ACL checks, model properties, and `select_related()` connector fields. Deferred fields can silently add queries.
- Use `select_related()` for single-valued relations and `prefetch_related()` for many-valued relations when serializing lists.
## Database And Migrations
- Models are primarily in `src/resources/models.py` plus app-specific model files.
- Run focused tests after model/query changes; query optimizations can affect lazy loading in serializers.
- For migration checks, use the local Django CLI with the same environment style as tests, for example `JAMA_VAR_DIR=.jama_data uv run jama makemigrations --check --dry-run`.
## Frontend
- The Vite frontend is in `src/ui/front`.
- Build it with `make build-ui-front`.
- Do not commit `src/ui/front/node_modules`.
## Verification Expectations
For Python-only changes, run at least:
-`uv run ruff check <changed files>`
- Relevant `uv run jama test ...` target
For broad/shared behavior, prefer the full `make test`.
