Connect Architecture

This page shows the complete Connect picture in a user-friendly way: who talks to whom, which parts are optional, and how commands, routing, and public server status move through the system.

High-level overview

flowchart LR
  subgraph Clients["Users and clients"]
    Dash["Dash"]
    Launcher["Launcher"]
    Player["Minecraft player"]
  end

  subgraph Host["Server host"]
    Game["Minecraft server"]
    Connect["Connect mod/plugin"]
    SDK["External Java app via connect-sdk"]
    Agent["Connect Agent (optional)"]
  end

  subgraph Cloud["Shared backend"]
    API["Public API"]
    Mongo["MongoDB"]
    Watcher["Gateway watcher"]
    Proxy["Gateway mcproxy"]
  end

  Dash <-->|"commands, settings,\nnetworks, metadata"| API
  Launcher <-->|"public server list,\ndownload metadata"| API

  Connect -->|"server actions,\nsettings, heartbeats,\npublic status"| Agent
  SDK -->|"same Connect API\ncontract"| Agent

  Connect -.->|"direct API mode\nwhen no agent is used"| API
  SDK -.->|"direct API mode\nwhen no agent is used"| API
  Agent -->|"proxy + short-lived\ncache/fallback"| API

  API <--> Mongo

  Connect -->|"gateway candidate lookup\nand route ownership"| API
  API -->|"active route snapshot"| Watcher
  Watcher -->|"routes.json"| Proxy
  Connect -->|"tunnel/control\nport 9001"| Proxy
  Player -->|"Minecraft TCP\n25565"| Proxy
  Proxy -->|"forwarded traffic"| Game

  Connect -->|"reporter snapshots\nMOTD + player stats"| API
  SDK -->|"reporter snapshots\nfor non-loader JVM apps"| API
  API -->|"aggregated network\npublic-server status"| Launcher

What each piece does

• Dash: operator UI for commands, settings, Connect networks, and metadata.
• Connect mod/plugin: runs inside Fabric, NeoForge, Paper, or Velocity and executes remote actions for a specific server.
• connect-sdk: lets any other JVM program use the same Connect registration, auth, gateway, and reporter APIs without shipping a Minecraft loader entry point.
• Connect Agent: optional local proxy on the host. It reduces direct API calls and keeps some functionality available during short API outages.
• Public API: central control plane and source of truth for Connect state.
• Gateway watcher: reads routing state from the API and materializes it for the runtime.
• Gateway mcproxy: handles the Minecraft TCP edge and forwards player traffic to the currently active backend.
• Launcher: consumes the public server listing and download/update metadata.

Main flows

1. Commands and settings

1. Dash writes commands or settings to the Public API.
2. Connect polls or streams that state.
3. The game server executes the action or applies the config.
4. Connect can publish updated settings back to the API.

2. Optional host-agent mode

1. Connect talks to the local Connect Agent.
2. The agent forwards /v1/connect/* traffic to the Public API.
3. If the API is briefly unavailable, the agent can still serve cached data for selected flows.

3. Gateway routing

1. Connect asks the Public API for gateway candidates.
2. Connect probes the available gateways and chooses the best one.
3. Connect publishes route ownership to the Public API.
4. Gateway watcher pulls that route state and writes routes.json.
5. Gateway mcproxy uses the active route to forward Minecraft traffic.

4. Public server stats

1. A Connect server or a JVM app using connect-sdk reports MOTD and player stats.
2. The Public API stores one raw snapshot per Connect server.
3. Fresh snapshots of the same network are aggregated into one public listing.
4. The launcher reads the aggregated network status instead of pinging every backend separately.

Typical setups

Simple single server

• Dash <-> Public API <-> Connect <-> Minecraft server

Server host with agent

• Dash <-> Public API <-> Connect Agent <-> Connect <-> Minecraft server

Connect network with gateway and public stats

• Dash manages the network in the Public API.
• Multiple Connect servers publish status into one shared public listing.
• One active gateway route exposes the network to players.
• The launcher reads the aggregated listing from the Public API.