# memoxiiii/portal architecture

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

- Interactive diagram: https://gitdiagram.com/memoxiiii/portal
- Repository: https://github.com/memoxiiii/portal

## Overview

Portal is a Minecraft: Bedrock transfer proxy: players connect once, join a backend, and can be transferred between backends while Portal relays and translates gameplay packets. Backend services connect separately over the socket protocol to authenticate, register servers, and request proxy operations. Supporting capabilities include health-aware and weighted selection, status and resource-pack handling, admin and metrics surfaces, events, and optional cross-proxy clustering. The README documents these capabilities; only selected source was sampled, so uncertain internal wiring is omitted.

Main entry points: [`portal.go`](https://github.com/memoxiiii/portal/blob/master/portal.go) (Portal proxy), [`server/registry.go`](https://github.com/memoxiiii/portal/blob/master/server/registry.go) (Server registry), [`session/session.go`](https://github.com/memoxiiii/portal/blob/master/session/session.go) (Player sessions), [`socket/server.go`](https://github.com/memoxiiii/portal/blob/master/socket/server.go) (Socket server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_player["Player proxy"]
  node_portal["Portal proxy<br/>[portal.go]"]
  node_transport["Player transport<br/>[transport.go]"]
  node_sessions["Player sessions<br/>[session.go]"]
  node_packetflow["Packet relay<br/>[packet_handler.go]"]
  node_translation["Protocol translation<br/>[translator.go]"]
  node_transfers["Transfer selection<br/>[load_balancer.go]"]
end

subgraph group_backends["Backend management"]
  node_socket["Socket server<br/>[server.go]"]
  node_auth["Backend authentication"]
  node_sockethandlers["Backend requests<br/>[handler.go]"]
  node_packets["Socket packets<br/>[packet.go]"]
  node_registry["Server registry<br/>[registry.go]"]
  node_serverstate["Backend state<br/>[server.go]"]
end

subgraph group_operations["Operations and state"]
  node_health["Health checks<br/>[health_checker.go]"]
  node_status["Player status<br/>[status_provider.go]"]
  node_packs["Resource packs"]
  node_admin["Admin console<br/>[admin.go]"]
  node_metrics["Metrics<br/>[registry.go]"]
  node_events["Event bus<br/>[bus.go]"]
  node_sessionsstore[("Session store<br/>[store.go]")]
end

subgraph group_integrations["External integrations"]
  node_cluster["Cluster backend<br/>[backend.go]"]
  node_redis[("Redis backend<br/>[redis.go]")]
end

node_players(("Bedrock players"))
node_backendsvc(("Backend servers"))
node_gamebackends(("Minecraft backends"))

node_players -->|"connect"| node_transport
node_transport -->|"accepts traffic"| node_portal
node_portal -->|"creates sessions"| node_sessions
node_sessions -->|"dials backend"| node_gamebackends
node_sessions -->|"relays packets"| node_packetflow
node_packetflow -->|"translates packets"| node_translation
node_sessions -->|"selects destination"| node_transfers
node_transfers -->|"chooses server"| node_registry
node_backendsvc -->|"connects"| node_socket
node_socket -->|"dispatches auth"| node_auth
node_socket -->|"dispatches requests"| node_sockethandlers
node_sockethandlers -->|"handles messages"| node_packets
node_sockethandlers -->|"registers servers"| node_registry
node_registry -->|"stores entries"| node_serverstate
node_health -->|"checks servers"| node_registry
node_portal -->|"provides status"| node_status
node_portal -->|"loads packs"| node_packs
node_portal -->|"stores sessions"| node_sessionsstore
node_admin -->|"administers servers"| node_registry
node_metrics -->|"reports state"| node_registry
node_metrics -->|"reports players"| node_sessionsstore
node_socket -->|"publishes events"| node_events
node_portal -.->|"uses presence"| node_cluster
node_cluster -.->|"stores presence"| node_redis

click node_portal "https://github.com/memoxiiii/portal/blob/master/portal.go"
click node_transport "https://github.com/memoxiiii/portal/blob/master/transport.go"
click node_sessions "https://github.com/memoxiiii/portal/blob/master/session/session.go"
click node_packetflow "https://github.com/memoxiiii/portal/blob/master/session/packet_handler.go"
click node_translation "https://github.com/memoxiiii/portal/blob/master/session/translator.go"
click node_transfers "https://github.com/memoxiiii/portal/blob/master/session/load_balancer.go"
click node_socket "https://github.com/memoxiiii/portal/blob/master/socket/server.go"
click node_auth "https://github.com/memoxiiii/portal/blob/master/socket/handler_auth_request.go"
click node_sockethandlers "https://github.com/memoxiiii/portal/blob/master/socket/handler.go"
click node_packets "https://github.com/memoxiiii/portal/blob/master/socket/packet/packet.go"
click node_registry "https://github.com/memoxiiii/portal/blob/master/server/registry.go"
click node_serverstate "https://github.com/memoxiiii/portal/blob/master/server/server.go"
click node_health "https://github.com/memoxiiii/portal/blob/master/server/health_checker.go"
click node_status "https://github.com/memoxiiii/portal/blob/master/status_provider.go"
click node_packs "https://github.com/memoxiiii/portal/blob/master/resource_pack_manager.go"
click node_admin "https://github.com/memoxiiii/portal/blob/master/admin.go"
click node_metrics "https://github.com/memoxiiii/portal/blob/master/metrics/registry.go"
click node_events "https://github.com/memoxiiii/portal/blob/master/event/bus.go"
click node_sessionsstore "https://github.com/memoxiiii/portal/blob/master/session/store.go"
click node_cluster "https://github.com/memoxiiii/portal/blob/master/cluster/backend.go"
click node_redis "https://github.com/memoxiiii/portal/blob/master/cluster/redis.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_portal,node_transport,node_sessions,node_packetflow,node_translation,node_transfers toneBlue
class node_socket,node_auth,node_sockethandlers,node_packets,node_registry,node_serverstate toneAmber
class node_health,node_status,node_packs,node_admin,node_metrics,node_events,node_sessionsstore,node_backendsvc toneMint
class node_cluster,node_redis toneRose
class node_players,node_gamebackends toneIndigo
```

## Components

### Player proxy

- [Portal proxy](https://github.com/memoxiiii/portal/blob/master/portal.go): `portal.go`
- [Player transport](https://github.com/memoxiiii/portal/blob/master/transport.go): `transport.go`
- [Player sessions](https://github.com/memoxiiii/portal/blob/master/session/session.go): `session/session.go`
- [Packet relay](https://github.com/memoxiiii/portal/blob/master/session/packet_handler.go): `session/packet_handler.go`
- [Protocol translation](https://github.com/memoxiiii/portal/blob/master/session/translator.go): `session/translator.go`
- [Transfer selection](https://github.com/memoxiiii/portal/blob/master/session/load_balancer.go): `session/load_balancer.go`

### Backend management

- [Socket server](https://github.com/memoxiiii/portal/blob/master/socket/server.go): `socket/server.go`
- [Backend authentication](https://github.com/memoxiiii/portal/blob/master/socket/handler_auth_request.go): `socket/handler_auth_request.go`
- [Backend requests](https://github.com/memoxiiii/portal/blob/master/socket/handler.go): `socket/handler.go`
- [Socket packets](https://github.com/memoxiiii/portal/blob/master/socket/packet/packet.go): `socket/packet/packet.go`
- [Server registry](https://github.com/memoxiiii/portal/blob/master/server/registry.go): `server/registry.go`
- [Backend state](https://github.com/memoxiiii/portal/blob/master/server/server.go): `server/server.go`

### Operations and state

- [Health checks](https://github.com/memoxiiii/portal/blob/master/server/health_checker.go): `server/health_checker.go`
- [Player status](https://github.com/memoxiiii/portal/blob/master/status_provider.go): `status_provider.go`
- [Resource packs](https://github.com/memoxiiii/portal/blob/master/resource_pack_manager.go): `resource_pack_manager.go`
- [Admin console](https://github.com/memoxiiii/portal/blob/master/admin.go): `admin.go`
- [Metrics](https://github.com/memoxiiii/portal/blob/master/metrics/registry.go): `metrics/registry.go`
- [Event bus](https://github.com/memoxiiii/portal/blob/master/event/bus.go): `event/bus.go`
- [Session store](https://github.com/memoxiiii/portal/blob/master/session/store.go): `session/store.go`

### External integrations

- [Cluster backend](https://github.com/memoxiiii/portal/blob/master/cluster/backend.go): `cluster/backend.go`
- [Redis backend](https://github.com/memoxiiii/portal/blob/master/cluster/redis.go): `cluster/redis.go`

### Other components

- **Bedrock players**
- **Backend servers**
- **Minecraft backends**

## Connections

- Bedrock players → Player transport: connect
- Player transport → Portal proxy: accepts traffic
- Portal proxy → Player sessions: creates sessions
- Player sessions → Minecraft backends: dials backend
- Player sessions → Packet relay: relays packets
- Packet relay → Protocol translation: translates packets
- Player sessions → Transfer selection: selects destination
- Transfer selection → Server registry: chooses server
- Backend servers → Socket server: connects
- Socket server → Backend authentication: dispatches auth
- Socket server → Backend requests: dispatches requests
- Backend requests → Socket packets: handles messages
- Backend requests → Server registry: registers servers
- Server registry → Backend state: stores entries
- Health checks → Server registry: checks servers
- Portal proxy → Player status: provides status
- Portal proxy → Resource packs: loads packs
- Portal proxy → Session store: stores sessions
- Admin console → Server registry: administers servers
- Metrics → Server registry: reports state
- Metrics → Session store: reports players
- Socket server → Event bus: publishes events
- Portal proxy → Cluster backend: uses presence
- Cluster backend → Redis backend: stores presence