# zerozshare/openfriendcore architecture

> Architecture diagram of the GitHub repository zerozshare/openfriendcore, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zerozshare/openfriendcore
- Repository: https://github.com/zerozshare/openfriendcore

## Overview

1. **Top-level shape**
   - This repo is a **single Go CLI binary** (`cmd/openfriend`) rather than a multi-service system.
   - The executable is orchestrating three main runtime roles: **authenticate**, **broadcast presence**, and **bridge Minecraft connections**.

2. **CLI entrypoint and mode selection**
   - `cmd/openfriend/main.go` and its helpers (`paths.go`, `reset.go`, `skin.go`, `selfupdate.go`, `joinrunner.go`, `watch_parent.go`) provide the user-facing commands and flags.
   - The key modes are:
     - **Host mode**: accept incoming Friends List joins and forward them to a local Minecraft server.
     - **Join mode**: expose a local TCP port so the user’s Minecraft client can join a friend’s world through OpenFriend.
     - **Reset / skin / update** utilities that operate on local state or external services.

3. **Authentication subsystem**
   - `internal/auth` handles the full Microsoft/Xbox/Mojang authentication chain.
   - It includes **device-code login**, token exchange, session management, and cryptographic storage so credentials can be reused across runs.
   - The persistent session is saved locally as an encrypted auth file in the data directory, which is why the app can start without re-login after the first device-code flow.

4. **Persistent local state**
   - The CLI stores machine-local state next to the binary or under the configured `--data-dir`.
   - Main artifacts include:
     - `auth.pem` for encrypted credentials
     - `status.json` for runtime/status bookkeeping
     - optional `bypass.pem` for the online-mode bypass key
   - This local state is the boundary between long-lived identity/configuration and transient runtime connections.

5. **Minecraft/Friends List API layer**
   - `internal/api` is a typed client for the Minecraft Java Edition friends-related backend.
   - It covers:
     - friend/profile resolution
     - presence queries
     - skin-related operations
     - ID normalization helpers
   - This layer is where the app translates between human-friendly names/PMIDs and the identifiers required by the backend services.

6. **Presence broadcasting**
   - `internal/presence` is responsible for keeping the user visible on the Friends List.
   - The `broadcaster` and `refresher` components periodically update the external presence state using the authenticated API client.
   - This is the subsystem that makes OpenFriend “show up” to other players as joinable.

7. **Signaling and peer setup**
   - `internal/signaling` manages the WebRTC-side negotiation used for Friends List joins.
   - It includes:
     - signaling client logic
     - JSON-RPC message handling
     - dispatch/endpoint definitions
     - TURN configuration and transport helpers
   - Architecturally, this is the control plane that sets up peer connectivity before any Minecraft bytes start flowing.

8. **Bridge layer: WebRTC to TCP**
   - `internal/bridge` is the core data-plane adapter.
   - It handles the handshake, session establishment, and TCP forwarding between:
     - the remote Friends List/WebRTC peer connection
     - the local or backend Minecraft TCP server
   - In **host mode**, OpenFriend accepts an incoming join and forwards traffic to a configured backend server.
   - In **join mode**, OpenFriend exposes a local TCP listener so the user’s Minecraft client can talk to a friend’s world through the negotiated peer connection.

9. **Optional bypass support**
   - `internal/bypass` contains support for the shared-key path used for the online-mode bypass.
   - The README explicitly says this is **implemented but not yet fully verified end-to-end**, and current practical usage is **offline-mode servers only**.
   - For architecture diagrams, treat this as an **optional authentication bypass branch** that is not part of the default offline-mode bridge path.

10. **Skin handling**
   - `internal/skinimg` validates and processes PNG skin images.
   - The CLI can upload a selected skin so the Friends List icon/appearance reflects that image.
   - This is a side channel into the presence/profile layer, not part of the TCP bridge.

11. **Self-update and lifecycle management**
   - `internal/update` plus `cmd/openfriend/selfupdate.go` implement in-place binary replacement on supported platforms.
   - `watch_parent.go` and the join runner utilities suggest the process can supervise child behavior and exit cleanly when the parent disappears.
   - These are operational concerns around the main runtime, not part of the networking core.

12. **External dependencies and boundaries**
   - The important external boundaries are:
     - **Microsoft login/device-code flow**
     - **Xbox Live / Mojang authentication services**
     - **Minecraft Friends List presence/signaling backend**
     - **TURN/WebRTC infrastructure**
     - **the target Minecraft TCP server**
   - The only local network service OpenFriend exposes is the **TCP listener** used in join mode; otherwise it is a client to remote services.

