Repository Guidelines

Project Structure & Module Organization

app/ holds the Rails application: controllers and views under feature-oriented folders, services/ for importers and background workflows, and policies/ for Pundit authorization.
app/javascript/ contains Stimulus controllers (controllers/), map widgets (maps/), and Tailwind/Turbo setup in application.js.
lib/ stores reusable support code and rake tasks, while config/ tracks environment settings, credentials, and initializers.
db/ carries schema migrations and data migrations; spec/ provides RSpec coverage; e2e/ hosts Playwright scenarios; docker/ bundles deployment compose files.

bundle exec rails db:prepare initializes or migrates the PostgreSQL database.
bundle exec bin/dev starts the Rails app plus JS bundler via Foreman using Procfile.dev (set PROMETHEUS_EXPORTER_ENABLED=true to use the Prometheus profile).
bundle exec sidekiq runs background jobs locally alongside the web server.
docker compose -f docker/docker-compose.yml up brings up the containerized stack for end-to-end smoke checks.

Follow default Ruby style with two-space indentation and snake_case filenames; run bin/rubocop before pushing.
JavaScript modules in app/javascript/ use ES modules and Stimulus naming (*_controller.js); keep exports camelCase and limit files to a single controller.
Tailwind classes power the UI; co-locate shared styles under app/javascript/styles/ rather than inline overrides.

Use bundle exec rspec for unit and feature specs; mirror production behavior by tagging jobs or services with factories in spec/support.
End-to-end flows live in e2e/; execute npx playwright test (set BASE_URL if the server runs on a non-default port).
Commit failing scenarios together with the fix, and prefer descriptive it "..." strings that capture user intent.

Write concise, imperative commit titles (e.g., Add family sharing policy); group related changes rather than omnibus commits.
Target pull requests at the dev branch, describe the motivation, reference GitHub issues when applicable, and attach screenshots for UI-facing changes.
Confirm CI, lint, and test status before requesting review; call out migrations or data tasks in the PR checklist.

Copy .env.example to .env or rely on Docker secrets to supply API keys, map tokens, and mail credentials.
Regenerate credentials with bin/rails credentials:edit when altering secrets, and avoid committing any generated .env or credentials.yml.enc changes.