Heatwave

E-commerce platform for WarmlyYours radiant heating products. Built
with Ruby on Rails 8.1, PostgreSQL 18, and Bootstrap 5.3.

📚 Generated docs site: docs.warmlyyours.dev
— full YARD reference for app/ and lib/, project conventions,
architecture docs, and the agent skills library. Rebuilt on every
push to master.

Quick Start

# 1. Clone
git clone git@github.com:warmlyyours/heatwave.git
cd heatwave

# 2. One command. Installs the pinned toolchain (Ruby/Node/Python/uv via mise),
#    gems, JS deps, the Docker Postgres/Redis cluster, local TLS, and
#    config/database.yml — then, when 1Password is unlocked, writes
#    config/master.key + .env.mcp. Prepares the dev database once
#    config/master.key + config/database.yml exist.
bin/setup

# 3. Start the dev server
mise exec -- bin/dev

Two prerequisites bin/setup can't install for you: Homebrew (it
bootstraps everything else, including mise), and 1Password — the desktop
app with Settings → Developer → Integrate with 1Password CLI enabled, signed
into WarmlyYours with access to vault IT. With those, bin/setup also
pulls config/master.key and populates .env.mcp (config/database.yml is
generated regardless). It then prepares the dev database whenever
config/master.key + config/database.yml are present. If 1Password is locked
it skips the secret fetches and says so — unlock it and re-run bin/setup
(idempotent), or add config/master.key and run mise exec -- bin/rails db:prepare by hand.

URLs

All Ruby / Node / Yarn commands run via mise exec --. Bare
commands pick up the wrong system-installed toolchain. See
AGENTS.md for the full toolchain non-negotiables.

Project Structure

heatwave/
├── app/                Rails application (controllers, models, views, services, javascript)
├── client/             Webpack frontend (JS / SCSS)
├── config/             Rails + environment config
├── db/                 Migrations, seeds, structure.sql, scenic views
├── doc/                Curated long-form docs (architecture, features, ops, …)
├── .agents/skills/     Agent skill packs (agentskills.io spec) — also surfaced on the docs site
├── script/             Utility scripts (MCP setup, IDE setup, validators)
├── test/               Minitest test suite
├── AGENTS.md           Toolchain rules + hard-block commands for AI agents
├── CLAUDE.md           Symlink → AGENTS.md (Claude Code reads this)
└── CONVENTIONS.md      ERP YARD + Markdown documentation conventions

Documentation

  • 📖 Documentation Index — hand-curated TOC of every doc subdirectory
  • 📐 CONVENTIONS.md — YARD + Markdown style for Ruby docstrings
  • 🤖 AGENTS.md — toolchain, hard-block commands, code-deletion safety, migration safety, Zeitwerk rules, git commit technique. Required reading if you wire up any AI tooling against this repo.
  • 🌐 docs.warmlyyours.dev — generated reference site (YARD + curated doc/ markdown + .agents/skills/)

Essential reading

Document What's in it
Skills index Code conventions, organized by area (Rails, Hotwire, infra, etc.)
Commit Conventions Commit type/scope taxonomy
API & integration testing Minitest workflow + COVERAGE=1
System tests Playwright system-test suite
Safe migrations online_migrations + structure.sql

By topic

Per-deploy changelogs are tracked via GitHub releases and PR
descriptions. Don't add files under a doc/changelog* directory
— for durable engineering narratives, file under the right doc/
topic folder with a descriptive name. For staged work and follow-up
plans, use doc/tasks/ with the YYYYMMDDHHMM_NAME.md
timestamp convention.

AI Agents (MCP, skills, .claude)

Agent context is the same across Claude Code, Aider, and OpenAI Codex
CLI:

MCP servers

Single source of truth: .mcp.json (committed),
populated from 1Password by script/setup_mcp_servers.sh. See
.agents/skills/mcp-servers for the active
server list and per-environment access rules.

Worktree workflow

bin/wt <branch-name> bootstraps a per-branch worktree at
../heatwave_worktrees/<branch> with the right symlinks for
credentials, env files, and the shared docker volume.

Native System Dependencies

Some gems require native C libraries — install before bundle install.

Library Purpose macOS Ubuntu / Debian
zint Vector barcode + QR generation (ruby-zint, hexapdf-extras) brew install zint sudo apt install zint
libvips Image processing — resize, format convert, PDF raster (ruby-vips, dragonfly_libvips, phash-rb) brew install libvips sudo apt install libvips-dev
librsvg SVG rasterization (used by libvips) brew install librsvg sudo apt install librsvg2-2
poppler PDF rendering (used by libvips for PDF thumbnails) brew install poppler sudo apt install poppler-utils

macOS: All four are in Brewfile — brew bundle covers it.

Ubuntu / production: baked into the production Docker image (see
Dockerfile). The containerized deploy stack lives under
doc/infrastructure/kamal/.

Prerequisites & remaining manual steps

bin/setup handles the toolchain, dependencies, the Docker cluster, local TLS,
and config/database.yml — and, when 1Password is unlocked, config/master.key
and .env.mcp. What it can't do for you:

  1. Homebrew — install first; bin/setup aborts without it.
  2. 1Password CLI integration — desktop app → Settings → Developer →
    Integrate with 1Password CLI    , signed into WarmlyYours (vault IT). Without
    it the secret fetches are skipped; add config/master.key by hand (IT vault
    → heatwave-master-key) and re-run bin/setup --refresh-mcp.
  3. GitHub SSH key — generate ed25519.
  4. Tailscale VPN — required for any deploy, server SSH, or admin-dashboard access.
  5. Server SSH access — add your public key to the production hosts.
  6. Database with real data (optional) — bin/setup --restore-db instead of
    the empty db:prepare schema.

See the development setup troubleshooting guide
for common issues.

Tech Stack

Component Version Notes
Ruby 4.0.5 Pinned via mise. YJIT enabled in all environments incl. dev — see config/initializers/000__yjit.rb
Rails 8.1.3
Node.js 24.8.0 Pinned via mise
Yarn 4.x Via Corepack
Python 3.12 For MCP servers (postgres-mcp, etc.)
PostgreSQL 18 Via Docker (heatwave-postgres:18-noble)
Bootstrap 5.3
Font Awesome 7 Pro
Sidekiq 7.x Background jobs

Questions? Check the Documentation Index
or the generated docs site.