Disimula – A Party Game of Secret Missions

Disimula – Architecture

Five deployable pieces, three runtimes and one rule that shapes them all - players never reach the home server.

The pieces

Disimula is split by who uses it and where it can run:

PieceRuntimeWho uses itWhere it runs
landing/Next.js static exportanyoneCloudflare Workers static assets (disimula.app)
frontend/Next.js 16 standalone serversigned-in organizers and adminshome server, behind Cloudflare Access (organiza.disimula.app)
backend/Spring Boot 4.1 on Java 25only the frontend, the AI worker and Paddlehome server, never exposed directly
frontend/automation/Node.js 24nobody: it polls the backendhome server
online/Cloudflare Worker + Durable Objectsplayers' phones (no account)Cloudflare (jugar.disimula.app)

System overview

The landing page is plain files, so it is up even when the home server is not. The app sits behind Cloudflare Access and a tunnel. The online rooms live entirely on Cloudflare, so a game with 40 phones never touches the home connection, and the home server needs no inbound ports at all.

Backend: hexagonal, feature first

The backend packages "scream" the feature first, then the layer:

com.disimula
  missions/   themes, their variants (sets of missions), AI generations
  games/      games, players, dealing the decks, printable cards, online rooms
  users/      users, roles, registration, impersonation
  billing/    plans, passes, subscriptions, payments, promo codes
  stats/      the admin panel's numbers, read with SQL from the other features' tables
  shared/     kernel: domain errors, Permission, MissionPool, Plans; security, REST errors, config
    each feature/
      domain/          models, rules and ports. Plain Java.
      application/     use cases (services). Depend on domain only.
      infrastructure/  adapters: rest/, persistence/, pdf/, image/, paddle/, online/, seed/

Backend hexagonal architecture

ArchitectureTest (ArchUnit) turns these into build failures:

  • the domain uses no framework (no Spring, no JPA, no Jackson);
  • the application layer knows no adapters;
  • features only depend on shared, never on each other;
  • every method of every @RestController carries @PreAuthorize.

Features talk through ports in the shared kernel. Games need missions to deal, but do not know the missions feature: they ask shared.domain.MissionPool, which missions/ implements. Billing exposes Plans so that games can check a tier without importing billing. Deleting a user publishes UserDeleted, and each feature deletes what it owned.

Persistence

PostgreSQL 18 with 23 Flyway migrations that tell the story of the product (self-registration, private generations, AI credits, tiers and passes, a credit ledger, promo codes, payments, partial refunds, languages...). Simple aggregates use Spring Data JPA; anything that needs atomic updates or reporting queries (JdbcPassRepository, JdbcPaymentLedger, the stats read models) uses plain JDBC. A pass, for instance, is consumed with a single conditional UPDATE in the same transaction as the game that uses it, with a deferred foreign key so the game can be saved after.

API conventions

  • Everything under /api, times as epoch milliseconds.
  • Errors are RFC 9457 problem details with a stable code (not_enough_missions, plan_limit, generation_input_rejected...), which the frontend maps to messages in each language.
  • 402 plan_limit carries what was reached (limit), for which tier, and what is allowed, so the UI can explain the upgrade without guessing.

Testing

  • Unit tests for the domain (DeckDealerTest, GameTest, BillingTest, MissionsTest...).
  • *IT integration tests against a real PostgreSQL in Testcontainers, through the HTTP API.
  • CardPrintingTest renders a sheet of cards, reads every QR code back and leaves the PDF and PNGs in target/cards/ to look at.
  • PaddleWebhooksIT signs webhook payloads like Paddle does and checks idempotency, refunds and held passes.

Frontend: Next.js as a static shell and a proxy

The frontend is deliberately thin on the server:

  • All data is loaded in the browser; the server renders static shells, prerendered once per language under app/[lang].
  • The browser only calls /api/... on its own origin; Next rewrites it to the backend. No CORS, and the backend is never exposed.
  • proxy.ts (Next 16's middleware) serves the visitor's language without it showing in the URL: the disimula-lang cookie, else Accept-Language.
  • Code is organized by feature (features/games, features/billing, features/missions...), each with its types, a store (backend calls with a small in-tab cache) and components.
  • Texts live next to the code as defineMessages({ es, en, it }). Spanish is the reference and TypeScript checks the other two have the same shape, functions included.

The card editor is the most interesting piece of UI: a canvas the size of the printed back (bleed included) with a photo, cut-out stickers, text and freehand drawing, with undo and no library. Saving flattens it to a JPEG and uploads it as the player's photo, so the backend only ever stores one flat image.

Online games: a Worker that owns the room

online/ is a Cloudflare Worker plus a static React page (Vite, Tailwind 4):

src/shared/   protocol.ts (what travels), room.ts (the rules as pure functions), awards.ts
src/worker/   index.ts (routing + home-server auth), room-object.ts (the Durable Object)
src/app/      the players' page: join, hand, scores, organizer menu, summary
  • One Durable Object per room, addressed by its 6-character code (no 0/O, 1/I/L). It stores the state in its own SQLite, including the players' photos.
  • The rules are pure functions (shared/room.ts) shared by the Worker and the page and tested with Node's test runner. view() decides what each caller may see: a hand only goes to the phone that holds that profile, discarded missions are only counted until the end.
  • Phones get updates over one WebSocket each, with hibernation, instead of polling. A game of 40 players costs a few hundred requests.
  • A Durable Object alarm ends the game on time and later deletes the room (a week after it ends, a month after it opened if nobody finished it).

Online game sequence

The AI worker

A separate long-running Node.js process that claims generation jobs from the backend over HTTP, asks Claude for the missions, and hands the result back. It is covered in detail in AI.

Landing page

A static Next.js export served by Workers static assets: no Worker code, no server, no API. Its root index.html sends each visitor to their language, and its buttons lead to the app with that same language. It shares components (logo, mission cards, trailer) with the app by copy. The trailer has a cut per language, rendered from HTML compositions with HyperFrames (the trailer-*/ projects).