66 lines
3.0 KiB
Markdown
66 lines
3.0 KiB
Markdown
# 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.
|