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:
| Piece | Runtime | Who uses it | Where it runs |
|---|---|---|---|
landing/ | Next.js static export | anyone | Cloudflare Workers static assets (disimula.app) |
frontend/ | Next.js 16 standalone server | signed-in organizers and admins | home server, behind Cloudflare Access (organiza.disimula.app) |
backend/ | Spring Boot 4.1 on Java 25 | only the frontend, the AI worker and Paddle | home server, never exposed directly |
frontend/automation/ | Node.js 24 | nobody: it polls the backend | home server |
online/ | Cloudflare Worker + Durable Objects | players' phones (no account) | Cloudflare (jugar.disimula.app) |
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/
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
@RestControllercarries@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_limitcarries what was reached (limit), for whichtier, and what isallowed, so the UI can explain the upgrade without guessing.
Testing
- Unit tests for the domain (
DeckDealerTest,GameTest,BillingTest,MissionsTest...). *ITintegration tests against a real PostgreSQL in Testcontainers, through the HTTP API.CardPrintingTestrenders a sheet of cards, reads every QR code back and leaves the PDF and PNGs intarget/cards/to look at.PaddleWebhooksITsigns 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: thedisimula-langcookie, elseAccept-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).
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).