# AGENTS.md — IDRS API server

Project conventions and operational gotchas for agents working in this repo.

## Layout
- `app/main.py` — FastAPI app: public endpoints `GET /api/getTokenInfo`, `GET /api/version/android`, `GET /img/token/<filename>`; mounts `/static`; startup calls `db.init_db()`.
- `app/admin.py` — sqladmin panel: `TokenAdmin` (custom WTForms form, `on_model_change`), `VersionAdmin`, `create_admin(app)`. Upload icons saved under `app/static/icons/token/` with `iconUrl = {IDRS_PUBLIC_URL}/img/token/<filename>`.
- `app/models.py` — SQLAlchemy `Token`/`Version`, engine, `SessionLocal`, `ICON_DIR`, `DB_PATH` (env `IDRS_DB_PATH`).
- `app/db.py` — seed from `tokenList.json`/`versionAndroid.json` (once, empty DB only).
- `app/auth.py` — `AdminAuthBackend`, fail-closed creds.
- `tokenList.json` / `versionAndroid.json` — seed source (read-only after seed).

## Environment / secrets
- `.env` (gitignored) → `ADMIN_USERNAME`, `ADMIN_PASSWORD`, `IDRS_PUBLIC_URL` (default `https://idrs.databisnis.id`). Test creds `admin`/`testpass123` — change before exposure.
- `.session_secret` (gitignored, auto-generated 0600) if `IDRS_SESSION_SECRET` unset.
- NEVER bake `.env` into the Docker image; pass via `--env-file` / `-e`.
- Untracked, never commit: `.env`, `.session_secret`, `idrs.db*`, `venv/`, `app/static/icons/*`.

## Run (local)
- `./run.sh` loads `.env` then `uvicorn app.main:app --host 127.0.0.1 --port 8000`.
- Start detached: `setsid nohup ./run.sh < /dev/null > /tmp/opencode/idrs.log 2>&1 & disown` (plain `&` hangs).
- Sanity-import: `./venv/bin/python -c "from app import main; print('IMPORT_OK')"`.

## Docker
- `docker build -t idrs-api .`
- Run with volumes: `-v idrs-data:/app/data -v idrs-icons:/app/app/static/icons`, env via `--env-file .env`.
- MUST use a single uvicorn worker (in-memory starlette sessions → `--workers >1` breaks login).
- DB + uploaded icons persist in the volumes across container recreate; code changes need an image rebuild.

## Verification
- curl login: `POST /admin/login` with `-c/-b` cookie jar; then curl admin endpoints / uploads with the jar.
- Assert `/img/token/<f>` returns `image/png`; HTML/oversize uploads rejected (400).

## Operation gotchas
- NEVER `pkill -f uvicorn` broadly — a separate user process runs uvicorn on port 7000. Kill only the port-8000 PID (`ps -ef | grep "uvicorn app.main:app --host 127.0.0.1 --port 8000"`).
- Local server binds 127.0.0.1:8000. Host ports 8080/8100 are taken by other services.

## Spec
- Canonical invariants and task status live in `SPEC.md` (§V invariants, §T tasks, §B bug log). Keep it updated when behavior changes; check §V before modifying.