Disimula – A Party Game of Secret Missions
Full-stack SaaS for organizing a party game of secret missions, with AI-written missions, printable QR cards, real-time online rooms on Cloudflare and Paddle payments, self-hosted on a home server.
Disimula is a party game of secret missions. Every player gets their own deck of missions ("get someone to recommend you a western", "leave a book in the kitchen for 20 minutes without anyone asking about it") and has to complete them without the others noticing. Whoever completes the most wins.
The app is for whoever organizes the game: pick themes, list the players, and either print each player's cards or open a room that everybody joins from their phone. A printed mission is a QR code that any phone reads as plain text, and online each player only sees their own, so nobody (not even the organizer, who may be playing) sees anyone else's missions.

This page and the ones linked above are the technical documentation of the project: how it is built, deployed, secured, monitored and paid for.
At a glance
| Area | Stack |
|---|---|
| Backend | Java 25, Spring Boot 4.1, PostgreSQL 18, Flyway, PDFBox + ZXing, hexagonal architecture checked by ArchUnit |
| Frontend | Next.js 16 (App Router, static shells), React 19, Tailwind 4, three languages (es, en, it) |
| Online games | Cloudflare Worker + one SQLite-backed Durable Object per room, WebSockets with hibernation |
| AI | A Node.js worker that calls Claude: writer, evaluator and translator sessions |
| Payments | Paddle Billing as merchant of record: passes, yearly plans and AI credit packs |
| Infrastructure | A home server running Docker Compose behind a Cloudflare Tunnel; Cloudflare Access, Workers and R2, all declared with OpenTofu |
| CI/CD | GitHub Actions: tests and images on every push, automatic deploy to dev, one-click production of the exact images dev runs, on a self-hosted runner |
| Observability | Grafana, Prometheus, Loki and Alloy, provisioned from the repository; alerts to Telegram and an external heartbeat |
Design principles
A few rules shaped almost every decision in the project:
- Nobody reads the missions they may be dealt. Organizers and admins may play too, so no endpoint returns the missions of a catalog theme or of a game. They leave the backend only inside the PDF (as QR codes), or to the online room that shows each player their own. Two exceptions, by design: the author of a private set sees what they wrote, and an admin approving AI-written catalog missions sees a sample of five, never the full set.
- Players never reach the home server. Online games are played on Cloudflare. The home server only makes outgoing calls to open a room and to collect its result.
- Stay on free plans, and fail closed instead of billing. Every Cloudflare resource is on the free plan; the online Worker has no binding that can be billed by usage; AI usage is bounded by credits and one job at a time.
- Everything is code. Cloudflare resources (OpenTofu), the server's env file (generated by CI), dashboards and alert rules (provisioned Grafana): a new server, or a lost volume, loses history but never configuration.
- The backend checks everything. The UI hides what a role cannot do for clarity only; every endpoint must declare its permission, and a test fails the build if one does not.
The repository
A monorepo with one folder per deployable piece:
frontend/ Next.js app (UI) and the AI worker (frontend/automation)
backend/ Java / Spring Boot API + PostgreSQL
online/ Online games: a Cloudflare Worker and the players' page
landing/ The public landing page, static on Cloudflare
infra/ OpenTofu: the Cloudflare side of each environment
deploy/ Compose stacks for the home server, backups, observability
.github/workflows/ CI and deploy
Where to go next
- Architecture: the components and how the backend is organized.
- Features: what the app does, from dealing decks to printing cards.
- AI: how missions are written, evaluated and translated by Claude.
- Users and roles: sign-in, sign-up, permissions.
- Cloudflare and infrastructure: tunnel, Access, Workers, OpenTofu.
- Security: the threat model and the defences in each layer.
- CI/CD: from a push to dev, and to production.
- Payments and plans: tiers, Paddle, webhooks and the upgrade hooks.
- Monitoring and observability: logs, metrics, dashboards and alerts.
- Diagrams: every diagram in one place.