# rptools/maptool architecture

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

- Interactive diagram: https://gitdiagram.com/rptools/maptool
- Repository: https://github.com/rptools/maptool

## Overview

##### Primary architectural components
- Client Application:
– This is found under packages like "net.rptools.maptool.client" (and its numerous subpackages for UI, tools, macro management, and chat).
– It uses Swing (and some JavaFX integration) for the user interface and includes modules for the drawing canvas, token management, chat panels, and extra client-side features (asset management, preferences, etc.).

- Communication/Connection Subsystem:
– The “clientserver” package and the classes for connection types (AbstractConnection, SocketConnection, WebRTCConnection) indicate an abstraction layer that handles network communications between the client and a central server.
– Also, note the "protocol" and "proto" definitions that define the message and data transfer objects. These define a standardized messaging protocol between client and server.

- Server/Backend Component:
– Found under "net.rptools.maptool.server" and related classes (MapToolServer, Handshake classes, ServerCommand, etc.).
– This component processes incoming client connections, synchronizes game state (such as campaign data, tokens, and zones), and orchestrates the overall multiplayer session.

- Core Business and Domain Logic:
– Located in the "net.rptools.maptool.model" package (and related subpackages).
– This area handles the game state (campaigns, tokens, zones, macros, drawing objects) as well as linking them to display and interactions.
- Dice and Expression Engine:
– Housed within "net.rptools.dicelib" packages, these components provide support for dice rolls and text-based formula evaluations, which are essential to role-playing games.
- Utility & Shared Libraries:
– General-purpose utilities, file I/O, networking utilities, logging, and resource management reside in "net.rptools.lib", "net.rptools.util", etc.
– Resources (graphics, sounds, language files) are stored under the "src/main/resources" tree.

##### Relationships and data flows
- The Client Application interacts with end-users via its rich UI and then dispatches commands (for chat, macro triggers, or token updates) to the Communication Subsystem.
- The Communication Subsystem provides an abstraction that allows different types of connections (socket-based, WebRTC) to pass messages from client to server and vice versa.
- The Server receives commands and updates from clients, accesses or modifies the shared game state managed by the Domain Model, and then dispatches updates back to the clients.
- The Protocol layer encapsulates message formats (defined by Proto files) that standardize data exchange.

##### Architectural patterns and design principles
- Separation of Concerns: Notice how UI code is completely separate from the domain logic (Model) and the communication layer.
- Client-Server Architecture: The clear boundary between the client (UI and local game logic) and the remotely hosted game/server.
- Plugin/Extension points: The use of macros, customizable token overlays, and support for external scripts indicate that the system is designed to be extensible.
- Event-Driven and Observer Patterns: Look for the “events” packages (e.g., MapToolEventBus, token events) which are used to notify different parts of the system about state changes.

##### Relevant technologies
- Java (core language, Gradle build system).
- Swing and JavaFX for UI.
- Protocol Buffers (Protobuf definitions in src/main/proto).
- Networking abstractions (including WebRTC and Socket connections).
- Crowdin for localization (as referenced in the README banners).

##### Overall, be as detailed as possible
- The goal is not to oversimplify the architecture but to capture the major modules and their interactions.
- Clear separation between the user event producers, the network/communication layer, and the server’s state-management systems.
- This granularity will help when evolving or debugging the architecture.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    User["User Actions"]:::user

    %% Client Layer
    subgraph "Client Layer"
        CApp["Client Application (UI, Tools, Macros)"]:::client
    end

    %% Communication Layer
    subgraph "Communication Layer"
        Comm["Communication/Connection Subsystem"]:::communication
        Proto["Protocol Definitions"]:::protocol
    end

    %% Server Layer
    subgraph "Server Layer"
        Server["Server/Backend Component"]:::server
        Domain["Core Business & Domain Logic"]:::domain
    end

    %% Shared Libraries
    subgraph "Shared Libraries"
        Dice["Dice & Expression Engine"]:::dice
        Lib["Utility Library (Lib)"]:::utility
        Util["Utility Functions (Util)"]:::utility
    end

    %% Connections
    User -->|"triggers_commands"| CApp
    CApp -->|"sends_requests"| Comm
    Comm -->|"uses_protocol"| Proto
    Comm -->|"forwards_to_server"| Server
    Server -->|"updates_state"| Domain
    Domain -->|"state_feedback"| Server
    Server -->|"pushes_updates"| Comm
    Comm -->|"returns_updates"| CApp
    CApp -->|"rolls_dice"| Dice
    CApp -->|"utilizes"| Lib
    CApp -->|"utilizes"| Util

    %% Click Events
    click CApp "https://github.com/rptools/maptool/tree/develop/src/main/java/net/rptools/maptool/client"
    click Comm "https://github.com/rptools/maptool/tree/develop/clientserver/src/main/java/net/rptools/clientserver"
    click Server "https://github.com/rptools/maptool/tree/develop/src/main/java/net/rptools/maptool/server"
    click Domain "https://github.com/rptools/maptool/tree/develop/src/main/java/net/rptools/maptool/model"
    click Dice "https://github.com/rptools/maptool/tree/develop/src/main/java/net/rptools/dicelib"
    click Lib "https://github.com/rptools/maptool/tree/develop/src/main/java/net/rptools/lib"
    click Util "https://github.com/rptools/maptool/tree/develop/src/main/java/net/rptools/util"
    click Proto "https://github.com/rptools/maptool/tree/develop/src/main/proto"

    %% Styles
    classDef client fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef communication fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef server fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef domain fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef dice fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef utility fill:#e2e3e5,stroke:#d6d8db,stroke-width:2px;
    classDef protocol fill:#fefefe,stroke:#ced4da,stroke-width:2px;
    classDef user fill:#d4d4d4,stroke:#4d4d4d,stroke-width:2px;
```
