first commit

2026-07-30 23:02:00 -04:00
commit fd537ed47e
48 changed files with 3059 additions and 0 deletions
@@ -0,0 +1,139 @@
+# 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