Documentation
Overview
Architecture
Updated 2026-11-03
Architecture
The kit separates pure game logic from HTTP, persistence, authentication and presentation. That boundary is the reason the same engine can serve very different games.
Layers
| Layer | Location | Responsibility |
|---|---|---|
| Domain | app/Domain/Engine |
Pure, deterministic calculations: races, scoring, fusion, breeding, life cycle, requirements, simulations |
| Persistence | app/Models, database/migrations |
Eloquent models, additive migrations, seeders |
| Application | app/Services |
Orchestration, transactions, authorization-aware operations |
| HTTP | app/Http |
Controllers, requests, resources, policies, middleware |
| Admin | app/Filament |
Operator control plane |
| Web | resources/views, routes/web.php |
Public pages, game web, product documentation |
| Client | flutter/ |
Android and web client |
| API | routes/api.php |
Versioned /api/v1 contract |
Server authority
The client never chooses the authoritative seed, lineup outcome or result. The server:
- validates ownership, lineup and rules;
- selects or stores the task combination;
- calculates the result deterministically;
- persists a replay with the trace;
- grants rewards idempotently.
This keeps audits, replays and anti-cheat possible.
Theme contract
theme.yaml is the single source of vocabulary and game shape. The engine reads it at bootstrap. A theme pack also declares pack.yaml, label files and content seeders.
See Theme packs.
Versioning
- Mechanics profiles are versioned and activated atomically.
- Collectibles, traits, trials, results and content rules carry versions.
- Ability definitions and activations are versioned.
- The API is versioned under
/api/v1and checked by an OpenAPI parity test.
Documentation and tests
The repository keeps codebase/ maps, plan/ decisions and dated update notes. Tests cover domain algorithms, API contracts, authorization, OpenAPI parity, admin structure and runtime flows.
Deployment modes
The same codebase can run as:
- a game (default): the game web is served at the root;
- the product site (
PRODUCT_SITE_ENABLED=true): the marketing site is at the root and the player gameplay pages live under/demo.
This flag keeps the sales site from leaking into games built with the kit.