# freennzzy/gtproxy architecture

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

- Interactive diagram: https://gitdiagram.com/freennzzy/gtproxy
- Repository: https://github.com/freennzzy/gtproxy

## Overview

Growtopia Proxy intercepts traffic between the game client and Growtopia servers so users can inspect and modify packets. The main path is client connection, packet decoding and event dispatch, proxy handlers (including sub-server redirection), then forwarding to the game server; packet events also feed commands and world/item state. The README additionally documents configuration, client metadata over HTTP, and packet debugging/modification. Some subsystems are represented from the file tree and README because their implementation was not sampled; uncertain internal wiring is omitted.

Main entry points: [`src/core/core.cpp`](https://github.com/freennzzy/gtproxy/blob/develop/src/core/core.cpp) (Core runtime), [`src/network/server.cpp`](https://github.com/freennzzy/gtproxy/blob/develop/src/network/server.cpp) (Client-facing proxy), [`src/core/handlers/connection_handler.cpp`](https://github.com/freennzzy/gtproxy/blob/develop/src/core/handlers/connection_handler.cpp) (Connection handling), [`src/network/client.cpp`](https://github.com/freennzzy/gtproxy/blob/develop/src/network/client.cpp) (Upstream connection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime and configuration"]
  node_main["Application entry<br/>[main.cpp]"]
  node_core["Core runtime<br/>[core.cpp]"]
  node_config["Configuration<br/>[config.cpp]"]
  node_web["Metadata HTTP server<br/>[web_server.cpp]"]
  node_scheduler["Task scheduler<br/>[scheduler.cpp]"]
end

subgraph group_network["Proxy networking"]
  node_proxy_server["Client-facing proxy<br/>[server.cpp]"]
  node_proxy_client["Upstream connection<br/>[client.cpp]"]
  node_forwarding["Packet forwarding"]
  node_connection["Connection handling"]
end

subgraph group_packets["Packets and events"]
  node_decoder["Packet decoder<br/>[packet_decoder.cpp]"]
  node_events["Event dispatcher<br/>[event.hpp]"]
  node_packet_types["Packet definitions<br/>[packet_types.hpp]"]
end

subgraph group_game["Game state"]
  node_world_handler["World event handling<br/>[world_handler.cpp]"]
  node_world["World and player state<br/>[world.hpp]"]
  node_item_database[("Item database<br/>[item_database.cpp]")]
end

subgraph group_extensions["Commands and scripting"]
  node_commands["Chat commands"]
  node_scripts["Lua scripting<br/>[lua_engine.cpp]"]
  node_script_loader["Script loading<br/>[script_loader.cpp]"]
end

node_user(("Proxy user"))
node_game_client(("Growtopia client"))
node_game_server(("Growtopia server"))

node_user -->|"starts proxy"| node_main
node_main -->|"runs"| node_core
node_core -->|"loads settings"| node_config
node_core -->|"creates listener"| node_proxy_server
node_core -->|"creates connection"| node_proxy_client
node_core -->|"registers handlers"| node_connection
node_core -->|"registers handler"| node_forwarding
node_core -->|"registers handler"| node_world_handler
node_core -->|"creates handler"| node_commands
node_core -.->|"starts server"| node_web
node_game_client -->|"sends packets"| node_proxy_server
node_proxy_server -->|"decodes data"| node_decoder
node_proxy_server -->|"dispatches events"| node_events
node_proxy_server -->|"dispatches connection events"| node_connection
node_connection -->|"connects upstream"| node_proxy_client
node_connection -->|"rewrites login packet"| node_proxy_server
node_proxy_client -->|"connects upstream"| node_game_server
node_forwarding -->|"forwards packets"| node_proxy_client
node_forwarding -->|"forwards packets"| node_proxy_server
node_events -->|"dispatches packet events"| node_world_handler
node_events -->|"dispatches input events"| node_commands
node_world_handler -->|"updates state"| node_world
node_connection -->|"parses item data"| node_item_database
node_events -->|"uses packet events"| node_packet_types
node_user -.->|"provides scripts"| node_scripts
node_core -.->|"loads scripts"| node_script_loader
node_script_loader -.->|"executes files"| node_scripts
node_scripts -.->|"schedules tasks"| node_scheduler
node_commands -->|"uses connection"| node_proxy_client
node_commands -->|"uses connection"| node_proxy_server

click node_main "https://github.com/freennzzy/gtproxy/blob/develop/src/main.cpp"
click node_core "https://github.com/freennzzy/gtproxy/blob/develop/src/core/core.cpp"
click node_config "https://github.com/freennzzy/gtproxy/blob/develop/src/core/config.cpp"
click node_web "https://github.com/freennzzy/gtproxy/blob/develop/src/core/web_server.cpp"
click node_scheduler "https://github.com/freennzzy/gtproxy/blob/develop/src/core/scheduler.cpp"
click node_proxy_server "https://github.com/freennzzy/gtproxy/blob/develop/src/network/server.cpp"
click node_proxy_client "https://github.com/freennzzy/gtproxy/blob/develop/src/network/client.cpp"
click node_forwarding "https://github.com/freennzzy/gtproxy/blob/develop/src/core/handlers/forwarding_handler.cpp"
click node_connection "https://github.com/freennzzy/gtproxy/blob/develop/src/core/handlers/connection_handler.cpp"
click node_decoder "https://github.com/freennzzy/gtproxy/blob/develop/src/packet/packet_decoder.cpp"
click node_events "https://github.com/freennzzy/gtproxy/blob/develop/src/event/event.hpp"
click node_packet_types "https://github.com/freennzzy/gtproxy/blob/develop/src/packet/packet_types.hpp"
click node_commands "https://github.com/freennzzy/gtproxy/blob/develop/src/command/command_handler.cpp"
click node_scripts "https://github.com/freennzzy/gtproxy/blob/develop/src/scripting/lua_engine.cpp"
click node_script_loader "https://github.com/freennzzy/gtproxy/blob/develop/src/scripting/script_loader.cpp"
click node_world_handler "https://github.com/freennzzy/gtproxy/blob/develop/src/core/handlers/world_handler.cpp"
click node_world "https://github.com/freennzzy/gtproxy/blob/develop/src/world/world.hpp"
click node_item_database "https://github.com/freennzzy/gtproxy/blob/develop/src/item/item_database.cpp"

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_main,node_core,node_config,node_web,node_scheduler,node_user,node_game_client toneBlue
class node_proxy_server,node_proxy_client,node_forwarding,node_connection toneAmber
class node_decoder,node_events,node_packet_types,node_game_server toneMint
class node_world_handler,node_world,node_item_database toneRose
class node_commands,node_scripts,node_script_loader toneIndigo
```

## Components

### Runtime and configuration

- [Application entry](https://github.com/freennzzy/gtproxy/blob/develop/src/main.cpp): `src/main.cpp`
- [Core runtime](https://github.com/freennzzy/gtproxy/blob/develop/src/core/core.cpp): `src/core/core.cpp`
- [Configuration](https://github.com/freennzzy/gtproxy/blob/develop/src/core/config.cpp): `src/core/config.cpp`
- [Metadata HTTP server](https://github.com/freennzzy/gtproxy/blob/develop/src/core/web_server.cpp): `src/core/web_server.cpp`
- [Task scheduler](https://github.com/freennzzy/gtproxy/blob/develop/src/core/scheduler.cpp): `src/core/scheduler.cpp`

### Proxy networking

- [Client-facing proxy](https://github.com/freennzzy/gtproxy/blob/develop/src/network/server.cpp): `src/network/server.cpp`
- [Upstream connection](https://github.com/freennzzy/gtproxy/blob/develop/src/network/client.cpp): `src/network/client.cpp`
- [Packet forwarding](https://github.com/freennzzy/gtproxy/blob/develop/src/core/handlers/forwarding_handler.cpp): `src/core/handlers/forwarding_handler.cpp`
- [Connection handling](https://github.com/freennzzy/gtproxy/blob/develop/src/core/handlers/connection_handler.cpp): `src/core/handlers/connection_handler.cpp`

### Packets and events

- [Packet decoder](https://github.com/freennzzy/gtproxy/blob/develop/src/packet/packet_decoder.cpp): `src/packet/packet_decoder.cpp`
- [Event dispatcher](https://github.com/freennzzy/gtproxy/blob/develop/src/event/event.hpp): `src/event/event.hpp`
- [Packet definitions](https://github.com/freennzzy/gtproxy/blob/develop/src/packet/packet_types.hpp): `src/packet/packet_types.hpp`

### Game state

- [World event handling](https://github.com/freennzzy/gtproxy/blob/develop/src/core/handlers/world_handler.cpp): `src/core/handlers/world_handler.cpp`
- [World and player state](https://github.com/freennzzy/gtproxy/blob/develop/src/world/world.hpp): `src/world/world.hpp`
- [Item database](https://github.com/freennzzy/gtproxy/blob/develop/src/item/item_database.cpp): `src/item/item_database.cpp`

### Commands and scripting

- [Chat commands](https://github.com/freennzzy/gtproxy/blob/develop/src/command/command_handler.cpp): `src/command/command_handler.cpp`
- [Lua scripting](https://github.com/freennzzy/gtproxy/blob/develop/src/scripting/lua_engine.cpp): `src/scripting/lua_engine.cpp`
- [Script loading](https://github.com/freennzzy/gtproxy/blob/develop/src/scripting/script_loader.cpp): `src/scripting/script_loader.cpp`

### Other components

- **Proxy user**
- **Growtopia client**
- **Growtopia server**

## Connections

- Proxy user → Application entry: starts proxy
- Application entry → Core runtime: runs
- Core runtime → Configuration: loads settings
- Core runtime → Client-facing proxy: creates listener
- Core runtime → Upstream connection: creates connection
- Core runtime → Connection handling: registers handlers
- Core runtime → Packet forwarding: registers handler
- Core runtime → World event handling: registers handler
- Core runtime → Chat commands: creates handler
- Core runtime → Metadata HTTP server: starts server
- Growtopia client → Client-facing proxy: sends packets
- Client-facing proxy → Packet decoder: decodes data
- Client-facing proxy → Event dispatcher: dispatches events
- Client-facing proxy → Connection handling: dispatches connection events
- Connection handling → Upstream connection: connects upstream
- Connection handling → Client-facing proxy: rewrites login packet
- Upstream connection → Growtopia server: connects upstream
- Packet forwarding → Upstream connection: forwards packets
- Packet forwarding → Client-facing proxy: forwards packets
- Event dispatcher → World event handling: dispatches packet events
- Event dispatcher → Chat commands: dispatches input events
- World event handling → World and player state: updates state
- Connection handling → Item database: parses item data
- Event dispatcher → Packet definitions: uses packet events
- Proxy user → Lua scripting: provides scripts
- Core runtime → Script loading: loads scripts
- Script loading → Lua scripting: executes files
- Lua scripting → Task scheduler: schedules tasks
- Chat commands → Upstream connection: uses connection
- Chat commands → Client-facing proxy: uses connection