# pymodbus-dev/pymodbus architecture

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

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

## Overview

##### Project type and purpose
- PyModbus is a protocol library and toolkit that implements the Modbus protocol in Python.
- It provides five main parts: a client, a server, a REPL, a web‐based simulator, and example scripts.
- It’s not a monolithic application but a layered, extensible library used by other applications (e.g., Home-Assistant).

##### File structure
- Top‐level directories:
- pymodbus/ – main Python package, subdivided into subpackages: client, server, framer, transport, transaction, pdu, datastore, simulator, utilities.
- examples/ – usage examples for client, server, simulator.
- test/ – test suite organized by module.
- doc/ – Sphinx documentation including an architecture guide.
- .github/, .devcontainer/ – CI and development config.
- Key configuration files: pyproject.toml, MANIFEST.in, check_ci.sh, .github/workflows/*.yml.
- Build artifacts: build/, dist/.

##### README for additional insights
- The README describes the five parts and outlines supported transports (TCP, UDP, TLS, serial), supported framing (ascii, RTU, socket), and datastores.

##### Elements
- Clear labels for each package/component (e.g., “pymodbus.client”, “pymodbus.framer.ascii”)
- Green for application APIs (client, server, repl, simulator)
- Orange for external systems (real devices, browsers)

##### Final advice
- Grouping (transport backends together, framing strategies together).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Application API Layer
    subgraph "Application API Layer"
        direction TB
        ClientAPI["pymodbus.client"]:::api
        subgraph "Server API"
            direction TB
            ServerBase["base.py"]:::api
            RequestHandler["requesthandler.py"]:::api
            ServerCore["server.py"]:::api
        end
        REPL["pymodbus.repl"]:::api
        subgraph "Simulator Core"
            direction TB
            SimCore["simcore.py"]:::api
            SimData["simdata.py"]:::api
        end
        subgraph "Simulator Web UI"
            direction TB
            HTTPServer["http_server.py"]:::api
            CustomActions["custom_actions.py"]:::api
            WebIndex["index.html"]:::api
            WebCSS["pymodbus.css"]:::api
            WebWelcome["welcome.html"]:::api
        end
    end

    %% Protocol Layer
    subgraph "Protocol Layer"
        direction TB
        subgraph "Framing"
            direction TB
            FramerASCII["ascii.py"]:::core
            FramerRTU["rtu.py"]:::core
            FramerSocket["socket.py"]:::core
            FramerTLS["tls.py"]:::core
        end
        subgraph "PDU"
            direction TB
            PDUCore["pdu.py"]:::core
            BitMsg["bit_message.py"]:::core
            RegMsg["register_message.py"]:::core
        end
        Transaction["transaction.py"]:::core
    end

    %% Transport Layer
    subgraph "Transport Layer"
        direction TB
        TransportCore["transport.py"]:::core
        SerialTransport["serialtransport.py"]:::core
    end

    %% Datastore
    subgraph "Datastore"
        direction TB
        ContextStore["context.py"]:::core
        Store["store.py"]:::core
        RemoteStore["remote.py"]:::core
        SimStore["simulator.py"]:::core
    end

    %% Examples & Tests
    subgraph "Examples & Demos"
        direction TB
        Examples["examples"]:::example
    end
    subgraph "Test Harness"
        direction TB
        Tests["test"]:::example
    end

    %% External Systems
    ExternalDevice["Real Modbus Devices"]:::external
    Browser["Web Browser"]:::external

    %% Data Flows
    ClientAPI -->|"invoke"| TransportCore
    TransportCore -->|"raw bytes"| FramerASCII
    FramerASCII -->|"frame decode"| PDUCore
    PDUCore -->|"message"| Transaction
    Transaction -->|"response"| ClientAPI

    ExternalDevice -->|"raw bytes"| TransportCore
    TransportCore --> FramerRTU
    FramerRTU --> PDUCore
    PDUCore --> Transaction
    Transaction --> ServerCore
    ServerCore -->|"build response"| FramerSocket
    FramerSocket --> TransportCore
    TransportCore --> ClientAPI

    REPL --> ClientAPI
    REPL --> ServerCore

    HTTPServer --> SimCore
    SimCore --> ContextStore
    HTTPServer --> Browser

    Examples --> ClientAPI
    Examples --> ServerCore
    Examples --> HTTPServer

    Tests --> ClientAPI
    Tests --> ServerCore
    Tests --> FramerASCII
    Tests --> PDUCore
    Tests --> Transaction
    Tests --> TransportCore
    Tests --> SimCore

    %% Click Events
    click ClientAPI "https://github.com/pymodbus-dev/pymodbus/tree/dev/pymodbus/client/"
    click ServerBase "https://github.com/pymodbus-dev/pymodbus/blob/dev/pymodbus/server/base.py"
    click RequestHandler "https://github.com/pymodbus-dev/pymodbus/blob/dev/pymodbus/server/requesthandler.py"
    click ServerCore "https://github.com/pymodbus-dev/pymodbus/blob/dev/pymodbus/server/server.py"
    click FramerASCII "https://github.com/pymodbus-dev/pymodbus/blob/dev/pymodbus/framer/ascii.py"
    click FramerRTU "https://github.com/pymodbus-dev/pymodbus/blob/dev/pymodbus/framer/rtu.py"
    click FramerSocket "https://github.com/pymodbus-dev/pymodbus/blob/dev/pymodbus/framer/socket.py"
    click FramerTLS "https://github.com/pymodbus-dev/pymodbus/blob/dev/pymodbus/framer/tls.py"
    click PDUCore "https://github.com/pymodbus-dev/pymodbus/blob/dev/pymodbus/pdu/pdu.py"
    click Transaction "https://github.com/pymodbus-dev/pymodbus/blob/dev/pymodbus/transaction/transaction.py"
    click TransportCore "https://github.com/pymodbus-dev/pymodbus/blob/dev/pymodbus/transport/transport.py"
    click SerialTransport "https://github.com/pymodbus-dev/pymodbus/blob/dev/pymodbus/transport/serialtransport.py"
    click ContextStore "https://github.com/pymodbus-dev/pymodbus/blob/dev/pymodbus/datastore/context.py"
    click Store "https://github.com/pymodbus-dev/pymodbus/blob/dev/pymodbus/datastore/store.py"
    click RemoteStore "https://github.com/pymodbus-dev/pymodbus/blob/dev/pymodbus/datastore/remote.py"
    click SimStore "https://github.com/pymodbus-dev/pymodbus/blob/dev/pymodbus/datastore/simulator.py"
    click SimCore "https://github.com/pymodbus-dev/pymodbus/blob/dev/pymodbus/simulator/simcore.py"
    click SimData "https://github.com/pymodbus-dev/pymodbus/blob/dev/pymodbus/simulator/simdata.py"
    click HTTPServer "https://github.com/pymodbus-dev/pymodbus/blob/dev/pymodbus/server/simulator/http_server.py"
    click CustomActions "https://github.com/pymodbus-dev/pymodbus/blob/dev/pymodbus/server/simulator/custom_actions.py"
    click WebIndex "https://github.com/pymodbus-dev/pymodbus/blob/dev/pymodbus/server/simulator/web/index.html"
    click WebCSS "https://github.com/pymodbus-dev/pymodbus/blob/dev/pymodbus/server/simulator/web/pymodbus.css"
    click WebWelcome "https://github.com/pymodbus-dev/pymodbus/blob/dev/pymodbus/server/simulator/web/welcome.html"
    click Examples "https://github.com/pymodbus-dev/pymodbus/tree/dev/examples/"
    click Tests "https://github.com/pymodbus-dev/pymodbus/tree/dev/test/"

    %% Styles
    classDef core fill:#e0f7fa,stroke:#006064,color:#006064
    classDef api fill:#e8f5e9,stroke:#2e7d32,color:#2e7d32
    classDef external fill:#fff3e0,stroke:#ef6c00,color:#ef6c00
    classDef example fill:#fafafa,stroke:#9e9e9e,color:#616161,stroke-dasharray: 5 5
```
