Files
aevolution/docs/architecture/SYSTEM_OVERVIEW.md
T
dingoandClaude Opus 5 d5b4bd068e Initial commit: architecture docs and headless engineering proof
Aeternalis Evolution, a custom-engine persistent evolutionary MMO.

This first commit establishes the project skeleton:

- Architecture and design docs: project vision, system overview,
  engineering constitution, roadmap, 19 ADRs, and the simulation,
  world, network, persistence and infrastructure architectures.
- Headless engineering proof: deterministic synthetic particles,
  component lifecycle, explicit PRNG streams, canonical snapshots
  and restored execution.
- Build and tooling: CMake 3.28+ / Ninja presets, C++23 feature
  check, clang-format and clang-tidy config, format check script,
  Windows check script, and a Docker build context.
- Tests: unit tests, benchmarks, a snapshot fuzz target and CLI
  integration wiring.

No gameplay, renderer, network service or running deployment yet.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-14 15:44:41 -04:00

5.0 KiB

System overview

Status: architecture recommendation; locked product constraints are in PROJECT_VISION. Only the local proof described in SIMULATION_ARCHITECTURE is implemented initially.

System context

flowchart LR
  Player[Player / Steam desktop client] -->|intentions| Game[Aeternalis world services]
  Steam[Steam identity provider] -->|validated identity| Game
  Operator[Operator] -->|approved GitOps release| Game
  Game -->|perceived state / outcomes / history| Player
  Game --> History[(Persistent world and phylogeny)]
  Game --> Telemetry[Metrics / logs / traces]
  Backups[Independent backup failure domain] <-->|verified archives / restore| History

Component and dependency boundaries

flowchart TD
  Client[Custom desktop client] --> Protocol[Protocol / prediction adapter]
  Region[Region process] --> Network[Transport / validation / interest]
  Region --> Persist[Persistence adapter]
  Region --> Sim[libevo simulation]
  Sim --> Biology[Genome / development / phenotype / ecology]
  Sim --> Environment[World / resources / sparse terrain interfaces]
  Sim --> Core[IDs / units / ticks / PRNG]
  Biology --> Core
  Environment --> Core
  Protocol --> Core
  CLI[evo-sim / tests / benchmarks] --> Sim
  Backend[Modular backend: identity / history / director] --> Persist
  Persist --> Stores[PostgreSQL / object store]
  Network --> Protocol

The renderer may consume phenotype and terrain views. Biology never consumes a mesh, graphics device, network session or database connection. Public simulation headers expose values and bounded commands, not third-party ECS/storage types. No Steam ID, socket, Kubernetes API, logger clock or storage handle belongs in the simulation state. Durable account references live in orchestration mapping.

Boundary Owns Must not own
core Value types, deterministic algorithms, explicit version constants Global state, threads, I/O
simulation (evo_simulation, alias evo::simulation) State, stable tick ordering, component lifecycle, pure restore validation Wall clock, transport, database or rendering
biology Genotype → development → phenotype; energetic transfers Account rewards, player/NPC subclasses
world Procedural base identity, spatial/environmental fields Dense planet allocation, gameplay authority
persistence Durable metadata, snapshots, replay batches, migration Per-tick simulation decisions
network Input validation, authentication boundary, bounded codecs and relevance Trust in client-provided positions or biology
backend Identity adapters, account/world metadata, history queries, directory/lease coordination Every noun deployed as a service
app / server Tick pacing, I/O ownership, durable outcome barrier, metrics export Alternative biological implementation

Only core, simulation, local snapshot codec and evo-sim are source modules in the proof. Future rows are boundaries, not empty directories or dummy services. Split a library when a real independently tested contract exists.

Runtime topology and data flow (target)

flowchart LR
  Client[Client] -->|HTTPS identity / world selection| API[Backend API]
  API -->|session and routing grant| Client
  Client -->|authenticated input channel| Worker[Region worker]
  Director[Director] -->|assignment hint| Worker
  Worker -->|fenced lease / commit| PG[(PostgreSQL)]
  Worker -->|immutable snapshots| S3[(Object store)]
  Worker -->|tick-boundary commands| Sim[In-memory simulation]
  Sim -->|events and views| Worker
  Worker -->|perception-filtered snapshots / durable outcomes| Client
  PG -->|transactional outbox| Bus[Optional JetStream]
  Bus -->|idempotent projections| History[History queries / ecology jobs]

Simulation reads an immutable ordered command batch at a tick boundary. It emits state and domain outcomes. The host stages durable records and marks an outcome committed only after the durable barrier. Projection notifications are not the source of authority. Simulation metrics are deterministic counters; timing and tracing are measured outside the simulation.

Failure containment

  • Worker crash: recover a consistent snapshot plus complete committed replay range under a new lease epoch. Never accept an old worker's writes.
  • Database unavailable: stop durable decisions and eventually pause simulation; do not continue granting irreversible uncommitted outcomes.
  • Object storage unavailable: retain/retry bounded pending snapshots; enforce journal/storage budgets rather than silently dropping recovery data.
  • Backend unavailable: availability degrades separately from existing regions, within session and lease policies. This does not grant workers perpetual authority.
  • Shared-host outage: all initial workloads can stop. Off-host recovery is an explicit operations requirement, not a benefit Kubernetes provides by itself.

See persistence, network and infrastructure architecture for detailed contracts.