# minekube/connect-java architecture

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

- Interactive diagram: https://gitdiagram.com/minekube/connect-java
- Repository: https://github.com/minekube/connect-java

## Overview

Minekube Connect is a Minecraft server/proxy plugin that exposes servers to Connect’s edge-proxy network. The principal flow is WatchService session negotiation, admission (including configured Bedrock identity checks), then creation of a local session that carries the player connection through a tunnel to the server. The repository also provides platform-specific adapters, packet interception, and an optional libp2p endpoint mode. Edges are limited to relationships visible in the supplied excerpts or README; unverified handoffs are dashed.

Main entry points: [`core/src/main/java/com/minekube/connect/watch/WatchClient.java`](https://github.com/minekube/connect-java/blob/main/core/src/main/java/com/minekube/connect/watch/WatchClient.java) (WatchService client), [`bungee/src/main/java/com/minekube/connect/BungeePlugin.java`](https://github.com/minekube/connect-java/blob/main/bungee/src/main/java/com/minekube/connect/BungeePlugin.java) (Connect plugin), [`core/src/main/java/com/minekube/connect/network/netty/LocalSession.java`](https://github.com/minekube/connect-java/blob/main/core/src/main/java/com/minekube/connect/network/netty/LocalSession.java) (Local session), [`core/src/main/java/com/minekube/connect/bedrock/BedrockAdmissionCoordinator.java`](https://github.com/minekube/connect-java/blob/main/core/src/main/java/com/minekube/connect/bedrock/BedrockAdmissionCoordinator.java) (Bedrock admission)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_integration["Platform integration"]
  node_platform["Connect plugin<br/>[BungeePlugin.java]"]
  node_platform_adapters["Platform adapters"]
  node_spigot_handler["Spigot login adaptation"]
end

subgraph group_session["Session lifecycle"]
  node_config["Connect configuration<br/>[ConnectConfig.java]"]
  node_watch["WatchService client<br/>[WatchClient.java]"]
  node_proposal["Session proposal"]
  node_local_session["Local session<br/>[LocalSession.java]"]
end

subgraph group_identity["Identity and admission"]
  node_bedrock["Bedrock admission"]
  node_bedrock_verify["Bedrock identity verification"]
  node_principal["Signed principal verification"]
end

subgraph group_transport["Tunnel transport"]
  node_local_channel["Local channel pipeline"]
  node_tunnel_conn["Tunnel connection<br/>[TunnelConn.java]"]
  node_tunneler["Tunnel orchestration<br/>[Tunneler.java]"]
  node_watch_transport["Watch tunnel transport"]
  node_libp2p["libp2p endpoint"]
end

subgraph group_extension["Plugin features"]
  node_packet_api["Packet handler API"]
  node_packet_impl["Packet dispatch"]
  node_commands["Commands and configuration<br/>[MainCommand.java]"]
end

node_player(("Minecraft player"))
node_edge{{"Connect edge network"}}
node_backend(("Minecraft server"))

node_player -->|"requests connection"| node_edge
node_edge -->|"negotiates sessions"| node_watch
node_watch -->|"reads settings"| node_config
node_watch -->|"receives proposals"| node_proposal
node_proposal -.->|"starts session"| node_local_session
node_local_session -->|"coordinates admission"| node_bedrock
node_bedrock -.->|"verifies identity"| node_bedrock_verify
node_bedrock -.->|"checks principal"| node_principal
node_local_session -->|"installs pipeline"| node_local_channel
node_local_channel -->|"uses tunnel"| node_tunneler
node_tunneler -.->|"opens connection"| node_tunnel_conn
node_tunnel_conn -.->|"uses transport"| node_watch_transport
node_watch_transport -.->|"carries session"| node_edge
node_tunnel_conn -->|"forwards traffic"| node_backend
node_platform -->|"configures platform"| node_platform_adapters
node_platform -->|"enables watcher"| node_watch
node_platform -->|"enables endpoint"| node_libp2p
node_libp2p -->|"registers peer"| node_edge
node_packet_api -->|"implemented by"| node_packet_impl
node_spigot_handler -->|"registers handler"| node_packet_api
node_commands -.->|"inspects settings"| node_config

click node_platform "https://github.com/minekube/connect-java/blob/main/bungee/src/main/java/com/minekube/connect/BungeePlugin.java"
click node_platform_adapters "https://github.com/minekube/connect-java/blob/main/bungee/src/main/java/com/minekube/connect/module/BungeePlatformModule.java"
click node_config "https://github.com/minekube/connect-java/blob/main/core/src/main/java/com/minekube/connect/config/ConnectConfig.java"
click node_watch "https://github.com/minekube/connect-java/blob/main/core/src/main/java/com/minekube/connect/watch/WatchClient.java"
click node_proposal "https://github.com/minekube/connect-java/blob/main/core/src/main/java/com/minekube/connect/watch/SessionProposal.java"
click node_local_session "https://github.com/minekube/connect-java/blob/main/core/src/main/java/com/minekube/connect/network/netty/LocalSession.java"
click node_bedrock "https://github.com/minekube/connect-java/blob/main/core/src/main/java/com/minekube/connect/bedrock/BedrockAdmissionCoordinator.java"
click node_bedrock_verify "https://github.com/minekube/connect-java/blob/main/api/src/main/java/com/minekube/connect/api/player/bedrock/BedrockIdentityVerifier.java"
click node_principal "https://github.com/minekube/connect-java/blob/main/api/src/main/java/com/minekube/connect/api/player/principal/DefaultBedrockPrincipalVerifier.java"
click node_local_channel "https://github.com/minekube/connect-java/blob/main/core/src/main/java/com/minekube/connect/network/netty/LocalChannelInboundHandler.java"
click node_tunnel_conn "https://github.com/minekube/connect-java/blob/main/core/src/main/java/com/minekube/connect/tunnel/TunnelConn.java"
click node_tunneler "https://github.com/minekube/connect-java/blob/main/core/src/main/java/com/minekube/connect/tunnel/Tunneler.java"
click node_watch_transport "https://github.com/minekube/connect-java/blob/main/core/src/main/java/com/minekube/connect/tunnel/WebSocketTunnelTransport.java"
click node_libp2p "https://github.com/minekube/connect-java/blob/main/core/src/main/java/com/minekube/connect/tunnel/p2p/Libp2pEndpointRuntime.java"
click node_packet_api "https://github.com/minekube/connect-java/blob/main/api/src/main/java/com/minekube/connect/api/packet/PacketHandlers.java"
click node_packet_impl "https://github.com/minekube/connect-java/blob/main/core/src/main/java/com/minekube/connect/packet/PacketHandlersImpl.java"
click node_spigot_handler "https://github.com/minekube/connect-java/blob/main/spigot/src/main/java/com/minekube/connect/addon/data/SpigotDataHandler.java"
click node_commands "https://github.com/minekube/connect-java/blob/main/core/src/main/java/com/minekube/connect/command/main/MainCommand.java"

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_platform,node_platform_adapters,node_spigot_handler toneBlue
class node_config,node_watch,node_proposal,node_local_session toneAmber
class node_bedrock,node_bedrock_verify,node_principal,node_backend toneMint
class node_local_channel,node_tunnel_conn,node_tunneler,node_watch_transport,node_libp2p toneRose
class node_packet_api,node_packet_impl,node_commands,node_player,node_edge toneIndigo
```

## Components

### Platform integration

- [Connect plugin](https://github.com/minekube/connect-java/blob/main/bungee/src/main/java/com/minekube/connect/BungeePlugin.java): `bungee/src/main/java/com/minekube/connect/BungeePlugin.java`
- [Platform adapters](https://github.com/minekube/connect-java/blob/main/bungee/src/main/java/com/minekube/connect/module/BungeePlatformModule.java): `bungee/src/main/java/com/minekube/connect/module/BungeePlatformModule.java`
- [Spigot login adaptation](https://github.com/minekube/connect-java/blob/main/spigot/src/main/java/com/minekube/connect/addon/data/SpigotDataHandler.java): `spigot/src/main/java/com/minekube/connect/addon/data/SpigotDataHandler.java`

### Session lifecycle

- [Connect configuration](https://github.com/minekube/connect-java/blob/main/core/src/main/java/com/minekube/connect/config/ConnectConfig.java): `core/src/main/java/com/minekube/connect/config/ConnectConfig.java`
- [WatchService client](https://github.com/minekube/connect-java/blob/main/core/src/main/java/com/minekube/connect/watch/WatchClient.java): `core/src/main/java/com/minekube/connect/watch/WatchClient.java`
- [Session proposal](https://github.com/minekube/connect-java/blob/main/core/src/main/java/com/minekube/connect/watch/SessionProposal.java): `core/src/main/java/com/minekube/connect/watch/SessionProposal.java`
- [Local session](https://github.com/minekube/connect-java/blob/main/core/src/main/java/com/minekube/connect/network/netty/LocalSession.java): `core/src/main/java/com/minekube/connect/network/netty/LocalSession.java`

### Identity and admission

- [Bedrock admission](https://github.com/minekube/connect-java/blob/main/core/src/main/java/com/minekube/connect/bedrock/BedrockAdmissionCoordinator.java): `core/src/main/java/com/minekube/connect/bedrock/BedrockAdmissionCoordinator.java`
- [Bedrock identity verification](https://github.com/minekube/connect-java/blob/main/api/src/main/java/com/minekube/connect/api/player/bedrock/BedrockIdentityVerifier.java): `api/src/main/java/com/minekube/connect/api/player/bedrock/BedrockIdentityVerifier.java`
- [Signed principal verification](https://github.com/minekube/connect-java/blob/main/api/src/main/java/com/minekube/connect/api/player/principal/DefaultBedrockPrincipalVerifier.java): `api/src/main/java/com/minekube/connect/api/player/principal/DefaultBedrockPrincipalVerifier.java`

### Tunnel transport

- [Local channel pipeline](https://github.com/minekube/connect-java/blob/main/core/src/main/java/com/minekube/connect/network/netty/LocalChannelInboundHandler.java): `core/src/main/java/com/minekube/connect/network/netty/LocalChannelInboundHandler.java`
- [Tunnel connection](https://github.com/minekube/connect-java/blob/main/core/src/main/java/com/minekube/connect/tunnel/TunnelConn.java): `core/src/main/java/com/minekube/connect/tunnel/TunnelConn.java`
- [Tunnel orchestration](https://github.com/minekube/connect-java/blob/main/core/src/main/java/com/minekube/connect/tunnel/Tunneler.java): `core/src/main/java/com/minekube/connect/tunnel/Tunneler.java`
- [Watch tunnel transport](https://github.com/minekube/connect-java/blob/main/core/src/main/java/com/minekube/connect/tunnel/WebSocketTunnelTransport.java): `core/src/main/java/com/minekube/connect/tunnel/WebSocketTunnelTransport.java`
- [libp2p endpoint](https://github.com/minekube/connect-java/blob/main/core/src/main/java/com/minekube/connect/tunnel/p2p/Libp2pEndpointRuntime.java): `core/src/main/java/com/minekube/connect/tunnel/p2p/Libp2pEndpointRuntime.java`

### Plugin features

- [Packet handler API](https://github.com/minekube/connect-java/blob/main/api/src/main/java/com/minekube/connect/api/packet/PacketHandlers.java): `api/src/main/java/com/minekube/connect/api/packet/PacketHandlers.java`
- [Packet dispatch](https://github.com/minekube/connect-java/blob/main/core/src/main/java/com/minekube/connect/packet/PacketHandlersImpl.java): `core/src/main/java/com/minekube/connect/packet/PacketHandlersImpl.java`
- [Commands and configuration](https://github.com/minekube/connect-java/blob/main/core/src/main/java/com/minekube/connect/command/main/MainCommand.java): `core/src/main/java/com/minekube/connect/command/main/MainCommand.java`

### Other components

- **Minecraft player**
- **Connect edge network**
- **Minecraft server**

## Connections

- Minecraft player → Connect edge network: requests connection (evidence: `README.md`)
- Connect edge network → WatchService client: negotiates sessions (evidence: `README.md`)
- WatchService client → Connect configuration: reads settings (evidence: `core/src/main/java/com/minekube/connect/watch/WatchClient.java`)
- WatchService client → Session proposal: receives proposals (evidence: `core/src/main/java/com/minekube/connect/watch/WatchClient.java`)
- Session proposal → Local session: starts session (evidence: `core/src/main/java/com/minekube/connect/network/netty/LocalSession.java`)
- Local session → Bedrock admission: coordinates admission (evidence: `core/src/main/java/com/minekube/connect/network/netty/LocalSession.java`)
- Bedrock admission → Bedrock identity verification: verifies identity
- Bedrock admission → Signed principal verification: checks principal
- Local session → Local channel pipeline: installs pipeline (evidence: `core/src/main/java/com/minekube/connect/network/netty/LocalSession.java`)
- Local channel pipeline → Tunnel orchestration: uses tunnel (evidence: `core/src/main/java/com/minekube/connect/network/netty/LocalSession.java`)
- Tunnel orchestration → Tunnel connection: opens connection
- Tunnel connection → Watch tunnel transport: uses transport
- Watch tunnel transport → Connect edge network: carries session
- Tunnel connection → Minecraft server: forwards traffic (evidence: `README.md`)
- Connect plugin → Platform adapters: configures platform (evidence: `bungee/src/main/java/com/minekube/connect/BungeePlugin.java`)
- Connect plugin → WatchService client: enables watcher (evidence: `bungee/src/main/java/com/minekube/connect/BungeePlugin.java`)
- Connect plugin → libp2p endpoint: enables endpoint (evidence: `bungee/src/main/java/com/minekube/connect/BungeePlugin.java`)
- libp2p endpoint → Connect edge network: registers peer (evidence: `README.md`)
- Packet handler API → Packet dispatch: implemented by (evidence: `core/src/main/java/com/minekube/connect/packet/PacketHandlersImpl.java`)
- Spigot login adaptation → Packet handler API: registers handler
- Commands and configuration → Connect configuration: inspects settings
