# [App Name] · Rails 8 + Hotwire

A Rails 8 app. Hotwire for interactivity (Turbo + Stimulus). Tailwind v4 for styling. SQLite for prod (yes, really, Rails 8 made it viable).

## Source of truth
The deployed Kamal release is canonical. Code on GitHub. Database is SQLite with Litestream replicating to S3 for backup.

## Tech stack
Ruby 3.4 + Rails 8.0 + Hotwire (Turbo + Stimulus) + Tailwind v4. SQLite for DB, queue (Solid Queue), and cache (Solid Cache). Active Storage for uploads (S3 or local). Devise for auth (still the boring choice). Kamal 2 for deployment.

## Deploy
- Local: `bin/dev` (runs Procfile.dev: server, Tailwind watch, jobs)
- Production: `kamal deploy` (build image, push, restart). Provision via `kamal setup`.
- Database: SQLite file on persistent volume. Litestream sidecar for S3 replication.

## File map
- `app/controllers/` Rails controllers
- `app/models/` ActiveRecord models
- `app/views/` ERB templates (Turbo Frames + Turbo Streams)
- `app/javascript/controllers/` Stimulus controllers
- `app/javascript/application.js` Stimulus + Turbo entrypoint
- `app/jobs/` background jobs (Solid Queue)
- `db/schema.rb` (auto-generated, don't hand-edit)
- `config/deploy.yml` Kamal config
- `Dockerfile` Rails-optimized

## .env keys
- `RAILS_MASTER_KEY` (also in `config/master.key`, NOT committed)
- `S3_BUCKET`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` (Active Storage + Litestream)
- `RESEND_API_KEY` (or Postmark, SMTP, whatever)
- `RAILS_ENV` `production`

## Hard rules
- ActiveRecord callbacks are forbidden for anything beyond trivial validation. Use service objects.
- Background jobs via Solid Queue. Never block a request on a slow third-party call.
- Hotwire first. Reach for a JS framework only when Turbo + Stimulus can't express it.
- Migrations go forward AND backward (`change` method or explicit `up`/`down`). Tested with `rails db:rollback`.
- Authorization (who can do what) via `pundit` or `action_policy`. Never inline in controllers.
- `bin/setup` works on a fresh clone. If a new dev can't go from `git clone` to `bin/dev` in 5 minutes, it's broken.

## Recent significant changes
- 2026-05-10: Scaffolded. Locked: Rails 8 omakase (Solid suite, no Redis), Hotwire over React (less code), Kamal over Heroku (cost), SQLite over Postgres for v0 (Rails 8 made this real).

## Next session: start here
1. `rails new myapp --database=sqlite3 --css=tailwind --javascript=esbuild` if from scratch.
2. Set up Devise: `rails generate devise:install && rails generate devise User && rails db:migrate`.
3. Generate first resource scaffold. Click through, including the Turbo Stream paths.
4. Configure Kamal: edit `config/deploy.yml` with your server IP.
5. `kamal setup` to provision, `kamal deploy` to ship.