Heatwave

E-commerce platform for WarmlyYours radiant heating products. Built
with Ruby on Rails 7.2, PostgreSQL 16, 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. Install pinned toolchain (Ruby, Node, Python, uv via mise)
mise install

# 3. Run automated setup
bin/setup

# 4. Configure database
cp config/database.yml.example config/database.yml

# 5. Add master key (1Password → IT Vault → heatwave-master-key)
echo "your-master-key" > config/master.key

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

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, …)
├── 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 + skills/)

Essential reading

Document What's in it
Skills index Code conventions, organized by area (Rails, Hotwire, CRM, etc.)
Commit Conventions Commit type/scope taxonomy
Asset Build Workflow Frontend build + asset pipeline
Test Suite Guide Minitest workflow + COVERAGE=1
MCP Database Access AI-assisted DB queries via MCP

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, .cursor + .claude)

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

  • AGENTS.md is the canonical instruction file
    (agents.md convention). CLAUDE.md is a
    symlink to it.
  • skills/ holds 46+ skill packs (Agent Skills
    spec    ). .claude/skills and
    .cursor/skills are symlinks → ../skills.
  • .cursor/rules/ keeps Cursor-specific alwaysApply rules. Their
    bodies are inlined into AGENTS.md so non-Cursor agents see them
    too.

MCP servers

Single source of truth: .mcp.json (committed),
populated from 1Password by script/setup_mcp_servers.sh. See
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: full setup in
doc/infrastructure/README-UBUNTU.MD.

Manual Setup Steps

Not automated by bin/setup:

  1. GitHub SSH key — Generate ed25519
  2. Master key — 1Password (IT Vault → heatwave-master-key)
  3. MCP credentials — script/setup_mcp_servers.sh (then direnv allow)
  4. Database restore (optional) — script/docker_restore.sh ~/Downloads/backup
  5. Tailscale VPN — required for deployment access
  6. Server SSH access — add your public key to production servers

See Troubleshooting Guide
for common setup issues.

Tech Stack

Component Version Notes
Ruby 3.4.7 Pinned via mise. YJIT enabled in prod/staging (off in dev — see config/initializers/000__yjit.rb)
Rails 7.2.3
Node.js 24.8.0 Pinned via mise
Yarn 4.x Via Corepack
Python 3.12 For MCP servers (postgres-mcp, etc.)
PostgreSQL 16 Via Docker (docker/volumes/...)
Bootstrap 5.3
Font Awesome 7 Pro
Sidekiq 7.x Background jobs

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