Technical overview

Implementation details and Open-Source tools

Technical detour ahead: this page explores the engineering behind the scenes — ideal for anyone who enjoys clean architectures, open-source and the warm glow of a passing test suite. If that sounds like you, welcome home.

Framework: Ruby on Rails

HeadScratcher runs on Rails 8.1, using a modern, dependency-light configuration.

  • Importmap for JavaScript dependencies — no Node, no Webpack
  • Turbo + Stimulus for real-time UI interactions
  • SolidQueue / SolidCable for background jobs and live updates

Rails 8 provides an extremely fast boot time, reduced infrastructure complexity, and excellent support for browser-native ES modules — ideal for a performance-sensitive puzzle interface.

User Interface

Because HeadScratcher uses Rails 8 with importmap, the frontend remains lightweight and fast, using modern browser-native techniques without the need for heavy JavaScript frameworks. This keeps the interface simple, responsive and easy to maintain while still delivering a polished, high-performance experience.

Tailwind CSS

The site uses Tailwind CSS for layout and styling. Tailwind v4 provides a fully-modern, compiled CSS engine with a significantly smaller footprint, native CSS variables and fast class-based styling without custom build tooling.

Tailwind is responsible for:

  • Responsive layout of the Sudoku grid and puzzle pages
  • Dark mode support via class toggles and CSS variables
  • Consistent typography and spacing across the site
  • Lightweight, utility-first styling
  • Print-friendly layouts for solution pages

ActiveAdmin

An internal administration interface built with ActiveAdmin enables:

  • Puzzle schedule management
  • Book metadata management
  • User moderation
  • Performance dashboards
  • Background job visibility

PWA Support

HeadScratcher is optimised as a Progressive Web App with:

  • Home screen install
  • Full-screen layout
  • Mobile-friendly Sudoku grid rendering

Open-Source Sudoku Hint Engine

HeadScratcher uses a custom-built, human-style Sudoku hint engine that evaluates a puzzle step-by-step using the same logical techniques real solvers apply.

The engine is now available as an open-source JavaScript module: SudokuHints

This powers the hint system on the Daily Sudoku page and supports all of the techniques needed to solve HeadScratcher puzzles:

  • Full House
  • Naked Single
  • Hidden Single
  • Pointing
  • Claiming / Box–Line Reduction
  • Naked Pairs, Triples, Quads
  • Hidden Pairs, Triples, Quads
  • X-Wing

Puzzle Book Generation (PDF)

HeadScratcher powers multiple Sudoku books published on Amazon KDP. These are generated programmatically using Ruby and the Prawn::PDF gem.

  • Formatting all of the puzzles in each book
  • Automatic typesetting and typography
  • Generate solution pages
  • Consistent print-ready margins and bleed settings
  • Supports multiple book sizes

Performance and Analytics

Ahoy (Event Tracking)

HeadScratcher uses Ahoy to track:

  • Puzzle plays
  • Hint requests
  • Completion events
  • Geographic distribution
  • Search term sources
  • Returning user behaviour

This enables detailed insight into the puzzle difficulty curve, user retention, and daily engagement patterns.

Rails Performance (Request Analysis)

The Rails Performance gem is used for real-time monitoring of request timings, database activity, throughput and memory usage.

The dashboard provides live insights during development and in production, making it easy to identify slow endpoints, track database-heavy actions, and verify overall system responsiveness.

Combined with importmap (no bundling), the site achieves sub-100ms server render times on Render.

Blazer (Internal Analytics)

HeadScratcher uses the Blazer gem to create query-driven analytics dashboards. Blazer allows the application to run SQL queries directly against PostgreSQL and present the results as tables, charts, time-series graphs, and exports.

Blazer is used for:

  • Daily traffic insights and puzzle engagement trends
  • Monitoring book sales data and category rankings
  • Tracking puzzle completion rates and hint usage
  • Performance diagnostics using historical logs
  • Internal reporting and long-term operational metrics

This provides a fast and flexible way to analyse data without adding heavy external BI tools.

Hosting & Infrastructure

HeadScratcher is hosted on Render, using a simple and reliable deployment architecture designed for fast response times and zero-maintenance operations.

Application Hosting

The Rails app is deployed as a Render Web Service, running in a containerised environment with automatic redeploys on every push to the main branch. Render handles build caching, dependency installation, SSL termination, and container health monitoring.

This setup provides a minimal-ops, developer-friendly environment with reliable performance, strong security, and predictable scaling characteristics.

Database

HeadScratcher uses PostgreSQL with automated backups, point-in-time recovery and zero-downtime restarts. PostgreSQL stores:

  • User accounts and authentication data
  • Puzzle metadata
  • Book information
  • Ahoy analytics events and visit/session data
  • Performance metrics and background job history

Redis (KeyDB)

Render’s Redis offering is built on KeyDB, a high-performance, multi-threaded Redis-compatible server. It is used for:

  • ActionCable connection state
  • SolidQueue / SolidCable notifications
  • Short-term caching
  • Real-time event distribution

Cron Jobs

Scheduled tasks (such as daily puzzle generation, sitemap regeneration and periodic cleanup tasks) run on Render Cron Jobs. These jobs execute Rails runners on fixed schedules without requiring separate infrastructure.

Content Delivery & Security

All public-facing traffic is proxied through Cloudflare, providing:

  • Global CDN caching of static assets
  • Image optimisation and edge caching
  • Automatic HTTPS and TLS 1.3 support
  • Bot protection and Web Application Firewall (WAF)
  • DDoS protection and rate limiting

Cloudflare ensures fast page delivery worldwide and helps protect the application from automated attacks.

Security

HeadScratcher benefits from the strong security posture provided by Ruby on Rails. Rails ships with secure-by-default protections that significantly reduce the risk of common web vulnerabilities:

  • CSRF protection on all non-GET requests, ensuring that form submissions and POST requests can only originate from trusted sessions.
  • Automatic HTML escaping in views to prevent cross-site scripting (XSS) by default. Rails templates render untrusted content safely unless explicitly marked otherwise.
  • Strong parameter filtering to prevent mass-assignment attacks and ensure only explicitly permitted attributes are accepted.
  • Secure session cookies with HTTP-only and same-site restrictions to protect against session hijacking.
  • SQL query sanitisation via ActiveRecord, preventing SQL injection in all non-raw queries.
  • Content Security Policy (CSP) support for controlling script, style, and asset sources.
  • Encrypted credentials using Rails’ built-in key management, ensuring API keys and secrets are never stored in plaintext.

Authentication & Password Security

User authentication is powered by Devise, which follows modern security best practices:

  • BCrypt password hashing with adaptive cost settings
  • Secure password reset workflows with expiring tokens
  • Brute-force protection via account lockout thresholds
  • Session invalidation on password changes

Platform-Level Security

Hosting on Render provides an additional layer of operational security:

  • Automatic HTTPS enforcement and certificate renewal
  • Isolated containers for application and background jobs
  • Automatic package updates during image rebuilds
  • Network-isolated PostgreSQL and KeyDB instances

Cloudflare WAF & CDN Security

All public traffic is routed through Cloudflare, which provides:

  • Web Application Firewall (WAF) rulesets blocking common attack vectors
  • DDoS protection at the network and application layers
  • Bot mitigation to protect forms and puzzle endpoints
  • Edge caching to reduce exposure of the origin server

Together, these Rails defaults and platform protections ensure that HeadScratcher operates with a strong security foundation, even as new features and systems are added.