Building PuzzleProwl: How We Got Here
Building PuzzleProwl: How We Got Here
Every project has a day zero. This is ours.
PuzzleProwl didn't start with a fully formed plan, a team, or a roadmap carved in stone. It started with a simple frustration: puzzle apps that begin clean and slowly bury the experience under ads, forced accounts, and microtransactions for features that used to be free. That frustration became a decision to build something better.
This post covers everything that happened between that decision and today: the domain, the infrastructure, the social presence, the code repository, and the early design thinking that will shape the games themselves. It's part behind-the-scenes, part technical record, and part accountability document. A stake in the ground that says this is real and this is where it begins.
The Domain
The first real decision was the name.
PuzzleProwl.com wasn't the first idea. It was the right one. The name needed to be memorable, speakable, broad enough to grow beyond any single game, and available as a .com. After working through a long list of candidates (GridBrain, NoodleGrid, MindGrind, and a dozen others that were either taken or didn't quite land) PuzzleProwl clicked.
The alliteration helps. The verb helps more. "Prowl" implies active hunting, searching, the satisfying pursuit of a solution. That's exactly what solving a logic puzzle feels like when you're doing it right.
The domain is registered, SSL is configured, and the site is live. What you're reading right now is the first real content published here, which feels like the right kind of milestone to document.
The Infrastructure
The Server
PuzzleProwl runs on a Rocky Linux 10 server running Apache httpd. Rocky was a deliberate choice. It's a stable, enterprise-grade Linux distribution with long-term support, which matters for a project built to last. Apache was chosen for its maturity, its extensive documentation, and frankly because it's what I know well after three decades in IT infrastructure.
SSL is handled by Let's Encrypt via Certbot, which means certificates renew automatically and there's no annual cost or manual renewal process to forget about.
The Development Environment
Development happens locally in a WSL2 Ubuntu environment on Windows. WSL2 gives a genuine Linux development experience without leaving the Windows desktop, which means the gap between local development and the Rocky Linux production server is minimal. What works locally works on the server, which is exactly what you want.
The local workflow is intentionally simple: VS Code for editing, Live Server for instant browser preview on save, and no build tools or compilation steps. PuzzleProwl is built on vanilla HTML, CSS, and JavaScript. No frameworks, no bundlers, no npm dependency trees to maintain. Files go in, a browser renders them, and that's the whole pipeline.
This simplicity is a feature, not a limitation. It means less tooling to learn, less infrastructure to maintain, and a codebase that will still be understandable in five years without archaeology.
Alpha and Beta Environments
One of the first infrastructure decisions was to set up separate environments for different stages of development. The promotion path looks like this:
Local WSL2 dev → alpha.puzzleprowl.com → beta.puzzleprowl.com → puzzleprowl.com
Alpha is the unstable environment. New code lands here first, things break here, and early testing happens here before anything is ready for wider eyes. It's locked behind HTTP Basic Authentication so only I can access it.
Beta is the relatively stable environment. Code lands here after passing alpha testing, and trusted testers can evaluate new features before they go live. Also locked behind Basic Authentication, with a separate set of credentials.
Production is what you're on right now. Nothing reaches here without passing through alpha and beta first. That discipline matters even for a solo project, especially for a solo project where there's no second pair of eyes to catch mistakes before they go live.
Both alpha and beta are excluded from search engine indexing via robots.txt and are protected by Apache Basic Authentication, which means duplicate content won't pollute PuzzleProwl's search presence and accidental visitors won't find half-built features.
The Version Control
All PuzzleProwl code lives in a private GitHub repository with a three-branch structure designed for the four-environment promotion path:
- dev → mirrors alpha.puzzleprowl.com
- beta → mirrors beta.puzzleprowl.com
- main → mirrors puzzleprowl.com (production)
Day-to-day development happens on short-lived feature branches off dev.
When a feature is ready for alpha testing, it merges into dev. When
alpha testing passes, it merges into beta. When beta testing passes, it
merges into main and deploys to production.
Direct commits to main are blocked. Nothing goes to production without
passing through the full promotion chain. This is a discipline borrowed
from enterprise IT and applied to a hobby project, because good habits
don't cost anything and bad ones have a way of compounding.
Deployment is handled by simple rsync scripts that push the relevant branch to the appropriate server directory over SSH. No CI/CD pipeline yet. The project doesn't need one. A shell script is honest, fast, and entirely appropriate at this scale.
The Social Presence
Before writing a line of game code, the social handles were locked in across every platform likely to matter for a puzzle game site. An early lesson from building things on the internet: handles disappear fast, and consistency across platforms matters more than any individual platform's reach.
PuzzleProwl is now established on:
- Facebook — facebook.com/puzzleprowl
- X — x.com/puzzleprowlcom
- Instagram — instagram.com/puzzleprowl
- TikTok — tiktok.com/@puzzleprowl
- Threads — threads.net/@puzzleprowl
- Pinterest — pinterest.com/puzzleprowl
- Reddit — reddit.com/u/puzzleprowl
- Bluesky — bsky.app/profile/puzzleprowl.bsky.social
- YouTube — youtube.com/@puzzleprowl
- Patreon — patreon.com/puzzleprowl
Each platform has its own role in the distribution strategy. Reddit is where the puzzle community lives and where authentic engagement matters most. The plan is to be a genuine contributor to r/sudoku and related communities, not a broadcast account. YouTube will eventually host puzzle walkthroughs and solving strategy content. Bluesky is where the building-in-public updates will land, since its audience skews toward developers and people who appreciate that kind of transparency.
Patreon exists as an eventual support mechanism, a way for people who value what PuzzleProwl is building to contribute directly to keeping the games free for everyone else. It won't launch until Classic Sudoku is live and people have had a chance to experience the product.
The Email List
Email capture is handled through Kit, formerly ConvertKit. Anyone who leaves their email on the coming soon page or the home page is added to a launch announcement list. Not a newsletter, not a marketing sequence, just a single email when Classic Sudoku goes live.
Kit was chosen over simpler form-forwarding tools because it handles subscriber management, unsubscribe compliance, and list broadcasting properly. The legal requirements around bulk email (CAN-SPAM, GDPR) are real even for small lists, and using a proper platform handles them correctly from day one rather than retrofitting compliance later.
Domain authentication is configured with SPF, DKIM, and DMARC records, which means emails sent through Kit on behalf of puzzleprowl.com are properly authenticated and significantly less likely to land in spam folders. Getting this right at the start matters. Sender reputation is hard to rebuild once it's damaged.
Privacy and Policies
Privacy policy and terms of service are handled through Termly, which generates and maintains legally compliant policy documents and keeps them updated as regulations change. The cookie consent banner is also Termly, integrated directly with Google Analytics 4 to handle consent mode properly for GDPR and CCPA compliance.
These aren't afterthoughts. GA4 is in place from day one, which means the data collected during the coming soon phase (however sparse) is collected correctly and with proper consent infrastructure in place.
Analytics Strategy
Google Analytics 4 is configured on PuzzleProwl from the start, but standard pageview tracking alone won't tell us much about how people interact with puzzle games. The plan is to instrument specific events that actually reveal something useful:
puzzle_started — which variant, which difficulty level, which device type. This tells us where players begin and whether our difficulty labeling is calibrated correctly.
puzzle_completed — time taken, difficulty level, whether hints were used. This is the core engagement metric. Completion means the puzzle was neither too easy nor too frustrating.
puzzle_abandoned — how far through the solve the player was when they quit. Abandonment early in a solve suggests the puzzle was too hard or the interface too confusing. Abandonment late suggests something more specific went wrong.
hint_used — which cell, which difficulty level, how far into the solve. This is the critical monetization data point. Understanding where and when players reach for hints informs how hint pricing and availability should be structured.
puzzle_shared — when daily puzzle results get shared to social. This is the organic distribution mechanism and worth tracking carefully.
The difference between knowing "1,000 people visited today" and knowing "1,000 people visited, 340 started a puzzle, 180 completed it, 45 used a hint, and 12 shared their result" is the difference between a vanity metric and actionable data. The goal from day one is actionable data.
The Design Philosophy
No code has been written for the games yet. Before writing code, it's worth being clear about the design decisions that will shape everything that follows. These aren't technical decisions. They're philosophical ones, and getting them right early prevents expensive corrections later.
Mobile-First, Always
Every game will be designed for a 375px wide screen before anything else. That's the baseline for smaller phones: the iPhone SE, smaller Android devices. If it works beautifully at 375px, it works everywhere. If it's designed for desktop first and adapted for mobile second, it will always feel like a compromise on the device most players will actually use.
This has direct implications for grid layout. A 9x9 Sudoku grid on a 375px screen needs careful thought. Cells need to be large enough to tap accurately with a finger, digits need to be readable without zooming, and the input mechanism needs to work without a keyboard. These are solvable problems, but they need to be solved before the first line of CSS is written, not after.
Vanilla HTML, CSS, and JavaScript
No frameworks. No build tools. No dependencies beyond the browser itself.
This is a deliberate constraint, not a limitation. Frameworks like React and Vue solve problems that PuzzleProwl doesn't have at this scale. They add complexity, build tooling, and abstraction layers that obscure what's actually happening in the browser. Learning front-end development means learning what the browser actually does, not what a framework does on top of it.
The practical benefit is a codebase with zero external dependencies that can't break, no npm audit warnings, and files that any browser can run directly without compilation. The games will be fast, lightweight, and maintainable for years without dependency rot.
Progressive Web App from Day One
The manifest.json and service worker that make PuzzleProwl installable on Android home screens will be built alongside the first game, not added later. The cost is minimal: a manifest file and a small amount of service worker boilerplate. The benefit is significant. An installable PWA on Android is genuinely hard to distinguish from a native app in daily use, and it requires no app store, no developer account, and no 30% revenue cut.
iOS PWA support is more limited because Apple intentionally restricts what PWAs can do on Safari, but the baseline experience still works correctly. App store submission via Capacitor is a later option that wraps the existing web code without rewriting it.
Accessibility Is Not Optional
High contrast support, keyboard navigation, and screen reader compatibility will be built in from the start. Puzzle games have a broad age demographic and the older end of that demographic is exactly the audience that benefits most from accessibility features and is most likely to abandon a game that doesn't accommodate them.
Practically this means semantic HTML, proper ARIA labels on interactive elements, focus management that makes sense when navigating by keyboard, and color choices that pass WCAG contrast requirements. None of this is difficult to build in from the start. All of it is expensive to retrofit.
The Hint System
The hint system deserves its own section because it's both a UX decision and a monetization decision simultaneously.
The wrong hint system tells the player the answer. That's not a hint, that's a surrender, and it leaves the player feeling like they didn't really solve the puzzle.
The right hint system teaches the player something. It points to a technique, highlights a region of the grid where progress is available, and gives the player enough information to take the next step themselves. That's a hint worth paying for, and more importantly, it's a hint that makes the player a better solver and keeps them coming back.
The plan is a tiered hint system:
Level 1 - Region highlight — indicates which row, column, or box contains the next available move without specifying the cell or technique. This preserves the most solving satisfaction.
Level 2 - Cell highlight — indicates which specific cell can be solved next, without revealing the digit or technique.
Level 3 - Technique hint — names the technique that applies and highlights the relevant cells, without filling in the answer.
Level 4 - Solution step — fills in one cell and explains why. This is the full hint, reserved for genuine impasses.
Each level costs more than the last. Players who want to learn pay for Level 1 and Level 2. Players who are genuinely stuck pay for Level 3. Players who just want to finish pay for Level 4. The pricing structure reflects the value delivered at each level.
What Comes Next
The website is live. The infrastructure is in place. The repository is initialized. The social accounts are set up. The design philosophy is documented.
What comes next is the actual game.
Classic Sudoku is first. Not because it's the easiest to build, but because it's the right foundation. Every technique, every UI pattern, every infrastructure decision made while building Classic Sudoku will make every subsequent game faster and better to build.
The development will be documented here as it happens. Not polished retrospectives, but honest accounts of what was built, what broke, what was learned, and what changed as a result. If you're here for the puzzles, the games are coming. If you're here for the journey, pull up a chair. This is where it starts.
--- Christian
PuzzleProwl.com