# piemc-dev/piemc architecture

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

- Interactive diagram: https://gitdiagram.com/piemc-dev/piemc
- Repository: https://github.com/piemc-dev/piemc

## Overview

##### Main Components
- Server Entrypoint & Core: Represented by files like start.py/start.sh/start.cmd and the main package (piemc/__main__.py). This is where the server is initialized.
- Server Module: The piemc/server.py likely encapsulates the main network loop, handling client connections and communications.
- Command Handling: The directory piemc/commands (especially piemc/commands/piemc.py) manages command execution. This component processes administrative or in-game commands.
- Event and Context Handlers: The handlers folder (piemc/handlers) is broken into parts:
- Command Handler (piemc/handlers/command.py) for command processing.
- Context handling the runtime context (piemc/handlers/context/context.py) that might be used for managing per-connection or global state.
- Event handler (piemc/handlers/events.py) which likely listens for and dispatches events (from network or game interactions).
- Language & Localization: The piemc/lang directory (with various .yml files) indicates multi-language support used by components such as the lang handler (piemc/handlers/lang.py) for translating server messages.
- Logging & Meta Information: With a dedicated logger (piemc/handlers/logger.py) and meta module (piemc/meta/protocol_info.py) that likely defines protocol constants, these support debugging and protocol integrity.

##### Relationships and Interactions
- The Start Scripts (start.[py, sh, cmd]) boot up the system, triggering initialization routines in the main module and server module.
- Once running, the Server (piemc/server.py) listens for client connections. Incoming data traverses to:
- The Protocol/Meta component (piemc/meta/protocol_info.py) for format and protocol-specific checks.
- The Event system (piemc/handlers/events.py) which dispatches activities to relevant modules.
- Commands issued by clients or admins are intercepted by the Command Handler (piemc/commands/piemc.py and handlers/command.py) and then processed accordingly.
- Supporting components—Language (for internationalized messages) via piemc/lang and contextual configurations via piemc/config.py, provide the necessary scaffolding for dynamic server responses.
- The Logger (piemc/handlers/logger.py) tracks and records server activity, errors, and debugging information.

##### Architectural Patterns & Design Principles
- Modular Design: The code is separated into distinct packages (commands, handlers, lang, meta) indicating a modular structure that isolates features and responsibilities.
- Event-Driven Architecture: The presence of event and context handlers suggests that the server responds to events (e.g., networking events, command inputs) in an asynchronous or decoupled manner.
- Extensibility: With planned features such as Plugins, Permissions, and Commands, the design hints at extensibility, where additional features can be inserted as separate modules and integrated via defined interfaces.

##### Relevant Technologies & Frameworks
- Python is the primary language.
- YAML files in piemc/lang indicate the use of YAML for localization.
- Standard Python packaging and module initialization flows (using __init__.py files) are central.
- GitHub workflows (.github/workflows) indicate CI/CD integration, especially for code quality and dependency management.

- From Start Scripts → Server Entrypoint → Network Module.
- From Network Module → Event Dispatcher/Protocol Handler.
- From Command Execution (via client commands) → Command Handler and Context Manager.
- From all modules → Logger for recording activities.

##### Final Elements
- Subsequent interactions within the server such as: network input → protocol analysis → event/command processing → logging/response generation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    Client["Client (Minecraft Bedrock)"]:::client

    %% Bootstrap Subgraph: Start Scripts & Server Entrypoint
    subgraph "Bootstrap"
        StartScripts["Start Scripts"]:::bootstrap
        Entrypoint["Server Entrypoint"]:::bootstrap
    end

    %% Core Networking Module
    Network["Network Module"]:::networking

    %% Protocol and Meta Information
    Meta["Protocol & Meta Info"]:::support

    %% Event and Command Processing
    EventDisp["Event Dispatcher"]:::processing
    CmdHandler["Command Handler"]:::processing
    CmdProc["Command Processing Module"]:::processing
    ContextMgmt["Context Management"]:::processing
    LangHandler["Language Handler"]:::processing
    LangFiles["Language Files"]:::support

    %% Support Utilities
    Logger["Logger"]:::support
    Config["Configuration"]:::support

    %% Connections
    Client -->|"connects"| Network

    StartScripts -->|"initializes"| Entrypoint
    Entrypoint -->|"boots"| Network
    Entrypoint -->|"loads"| Config
    Entrypoint --> Logger

    Network -->|"validates"| Meta
    Network -->|"listens"| EventDisp
    Network --> Logger

    EventDisp -->|"dispatches"| CmdHandler
    EventDisp -->|"updates"| ContextMgmt
    EventDisp --> LangHandler
    EventDisp --> Logger

    CmdHandler -->|"processes"| CmdProc
    CmdHandler --> Logger

    LangHandler --> LangFiles

    %% Click Events
    click Entrypoint "https://github.com/piemc-dev/piemc/blob/main/piemc/__main__.py"
    click StartScripts "https://github.com/piemc-dev/piemc/blob/main/start.py"
    click Network "https://github.com/piemc-dev/piemc/blob/main/piemc/server.py"
    click CmdProc "https://github.com/piemc-dev/piemc/blob/main/piemc/commands/piemc.py"
    click CmdHandler "https://github.com/piemc-dev/piemc/blob/main/piemc/handlers/command.py"
    click EventDisp "https://github.com/piemc-dev/piemc/blob/main/piemc/handlers/events.py"
    click ContextMgmt "https://github.com/piemc-dev/piemc/blob/main/piemc/handlers/context/context.py"
    click LangHandler "https://github.com/piemc-dev/piemc/blob/main/piemc/handlers/lang.py"
    click LangFiles "https://github.com/piemc-dev/piemc/tree/main/piemc/lang"
    click Logger "https://github.com/piemc-dev/piemc/blob/main/piemc/handlers/logger.py"
    click Meta "https://github.com/piemc-dev/piemc/blob/main/piemc/meta/protocol_info.py"
    click Config "https://github.com/piemc-dev/piemc/blob/main/piemc/config.py"

    %% Styles
    classDef networking fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef processing fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef support fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef bootstrap fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef client fill:#FFD700,stroke:#000,stroke-width:2px;
```
