140 lines
6.7 KiB
Markdown
140 lines
6.7 KiB
Markdown
# Architecture Overview
|
||
|
||
> High-level picture of Flying Jib. For deep detail see [developer_docs/ARCHITECTURE.md](../developer_docs/ARCHITECTURE.md).
|
||
> Update this file whenever the design changes (same PR as code/ADRs).
|
||
|
||
**Last updated:** 2026-07-30
|
||
**Design name:** Local Authority + Capability Tunnel + Federated Regions
|
||
**Runtime:** **Bare / Pear only** ([ADR-0013](../agent/ADRs/0013-bare-pear-only-runtime-and-distribution.md))
|
||
|
||
---
|
||
|
||
## Goals (non-negotiable)
|
||
|
||
1. **Never** master/central game servers we operate.
|
||
2. Every participant runs a **local** Minecraft server (Flying Squid) on **`127.0.0.1` only**.
|
||
3. Users launch a **single Bare/Pear distributable** — **no system Node.js**, no Node child process for Squid.
|
||
4. Worlds are **private** (capability invite) or **enrolled** into a mesh of linked regions.
|
||
5. Discovery and transport use **Hyperswarm / HyperDHT** only (public DHT bootstrap nodes are infrastructure, not app control planes).
|
||
6. CI releases produce **single standalone executables** (`bare-build --standalone`) plus Pear app-drive OTA (stage/seed/provision/multisig).
|
||
|
||
---
|
||
|
||
## System diagram
|
||
|
||
```text
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ Java Edition Client → 127.0.0.1:25565 (or configured) │
|
||
└───────────────────────────────┬─────────────────────────────────┘
|
||
│ TCP (Minecraft protocol, local only)
|
||
┌───────────────────────────────▼─────────────────────────────────┐
|
||
│ Flying Jib — single Bare executable / Pear app │
|
||
│ (no system Node.js, no Electron-as-default shell) │
|
||
│ ┌─────────────┐ framed IPC ┌─────────────────────────────┐ │
|
||
│ │ Main (Bare) │◄─────────────►│ Worker (Bare + pear-runtime)│ │
|
||
│ │ CLI / UI │ │ Hyperswarm / HyperDHT │ │
|
||
│ │ lifecycle │ │ Protomux / Autobase / OTA │ │
|
||
│ └──────┬──────┘ └──────────────┬──────────────┘ │
|
||
│ │ createMCServer via bare-node-runtime │ │
|
||
│ ┌──────▼──────────────────┐ ┌───────────────▼──────────────┐ │
|
||
│ │ Flying Squid (in Bare) │ │ World Tunnel (HyperDHT) │ │
|
||
│ │ host=127.0.0.1 only │◄──│ remote peers ↔ local MC port │ │
|
||
│ │ Anvil world on disk │ │ (byte pipe) │ │
|
||
│ └─────────────────────────┘ └──────────────────────────────┘ │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
▲ encrypted peer links (Noise / secretstream)
|
||
│ no app-operated matchmaking servers
|
||
other peers (same Bare architecture)
|
||
```
|
||
|
||
---
|
||
|
||
## Design pillars
|
||
|
||
### 0. Bare/Pear-only runtime ([ADR-0013](../agent/ADRs/0013-bare-pear-only-runtime-and-distribution.md))
|
||
|
||
- Production code runs on **Bare**.
|
||
- Flying Squid loads under **`bare-node-runtime`** (Node API → Bare modules), not `node` subprocess.
|
||
- Release: **`hello-pear-bare`** patterns + **`bare-build --standalone`** + Pear deploy layers.
|
||
- Electron Forge is **not** the default distribution path.
|
||
|
||
### 1. Local authority
|
||
|
||
Each peer’s Squid is authoritative for **its** world/region. There is no global block database and no single simulation spanning the mesh.
|
||
|
||
### 2. Capability tunnel (private worlds)
|
||
|
||
- Host listens on HyperDHT with a world keypair.
|
||
- Remote peers connect with an invite (`fj1.…`) and get a TCP byte pipe to the host’s loopback Squid.
|
||
- Java clients on every machine still only talk to their own localhost.
|
||
|
||
### 3. Federated regions (mesh)
|
||
|
||
- Peers **enroll** regions into a mesh registry (Autobase + Hyperbee view).
|
||
- Each region has bounds/offset, tunnel key, seed metadata.
|
||
- Crossing a border **migrates** the player session to the neighbor’s Squid.
|
||
|
||
### 4. Side-channel communication
|
||
|
||
Chat and presence use Protomux over Hyperswarm/DHT streams.
|
||
|
||
---
|
||
|
||
## Process model
|
||
|
||
| Role | Runtime | Responsibility |
|
||
|------|---------|----------------|
|
||
| Main entry | Bare | CLI/UI host, lifecycle, config |
|
||
| Worker | Bare + pear-runtime | P2P, tunnels, Autobase, OTA |
|
||
| Squid | Bare (+ bare-node-runtime) | MC simulation, Anvil, **127.0.0.1** |
|
||
|
||
---
|
||
|
||
## Distribution model
|
||
|
||
| Artifact | Tooling |
|
||
|----------|---------|
|
||
| Standalone binary per OS/arch | `bare-build --standalone` |
|
||
| P2P OTA app drive | pear stage → seed → provision → multisig |
|
||
| Upgrade channel | pear link in app metadata (`upgrade`) |
|
||
|
||
Users never install Node.js to play.
|
||
|
||
---
|
||
|
||
## Data at rest (sketch)
|
||
|
||
```text
|
||
$APP_STORAGE/
|
||
corestore/
|
||
identity/
|
||
worlds/<worldId>/anvil|meta.json|secrets
|
||
mesh/<meshId>/
|
||
invites/
|
||
```
|
||
|
||
---
|
||
|
||
## What we explicitly do not build
|
||
|
||
- Central matchmaking or “master mesh node”
|
||
- Fully replicated global voxel array
|
||
- Single authoritative multi-peer tick across all regions
|
||
- Public Minecraft TCP listen on WAN interfaces
|
||
- **System Node.js or Node child process as app runtime**
|
||
- Electron Forge as the **primary** shipping vehicle (optional experiment only with ADR)
|
||
|
||
---
|
||
|
||
## Related ADRs
|
||
|
||
- [0013 Bare/Pear only](../agent/ADRs/0013-bare-pear-only-runtime-and-distribution.md) ← **runtime & release**
|
||
- [0002 Flying Squid on Bare](../agent/ADRs/0002-choose-flying-squid-as-server-core.md)
|
||
- [0003 P2P stack](../agent/ADRs/0003-choose-holepunch-p2p-stack.md)
|
||
- [0004](../agent/ADRs/0004-process-model-electron-bare-squid.md) — **superseded** by 0013
|
||
- [0005 Local bind](../agent/ADRs/0005-local-only-bind-invariant.md)
|
||
- [0006 Tunnel](../agent/ADRs/0006-private-world-hyperdht-tunnel.md)
|
||
- [0007 Region registry](../agent/ADRs/0007-mesh-region-registry-autobase.md)
|
||
- [0008 Border migration](../agent/ADRs/0008-border-session-migration.md)
|
||
- [0011](../agent/ADRs/0011-build-release-hello-pear-electron.md) — **superseded** primary path by 0013
|