13. **Supporting utilities**
   - `internal/util` provides common HTTP and UUID helpers used across auth, API, and signaling.
   - `internal/status` appears to centralize runtime status representation used by the CLI and persisted status file.

14. **How the system fits together**
   - The runtime sequence is: **authenticate → refresh/broadcast presence → negotiate join via signaling → bridge traffic over TCP**.
   - The app is intentionally modular around those phases, so an architecture diagram should show separate lanes for **identity/session**, **presence/control plane**, and **Minecraft traffic forwarding**.

Main entry points: [`cmd/openfriend/main.go`](https://github.com/zerozshare/openfriendcore/blob/main/cmd/openfriend/main.go) (Main CLI), [`internal/signaling/client.go`](https://github.com/zerozshare/openfriendcore/blob/main/internal/signaling/client.go) (Signaling client), [`internal/bridge/host.go`](https://github.com/zerozshare/openfriendcore/blob/main/internal/bridge/host.go) (Host bridge), [`internal/bridge/join.go`](https://github.com/zerozshare/openfriendcore/blob/main/internal/bridge/join.go) (Join bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI runtime"]
  node_cmd_main["Main CLI<br/>entrypoint<br/>[main.go]"]
  node_cmd_joinrunner["Join runner<br/>runtime helper<br/>[joinrunner.go]"]
  node_cmd_paths["Paths<br/>local state<br/>[paths.go]"]
  node_cmd_reset["Reset<br/>utility command<br/>[reset.go]"]
  node_cmd_watch_parent["Parent watch<br/>lifecycle helper<br/>[watch_parent.go]"]
end

subgraph group_identity["Identity and state"]
  node_auth_store[("Auth store<br/>encrypted session<br/>[store.go]")]
  node_auth_devicecode["Device login<br/>login flow<br/>[devicecode.go]"]
  node_auth_tokens["Token chain<br/>token exchange<br/>[tokens.go]"]
  node_auth_crypto{{"Crypto<br/>sealing<br/>[crypto.go]"}}
  node_status_mod["Status<br/>[status.go]"]
end

subgraph group_control["Control plane"]
  node_api_client["API client<br/>typed client<br/>[client.go]"]
  node_api_friends["Friends API<br/>profiles and presence<br/>[friends.go]"]
  node_api_presence["Presence API<br/>presence backend<br/>[presence.go]"]
  node_presence_broadcaster(("Broadcaster<br/>presence loop<br/>[broadcaster.go]"))
  node_presence_refresher(("Refresher<br/>refresh loop<br/>[refresher.go]"))
  node_signaling_client["Signaling client<br/>peer control<br/>[client.go]"]
  node_signaling_jsonrpc["JSON-RPC<br/>message codec<br/>[jsonrpc.go]"]
  node_signaling_turn["TURN setup<br/>transport config<br/>[turn.go]"]
end

subgraph group_data["Minecraft bridge"]
  node_bridge_host["Host bridge<br/>join ingress<br/>[host.go]"]
  node_bridge_join["Join bridge<br/>client egress<br/>[join.go]"]
  node_bridge_handshake{{"Handshake<br/>session setup<br/>[handshake.go]"}}
  node_bridge_tcp["TCP forward<br/>data plane<br/>[tcp.go]"]
  node_bridge_session[("Bridge session<br/>session state<br/>[session.go]")]
end

subgraph group_ops["Operational tools"]
  node_bypass_key{{"Bypass key<br/>optional path<br/>[key.go]"}}
  node_skinimg_mod["Skin image<br/>png processing<br/>[skinimg.go]"]
  node_update_mod["Updater<br/>binary replace<br/>[update.go]"]
  node_util_mod["Utilities<br/>shared helpers<br/>[http.go]"]
end

node_cmd_main -->|"resolves state"| node_cmd_paths
node_cmd_main -->|"authenticates"| node_auth_devicecode
node_cmd_main -->|"broadcasts"| node_presence_broadcaster
node_cmd_main -->|"negotiates"| node_signaling_client
node_cmd_main -->|"host mode"| node_bridge_host
node_cmd_main -->|"join mode"| node_bridge_join
node_cmd_main -->|"utility"| node_cmd_reset
node_cmd_main -->|"self-update"| node_update_mod
node_cmd_main -->|"skin tool"| node_skinimg_mod
node_cmd_main -->|"loads status"| node_status_mod
node_auth_devicecode -->|"exchanges"| node_auth_tokens
node_auth_tokens -->|"seals"| node_auth_crypto
node_auth_crypto -->|"persists"| node_auth_store
node_auth_store -->|"uses paths"| node_cmd_paths
node_api_client -->|"helpers"| node_util_mod
node_presence_broadcaster -->|"publishes"| node_api_presence
node_presence_refresher -->|"refreshes via"| node_api_client
node_api_friends -->|"served by"| node_api_client
node_signaling_client -->|"encodes"| node_signaling_jsonrpc
node_signaling_client -->|"configures"| node_signaling_turn
node_signaling_client -->|"helpers"| node_util_mod
node_bridge_host -->|"starts"| node_bridge_handshake
node_bridge_join -->|"starts"| node_bridge_handshake
node_bridge_handshake -->|"creates"| node_bridge_session
node_bridge_session -->|"drives"| node_bridge_tcp
node_bridge_tcp -->|"serves"| node_bridge_host
node_bridge_tcp -->|"serves"| node_bridge_join
node_bridge_host -->|"uses control plane"| node_signaling_client
node_bridge_join -->|"uses control plane"| node_signaling_client
node_bypass_key -.->|"optional"| node_bridge_host
node_skinimg_mod -->|"uploads via"| node_api_client
node_update_mod -->|"replaces binary"| node_cmd_main
node_status_mod -->|"stored under"| node_cmd_paths

click node_cmd_main "https://github.com/zerozshare/openfriendcore/blob/main/cmd/openfriend/main.go"
click node_cmd_joinrunner "https://github.com/zerozshare/openfriendcore/blob/main/cmd/openfriend/joinrunner.go"
click node_cmd_paths "https://github.com/zerozshare/openfriendcore/blob/main/cmd/openfriend/paths.go"
click node_cmd_reset "https://github.com/zerozshare/openfriendcore/blob/main/cmd/openfriend/reset.go"
click node_cmd_watch_parent "https://github.com/zerozshare/openfriendcore/blob/main/cmd/openfriend/watch_parent.go"
click node_auth_store "https://github.com/zerozshare/openfriendcore/blob/main/internal/auth/store.go"
click node_auth_devicecode "https://github.com/zerozshare/openfriendcore/blob/main/internal/auth/devicecode.go"
click node_auth_tokens "https://github.com/zerozshare/openfriendcore/blob/main/internal/auth/tokens.go"
click node_auth_crypto "https://github.com/zerozshare/openfriendcore/blob/main/internal/auth/crypto.go"
click node_status_mod "https://github.com/zerozshare/openfriendcore/blob/main/internal/status/status.go"
click node_api_client "https://github.com/zerozshare/openfriendcore/blob/main/internal/api/client.go"
click node_api_friends "https://github.com/zerozshare/openfriendcore/blob/main/internal/api/friends.go"
click node_api_presence "https://github.com/zerozshare/openfriendcore/blob/main/internal/api/presence.go"
click node_presence_broadcaster "https://github.com/zerozshare/openfriendcore/blob/main/internal/presence/broadcaster.go"
click node_presence_refresher "https://github.com/zerozshare/openfriendcore/blob/main/internal/presence/refresher.go"
click node_signaling_client "https://github.com/zerozshare/openfriendcore/blob/main/internal/signaling/client.go"
click node_signaling_jsonrpc "https://github.com/zerozshare/openfriendcore/blob/main/internal/signaling/jsonrpc.go"
click node_signaling_turn "https://github.com/zerozshare/openfriendcore/blob/main/internal/signaling/turn.go"
click node_bridge_host "https://github.com/zerozshare/openfriendcore/blob/main/internal/bridge/host.go"
click node_bridge_join "https://github.com/zerozshare/openfriendcore/blob/main/internal/bridge/join.go"
click node_bridge_handshake "https://github.com/zerozshare/openfriendcore/blob/main/internal/bridge/handshake.go"
click node_bridge_tcp "https://github.com/zerozshare/openfriendcore/blob/main/internal/bridge/tcp.go"
click node_bridge_session "https://github.com/zerozshare/openfriendcore/blob/main/internal/bridge/session.go"
click node_bypass_key "https://github.com/zerozshare/openfriendcore/blob/main/internal/bypass/key.go"
click node_skinimg_mod "https://github.com/zerozshare/openfriendcore/blob/main/internal/skinimg/skinimg.go"
click node_update_mod "https://github.com/zerozshare/openfriendcore/blob/main/internal/update/update.go"
click node_util_mod "https://github.com/zerozshare/openfriendcore/blob/main/internal/util/http.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cmd_main,node_cmd_joinrunner,node_cmd_paths,node_cmd_reset,node_cmd_watch_parent toneBlue
class node_auth_store,node_auth_devicecode,node_auth_tokens,node_auth_crypto,node_status_mod toneAmber
class node_api_client,node_api_friends,node_api_presence,node_presence_broadcaster,node_presence_refresher,node_signaling_client,node_signaling_jsonrpc,node_signaling_turn toneMint
class node_bridge_host,node_bridge_join,node_bridge_handshake,node_bridge_tcp,node_bridge_session toneRose
class node_bypass_key,node_skinimg_mod,node_update_mod,node_util_mod toneIndigo
```

## Components

### CLI runtime

Entry commands, mode selection, and local lifecycle control.

- [Main CLI](https://github.com/zerozshare/openfriendcore/blob/main/cmd/openfriend/main.go): entrypoint · Command-line entrypoint that selects host, join, and utility modes. · `cmd/openfriend/main.go`
- [Join runner](https://github.com/zerozshare/openfriendcore/blob/main/cmd/openfriend/joinrunner.go): runtime helper · Supervises join-mode lifecycle and process behavior around the main CLI. · `cmd/openfriend/joinrunner.go`
- [Paths](https://github.com/zerozshare/openfriendcore/blob/main/cmd/openfriend/paths.go): local state · Resolves data-directory and file locations for persistent artifacts. · `cmd/openfriend/paths.go`
- [Reset](https://github.com/zerozshare/openfriendcore/blob/main/cmd/openfriend/reset.go): utility command · Clears or reinitializes local state and runtime bookkeeping. · `cmd/openfriend/reset.go`
- [Parent watch](https://github.com/zerozshare/openfriendcore/blob/main/cmd/openfriend/watch_parent.go): lifecycle helper · Observes parent-process presence and supports clean shutdown behavior. · `cmd/openfriend/watch_parent.go`

### Identity and state

Authentication, encrypted session storage, and persisted local state.

- [Auth store](https://github.com/zerozshare/openfriendcore/blob/main/internal/auth/store.go): encrypted session · Persists encrypted credentials and reusable login state on disk. · `internal/auth/store.go`
- [Device login](https://github.com/zerozshare/openfriendcore/blob/main/internal/auth/devicecode.go): login flow · Runs the Microsoft device-code authentication flow. · `internal/auth/devicecode.go`
- [Token chain](https://github.com/zerozshare/openfriendcore/blob/main/internal/auth/tokens.go): token exchange · Handles Microsoft, Xbox, and Mojang token/session exchange. · `internal/auth/tokens.go`
- [Crypto](https://github.com/zerozshare/openfriendcore/blob/main/internal/auth/crypto.go): sealing · Encrypts and decrypts stored authentication material. · `internal/auth/crypto.go`
- [Status](https://github.com/zerozshare/openfriendcore/blob/main/internal/status/status.go): runtime status · Represents and persists runtime status bookkeeping. · `internal/status/status.go`

### Control plane

Presence, signaling, and external service coordination.

- [API client](https://github.com/zerozshare/openfriendcore/blob/main/internal/api/client.go): typed client · Shared client for Minecraft Friends List backend calls. · `internal/api/client.go`
- [Friends API](https://github.com/zerozshare/openfriendcore/blob/main/internal/api/friends.go): profiles and presence · Resolves friends, profiles, and join-related identifiers. · `internal/api/friends.go`
- [Presence API](https://github.com/zerozshare/openfriendcore/blob/main/internal/api/presence.go): presence backend · Reads and writes presence state used for joinability. · `internal/api/presence.go`
- [Broadcaster](https://github.com/zerozshare/openfriendcore/blob/main/internal/presence/broadcaster.go): presence loop · Keeps the user visible on Friends List by publishing presence updates. · `internal/presence/broadcaster.go`
- [Refresher](https://github.com/zerozshare/openfriendcore/blob/main/internal/presence/refresher.go): refresh loop · Periodically renews presence using the authenticated API client. · `internal/presence/refresher.go`
- [Signaling client](https://github.com/zerozshare/openfriendcore/blob/main/internal/signaling/client.go): peer control · Coordinates WebRTC-side join negotiation with remote peers. · `internal/signaling/client.go`
- [JSON-RPC](https://github.com/zerozshare/openfriendcore/blob/main/internal/signaling/jsonrpc.go): message codec · Encodes and handles signaling messages over the transport. · `internal/signaling/jsonrpc.go`
- [TURN setup](https://github.com/zerozshare/openfriendcore/blob/main/internal/signaling/turn.go): transport config · Configures TURN and transport details for peer connectivity. · `internal/signaling/turn.go`

### Minecraft bridge

Traffic forwarding between peer connectivity and TCP endpoints.

- [Host bridge](https://github.com/zerozshare/openfriendcore/blob/main/internal/bridge/host.go): join ingress · Accepts incoming joins and forwards them to a backend Minecraft server. · `internal/bridge/host.go`
- [Join bridge](https://github.com/zerozshare/openfriendcore/blob/main/internal/bridge/join.go): client egress · Exposes a local TCP listener for the Minecraft client in join mode. · `internal/bridge/join.go`
- [Handshake](https://github.com/zerozshare/openfriendcore/blob/main/internal/bridge/handshake.go): session setup · Establishes the bridge session before bytes flow. · `internal/bridge/handshake.go`
- [TCP forward](https://github.com/zerozshare/openfriendcore/blob/main/internal/bridge/tcp.go): data plane · Moves Minecraft traffic between the peer connection and the TCP endpoint. · `internal/bridge/tcp.go`
- [Bridge session](https://github.com/zerozshare/openfriendcore/blob/main/internal/bridge/session.go): session state · Tracks negotiated bridge state and active connection metadata. · `internal/bridge/session.go`

### Operational tools

Skin, update, bypass, and status helpers.

- [Bypass key](https://github.com/zerozshare/openfriendcore/blob/main/internal/bypass/key.go): optional path · Supports the optional online-mode bypass key flow. · `internal/bypass/key.go`
- [Skin image](https://github.com/zerozshare/openfriendcore/blob/main/internal/skinimg/skinimg.go): png processing · Validates and processes skin images for profile appearance. · `internal/skinimg/skinimg.go`
- [Updater](https://github.com/zerozshare/openfriendcore/blob/main/internal/update/update.go): binary replace · Performs in-place self-update and executable replacement. · `internal/update/update.go`
- [Utilities](https://github.com/zerozshare/openfriendcore/blob/main/internal/util/http.go): shared helpers · Common HTTP and UUID helpers reused across subsystems. · `internal/util/http.go`

## Connections

- Main CLI → Paths: resolves state · Locates persistent files and data directory for the current run.
- Main CLI → Device login: authenticates · Starts login when no reusable session is available.
- Main CLI → Broadcaster: broadcasts · Enters the presence loop after authentication.
- Main CLI → Signaling client: negotiates · Handles join signaling for host or join modes.
- Main CLI → Host bridge: host mode · Forwards incoming joins to a local Minecraft server.
- Main CLI → Join bridge: join mode · Creates the local listener used by the Minecraft client.
- Main CLI → Reset: utility · Runs state-reset operations when requested.
- Main CLI → Updater: self-update · Triggers in-place binary replacement when requested.
- Main CLI → Skin image: skin tool · Processes skin uploads from the CLI.
- Main CLI → Status: loads status · Reads and writes runtime bookkeeping.
- Device login → Token chain: exchanges · Completes the Microsoft/Xbox/Mojang token chain.
- Token chain → Crypto: seals · Encrypts material before persistence.
- Crypto → Auth store: persists · Writes encrypted auth state to disk.
- Auth store → Paths: uses paths · Reads the configured data-directory locations.
- API client → Utilities: helpers · Uses shared HTTP and UUID helpers.
- Broadcaster → Presence API: publishes · Updates presence through the backend API.
- Refresher → API client: refreshes via · Renewal loop uses the typed API client.
- Friends API → API client: served by · Friend and profile operations are issued through the shared client.
- Signaling client → JSON-RPC: encodes · Uses JSON-RPC messages for join negotiation.
- Signaling client → TURN setup: configures · Sets up TURN and transport parameters.
- Signaling client → Utilities: helpers · Reuses common utility functions.
- Host bridge → Handshake: starts · Begins session establishment for incoming joins.
- Join bridge → Handshake: starts · Begins session establishment for local-client joins.
- Handshake → Bridge session: creates · Creates the active bridge session state.
- Bridge session → TCP forward: drives · Session state governs traffic forwarding.
- TCP forward → Host bridge: serves · Host mode forwards to the backend Minecraft server.
- TCP forward → Join bridge: serves · Join mode forwards to the local Minecraft client listener.
- Host bridge → Signaling client: uses control plane · Relies on signaling to establish the peer connection.
- Join bridge → Signaling client: uses control plane · Relies on signaling to establish the peer connection.
- Bypass key → Host bridge: optional · Represents the optional online-mode bypass branch.
- Skin image → API client: uploads via · Skin operations feed the Friends List profile layer.
- Updater → Main CLI: replaces binary · Supports self-update of the running CLI.
- Status → Paths: stored under · Persists status data alongside other local state.
