CYBERIA
**Network Object Layers**
_Stackable Rendering Layers as a Unified Tokenized Reality_
[](https://www.npmjs.org/package/cyberia)
Cyberia is an MMORPG extension built on the Underpost Platform. The platform owns the
toolchain, deployment surface, PWA delivery, and base infrastructure. Cyberia adds a three-service MMO
runtime: `engine-cyberia`, `cyberia-server`, and `cyberia-client`.
`engine-cyberia` is the **sidecar-backed data layer**: a Node.js sidecar that owns content,
validation, persistence, the gRPC/REST data services, and asset metadata. It backs the authoritative
Go server and the WASM client with data — it does not run the simulation or the presentation.
---
## Ecosystem at a glance
```text
┌───────────────────────────────────────────────┐
│ UNDERPOST PLATFORM │
│ toolchain · deploy · PWA build · static │
│ delivery · cluster/image/db · monitoring │
│ │
│ underpost CLI ──▶ builds & deploys all │
└───────────────────────────────────────────────┘
│ hosts / delivers
▼
╔═══════════════════════════════ CYBERIA MMO ══════════════════════════════════╗
║ ║
║ ┌──────────────────┐ gRPC ┌──────────────────┐ WebSocket ║
║ │ engine-cyberia │ ────────▶ │ cyberia-server │ ───────────┐ ║
║ │ (Node.js) │ │ (Go) │ │ ║
║ │ │ │ │ ▼ ║
║ │ content │ │ authoritative │ ┌──────────────────┐ ║
║ │ validation │ │ simulation │ │ cyberia-client │ ║
║ │ persistence │ │ world tick │ │ (C / WASM) │ ║
║ │ gRPC/REST data │ │ AOI replication │ │ │ ║
║ │ asset metadata │ │ │ │ rendering │ ║
║ └──────────────────┘ └──────────────────┘ │ input │ ║
║ │ │ prediction │ ║
║ └──────────────── REST (content/assets) ─────▶│ presentation │ ║
║ └──────────────────┘ ║
╚═══════════════════════════════════════════════════════════════════════════════╝
One source of truth per concern:
content & world config ── engine-cyberia
real-time world state ── cyberia-server
presentation & input ── cyberia-client
```
---
## 1. Toolchain and base infrastructure
Underpost Platform is the operational backbone and the source of truth for deploy IDs, runtime
selection, host/path layout, generated client assets, and environment resolution.
| Area | What it owns |
| --------------- | ------------------------------------------------------------------------------------ |
| Toolchain | `underpost` CLI, build, deploy, release, metadata, secrets, environment selection |
| Infrastructure | bare metal, LXD, Kubernetes, K3s, kubeadm, images, SSH, runners |
| Data operations | MongoDB, MariaDB where needed, backups, cron, monitoring |
| Delivery | static build, SSR views, PWA packaging, service worker generation, host/path routing |
`underpost` is the shared control surface for everything infrastructural. Cyberia-specific work belongs
in the `cyberia` CLI, never in parallel platform commands. When a concern already exists in `underpost`,
reuse it instead of forking a Cyberia variant.
---
## 2. PWA workflow
Every deployed client ships as a static application shell with PWA support. The pipeline has exactly two
inputs:
- the deploy `ssr` configuration in `conf.dd-*.js` (or `conf.ssr.json`)
- the service worker source in `src/client/sw/core.sw.js`
Everything else — `index.html` pages, `sw.js`, the precache list — is **generated** during the client
build. Treat them as outputs only; never hand-edit them.
Runtime service-worker behavior:
| Request | Strategy |
| ------------- | -------------------------------- |
| static assets | stale-while-revalidate |
| API `GET` | network-first + short cache |
| API mutations | network-only + background replay |
| navigation | network-first + fallback shells |
Fallback selection: offline network → offline fallback view; origin/server failure → maintenance
fallback view. Only fallback-marked views are guaranteed precached.
---
## 3. Cyberia MMO extension
### Responsibility split
| Service | Owns | Must not own |
| ---------------- | ------------------------------------------------------------------------- | --------------------------------------------- |
| `engine-cyberia` | content, validation, persistence, gRPC/REST data services, asset metadata | authoritative simulation, render policy |
| `cyberia-server` | authoritative simulation, world tick, gameplay mutation, AOI replication | content authority, presentation metadata |
| `cyberia-client` | rendering, input, prediction, interpolation, presentation | authoritative world state, gameplay authority |
Two boundaries are non-negotiable:
- Do not move authoritative logic into the client.
- Do not move content-authority logic into the Go runtime.
### Data flow
```text
engine-cyberia ──gRPC──▶ cyberia-server ──WebSocket──▶ cyberia-client
engine-cyberia ──REST──────────────────────────────▶ cyberia-client
```
### `engine-cyberia` as the sidecar-backed data layer
`engine-cyberia` is the only Cyberia service that owns content-backed data and asset metadata.
- Boot-time world configuration flows from `engine-cyberia` to `cyberia-server` over gRPC `GetFullInstance`.
- Client-facing assets, object layers, dialogues, and presentation hints flow from `engine-cyberia` to `cyberia-client` over REST.
- Simulation never migrates into the sidecar, and presentation policy never migrates out of the client.
### Runtime / health model
Three supervised processes run in parallel, each with its own monitor and reconnect loop. Gameplay is live only when all three are healthy at once.
```text
┌──────────────────────────────────────────────────────────────┐
│ SUPERVISION (parallel) │
│ │
│ engine-cyberia cyberia-server cyberia-client │
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
│ │ monitor │ │ monitor │ │ monitor │ │
│ │ +reconnect │ │ +reconnect │ │ +reconnect │ │
│ └─────┬──────┘ └─────┬──────┘ └─────┬──────┘ │
│ │ │ │ │
│ └──────────┬──────────┴──────────┬──────────┘ │
│ ▼ ▼ │
│ all three up & connected? │
└────────────────────────────┬─────────────────────────────────┘
│
┌─────────────────────┼─────────────────────┐
▼ ▼ ▼
┌───────────┐ ┌───────────┐ ┌───────────┐
│ HEALTHY │ │ DEGRADED │ │ STANDBY │
│ all 3 up │ │ ≥1 service│ │ gameplay │
│ gameplay │ │ reconnect-│ │ paused │
│ live │ │ ing / down│ │ until all │
│ │ │ │ │ 3 healthy │
└───────────┘ └───────────┘ └───────────┘
```
| State | Meaning |
| ---------- | -------------------------------------------------------------------- |
| `healthy` | all three Cyberia services are up and connected |
| `degraded` | at least one service is reconnecting or unavailable |
| `standby` | gameplay is paused because the full three-service set is not healthy |
---
## User commands
Use `underpost` for platform, infrastructure, build, and deploy. Use `cyberia` for MMO content and
extension workflows. Both share the same helpers — never duplicate config, env, or path logic.
### Platform (underpost)
```bash
# Bootstrap a new app (local app serves on http://localhost:4001)
underpost new app-name
# Build the client bundle / static + PWA output
underpost client
npm run build # node bin client
# Deploy and operate
underpost deploy