106 lines
5.7 KiB
Markdown
106 lines
5.7 KiB
Markdown
# System overview
|
|
|
|
Status: architecture recommendation; locked product constraints are in
|
|
[PROJECT_VISION](../PROJECT_VISION.md). Only the local proof described in
|
|
[SIMULATION_ARCHITECTURE](SIMULATION_ARCHITECTURE.md) is implemented initially.
|
|
|
|
## System context
|
|
|
|
```mermaid
|
|
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
|
|
|
|
```mermaid
|
|
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 |
|
|
| accounting (`evo_accounting`, alias `evo::accounting`) | Typed finite inventories, atomic conserved transfers, in-memory action watermark | Chemistry, minting resources, entity lifecycle or durable storage |
|
|
| processes (`evo_processes`, alias `evo::processes`) | Synthetic source/producer rules and atomic process/accounting state | Live organism ancestry, persistence, heat recycling or external I/O |
|
|
| 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 |
|
|
|
|
Core, simulation, local snapshot codec, accounting, processes and `evo-sim` are source modules
|
|
in the proof. Accounting has an independent tested contract; it is not yet wired
|
|
into particle state. Future rows are boundaries, not empty directories or dummy services.
|
|
Split a library when a real independently tested contract exists.
|
|
|
|
The processes library now includes a shared feeding community (ADR-0026): producer
|
|
and consumer reservoirs have one owner, with heat/waste and activity flags committed
|
|
atomically. Standalone producer fixtures remain available for focused testing.
|
|
|
|
## Runtime topology and data flow (target)
|
|
|
|
```mermaid
|
|
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.
|