# Repository Guidelines

## Project Structure & Module Organization

RF4 Spotter is an Astro/FastAPI/PostgreSQL application with an offline
research and media-ingestion toolkit. The main areas are:

- `apps/api/` — FastAPI application, routers, models, migrations, and API tests.
- `apps/web/` — Astro pages, components, styles, unit tests, and Playwright tests.
- `rf4_research/` — source parsers, media manifest tooling, and CLI commands.
- `tests/` — Python research/tooling tests and fixtures.
- `data/media/` — versioned manifest and content-addressed local media files.
- `docs/` — specification, roadmap, ADRs, runbooks, and acceptance procedures.
- `compose.yaml` — local PostgreSQL, API, web, and supporting services.

Keep generated reports and temporary downloads outside committed paths unless a
task explicitly requires versioning them.

## Build, Test, and Development Commands

From the repository root:

```bash
.venv/bin/pytest -q                         # Python suites
npm --prefix apps/web run check             # Astro type/template checks
npm --prefix apps/web run build             # Check and production build
npm --prefix apps/web run test:unit         # Web unit tests
WEB_URL=http://127.0.0.1:4321 npm --prefix apps/web run test:e2e
docker compose up --build                   # Full local stack
```

For media work, use `.venv/bin/python -m rf4_research.media_cli --audit` and
respect the manifest’s cooldown and approval states. Do not hotlink or replace
approved media without explicit review.

## Coding Style & Naming Conventions

Use four-space indentation for Python and two spaces for Astro/TypeScript.
Prefer typed Python functions, `snake_case` for Python identifiers, and
`camelCase` for TypeScript variables/functions. Astro components use
`PascalCase.astro`; tests use descriptive `test_*.py` or `*.test.ts` names.
Keep UI text and data-source labels explicit and accessible; run `astro check`
before committing web changes.

## Testing Guidelines

Add focused regression tests beside the affected suite. Python tests use
pytest; web behavior uses Node unit tests and Playwright. Run the smallest
relevant test first, then the full suite before handoff. Never use live external
sources in tests; use fixtures or isolated Docker services.

## Commit & Pull Request Guidelines

Use imperative, concise commit subjects with the repository’s existing scope
style, such as `feat:`, `fix:`, `data:`, or `chore:`. Keep commits focused and
exclude unrelated user files. Pull requests should describe behavior changes,
verification commands, migration or configuration impact, and screenshots for
visual/UI work. Call out any media provenance, approval, or rollback decision.

## Security & Configuration Tips

Do not commit secrets, production `.env` files, tokens, or private payloads.
Use local fixtures and documented environment variables. Preserve the strict
CSP, admin authentication barriers, source attribution, and media provenance
when changing application code.