# 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