Shared architectural baseline for Rails 8 apps in this org. Every decision here has been validated across at least three production apps: toaster, voice-assistant, and evs-mapper.
Use this on day one of a new app. Fork the decisions that apply, skip the ones that don't, and record deviations as ADRs in your own docs/adr/.
| Document |
Purpose |
| BASELINE.md |
Quick-reference checklist — stack table, Dockerfile pattern, Compose pattern, gotchas |
| PLATFORM.md |
Full narrative — rationale, code snippets, and configuration detail for every decision |
| docs/adr/ |
Individual Architecture Decision Records |
| # |
Decision |
| 0001 |
Rails + Hotwire monolith; no separate frontend |
| 0002 |
GoodJob as background job queue |
| 0003 |
Postgres for queue, cache, and cable; no Redis |
| 0004 |
Coolify for deployment |
| 0005 |
Propshaft over Sprockets |
| 0006 |
jemalloc via LD_PRELOAD in Docker |
| 0007 |
TDD with RSpec + FactoryBot |
| 0008 |
Brakeman + Bundler Audit as mandatory gates |
| 0009 |
Pundit for authorization |
| 0010 |
Configurable storage provider (local / MinIO / S3) |
| 0011 |
Organization model from day one for future multi-tenancy |
| 0012 |
Browser testing with Capybara + Cuprite |
| 0013 |
Day-one themed landing page for early deployability |
| Concern |
Choice |
| Framework |
Rails 8+ (Hotwire monolith) |
| Language |
Ruby 3.4+ |
| Database |
PostgreSQL (Neon in prod; no Redis) |
| Jobs |
GoodJob |
| Cache / Cable |
solid_cache + solid_cable |
| Assets |
Propshaft + Importmap + Tailwind |
| Auth |
Devise |
| Authorization |
Pundit |
| Storage |
Active Storage — local / MinIO / S3 via STORAGE_PROVIDER |
| Deploy |
Coolify via Docker Compose |
| Testing |
RSpec + FactoryBot |
| Security |
Brakeman + Bundler Audit (CI gates) |
