Architecture Overview

High-level picture of Flying Jib. For deep detail see 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)

Goals (non-negotiable)

Never master/central game servers we operate.
Every participant runs a local Minecraft server (Flying Squid) on 127.0.0.1 only.
Users launch a single Bare/Pear distributable — no system Node.js, no Node child process for Squid.
Worlds are private (capability invite) or enrolled into a mesh of linked regions.
Discovery and transport use Hyperswarm / HyperDHT only (public DHT bootstrap nodes are infrastructure, not app control planes).
CI releases produce single standalone executables (bare-build --standalone) plus Pear app-drive OTA (stage/seed/provision/multisig).

System diagram

┌─────────────────────────────────────────────────────────────────┐
│  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)

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)

$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)

0013 Bare/Pear only ← runtime & release
0002 Flying Squid on Bare
0003 P2P stack
0004 — superseded by 0013
0005 Local bind
0006 Tunnel
0007 Region registry
0008 Border migration
0011 — superseded primary path by 0013

6.7 KiB Raw Blame History Unescape Escape