3.0 KiB
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:
.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.