Heatwave

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

Quick Start

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

# 2. Run automated setup
bin/setup

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

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

# 5. Start development server
bin/dev

URLs:

• WWW: https://www.warmlyyours.me:3000
• CRM: https://crm.warmlyyours.me:3000

Project Structure

heatwave/
├── app/                    # Rails application
│   ├── controllers/        # WWW, CRM, API controllers
│   ├── models/             # ActiveRecord models
│   ├── views/              # ERB templates & components
│   ├── services/           # Business logic
│   └── javascript/         # Stimulus controllers
├── client/                 # Webpack frontend (JS/CSS)
├── config/                 # Rails & environment config
├── db/                     # Migrations, seeds, views
├── doc/                    # 📚 All documentation
├── script/                 # Utility scripts
└── test/                   # Minitest test suite

Documentation

📖 Documentation Index — Complete guide to all project documentation

Essential Reading

Document	Description
Team Coding Standards	Code conventions and best practices
Asset Build Workflow	Frontend build process
Test Suite Guide	Testing with Minitest
MCP Database Access	AI-assisted database queries

By Topic

• Development: doc/development/
• Frontend: doc/frontend/
• Infrastructure: doc/infrastructure/
• Features: doc/features/
• Troubleshooting: doc/troubleshooting/
• Changelogs: doc/changelogs/

Native System Dependencies

Some gems require native C libraries. Install these before bundle install.

Library	Purpose	macOS (Homebrew)	Ubuntu / Debian
zint	Vector barcode & QR generation (ruby-zint → hexapdf-extras)	brew install zint	sudo apt install zint
libvips	Image processing (Active Storage variants)	brew install libvips	sudo apt install libvips-dev
imagemagick	Legacy image processing	brew install imagemagick	see Ubuntu README
librsvg	SVG support for ImageMagick	brew install librsvg	sudo apt install librsvg2-2
ghostscript	PDF processing for ImageMagick	brew install ghostscript	sudo apt install ghostscript

macOS: All the above are in Brewfile — just run brew bundle after cloning.

Ubuntu/Production: Full setup steps in doc/infrastructure/README-UBUNTU.MD.

Manual Setup Steps

These require human action (not automated by bin/setup):

1. GitHub SSH Key — Generate ed25519 key
2. Master Key — Get from 1Password (IT Vault → heatwave-master-key)
3. Database Restore — Optional: script/docker_restore.sh ~/Downloads/backup
4. Tailscale VPN — Required for deployment access
5. 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	Managed by mise. YJIT enabled in production/staging (disabled in dev — see config/initializers/000__yjit.rb)
Rails	7.0.8
Node.js	24.8.0	Managed by mise
Yarn	4.x	Managed by Corepack
PostgreSQL	16	Via Docker
Bootstrap	5.3
Font Awesome	7 Pro

---

Questions? Check the Documentation Index or ask the team.