# papermc/velocity architecture

> Architecture diagram of the GitHub repository papermc/velocity, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/papermc/velocity
- Repository: https://github.com/papermc/velocity

## Overview

##### Main Components
- API Module: This module (located under “api”) contains the public interfaces for plugins, events, commands, network communication, scheduling, and utilities. It defines core abstractions such as Plugin, ProxyServer, CommandManager, EventManager, etc.
- Proxy Module: The “proxy” directory represents the main runtime for the proxy itself. This module handles network connections, session handling, command processing, player connections, and routing to backend servers.
- Native Module: Under “native”, this part focuses on native code integrations (written in C, JNI components) for performance-critical tasks such as encryption, compression, and other low-level operations.
- Build and Configuration: The configuration files include Gradle build scripts, checkstyle configurations, and other build‐logic, emphasizing that Velocity is built using Gradle with clear separation of concerns among modules.
- Additional Components: The existence of dedicated directories for command handling, event modules, encryption/decryption, and plugin loading (including support for plugin annotation processing in the API) indicates that the design leverages event-driven and plugin-based extensibility.

##### Relationships and Interactions
- The API defines interfaces that are implemented by the Proxy and other modules – for example, your ProxyServer relies on Plugin, Event, and Command APIs.
- The Proxy module interacts directly with network layers, receiving client connections, handling protocols, and routing packets. It uses events and commands defined in the API.
- The Native module acts as a performance “accelerator” for both the proxy and API layers by providing optimized native implementations that the proxy can call when necessary.

##### Architectural Patterns and Design Principles
- Modularization: The project is split into clearly demarcated modules (api, proxy, native) that can be updated and maintained separately.
- Plugin-based Extensibility: With dedicated API packages for plugin management and plugin description, there’s a strong emphasis on runtime extensibility.
- Separation of Concerns: Networking, command handling, plugin management, and native operations are each encapsulated in their own layers.

##### Relevant Technologies and Frameworks
- Java and Gradle: The project is built in Java using Gradle (as indicated by the build.gradle.kts files and Gradle wrapper).
- JNI/Natives: For performance enhancements, the native module integrates C code for encryption and compression.
- Minecraft-specific Protocol Handling: Custom packet classes, protocol utilities, and event structures show that it’s tightly integrated with Minecraft’s networking and protocol conventions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    Client["Minecraft Client"]:::clientClass
    Backend["Backend Minecraft Servers"]:::backendClass

    %% API Module Subgraph
    subgraph "API Module"
        API_Module["API Module"]:::apiClass
        API_Commands["API Commands"]:::apiClass
        API_Events["API Events"]:::apiClass
        API_Plugins["API Plugins"]:::apiClass
        API_Module --> API_Commands
        API_Module --> API_Events
        API_Module --> API_Plugins
    end

    %% Proxy Module Subgraph
    subgraph "Proxy Module"
        Proxy_Module["Proxy Module"]:::proxyClass
        P_Connection["Connection Manager"]:::proxyClass
        P_Network["Network Processing"]:::proxyClass
        Proxy_Commands["Proxy Command Handling"]:::proxyClass
        Proxy_Events["Proxy Event Management"]:::proxyClass
        Proxy_Plugin_Loader["Plugin Loader"]:::proxyClass
        Proxy_Module --> P_Connection
        Proxy_Module --> P_Network
        Proxy_Module --> Proxy_Commands
        Proxy_Module --> Proxy_Events
        Proxy_Module --> Proxy_Plugin_Loader
    end

    %% Native Module Subgraph
    subgraph "Native Module"
        Native_Module["Native Module (Encryption,Compression)"]:::nativeClass
    end

    %% Build and Configuration
    Build_Config["Build & Configuration"]:::buildClass

    %% Interactions
    Client -->|"sends_connection"| P_Connection
    P_Connection -->|"routes_to"| Backend
    P_Network -->|"calls_native"| Native_Module
    P_Network -->|"dispatches_event"| API_Events
    Proxy_Commands -->|"executes_command"| API_Commands
    Proxy_Plugin_Loader -->|"loads_plugin"| API_Plugins
    Build_Config --- API_Module
    Build_Config --- Proxy_Module

    %% Click Events
    click API_Module "https://github.com/papermc/velocity/tree/dev/3.0.0/api/"
    click Proxy_Module "https://github.com/papermc/velocity/tree/dev/3.0.0/proxy/"
    click Native_Module "https://github.com/papermc/velocity/tree/dev/3.0.0/native/"
    click Build_Config "https://github.com/papermc/velocity/blob/dev/3.0.0/build.gradle.kts"
    click API_Commands "https://github.com/papermc/velocity/tree/dev/3.0.0/api/src/main/java/com/velocitypowered/api/command/"
    click Proxy_Commands "https://github.com/papermc/velocity/tree/dev/3.0.0/proxy/src/main/java/com/velocitypowered/proxy/command/"
    click API_Events "https://github.com/papermc/velocity/tree/dev/3.0.0/api/src/main/java/com/velocitypowered/api/event/"
    click Proxy_Events "https://github.com/papermc/velocity/tree/dev/3.0.0/proxy/src/main/java/com/velocitypowered/proxy/event/"
    click API_Plugins "https://github.com/papermc/velocity/tree/dev/3.0.0/api/src/main/java/com/velocitypowered/api/plugin/"
    click Proxy_Plugin_Loader "https://github.com/papermc/velocity/tree/dev/3.0.0/proxy/src/main/java/com/velocitypowered/proxy/plugin/"

    %% Styles
    classDef apiClass fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef proxyClass fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef nativeClass fill:#FFA500,stroke:#000,stroke-width:2px;
    classDef buildClass fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef clientClass fill:#FFFFE0,stroke:#000,stroke-width:2px;
    classDef backendClass fill:#F4A460,stroke:#000,stroke-width:2px;
```
