# slowtec/tokio-modbus architecture

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

- Interactive diagram: https://gitdiagram.com/slowtec/tokio-modbus
- Repository: https://github.com/slowtec/tokio-modbus

## Overview

##### Project Type and Purpose
- The project is a library (not a standalone application) that provides both client and server implementations of the Modbus protocol over TCP and RTU.
- It is built in Rust and leverages Tokio for asynchronous operations, while also offering synchronous API variants.
- The README highlights support for different features (e.g., “rtu”, “tcp”, “rtu-server” etc.) and offers example usages in the examples folder. This indicates a clear separation of concerns and configurable behavior via Cargo features.

##### File Structure
- The top-level directories and files (e.g., Cargo.toml, README.md, LICENSES, .github workflows, etc.) show that it is a well-maintained open source Rust library.
- The src directory is structured into multiple key submodules:
- src/client: Contains implementations for the client APIs with separate modules for RTU and TCP, and even a dedicated “sync” subdirectory for blocking implementations.
- src/server: Contains modules for the server implementations, including RTU and TCP variants plus an “rtu_over_tcp” for that case.
- src/codec and src/frame: Handle the encoding/decoding and framing of Modbus messages respectively, which are critical for protocol compliance.
- src/service: Likely used to bridge or wrap common functionalities between client/server operations.
- Additional modules like src/slave and src/prelude offer abstraction and shared functionality throughout the library.
- The examples directory provides multiple example programs to demonstrate the usage of various API modes – highlighting the intended extensibility.

##### Key Components and Their Relationships
- Tokio Runtime: As the core asynchronous runtime environment supporting non-blocking operations.
- Client Module:
▪ Asynchronous Clients: Separate nodes for TCP and RTU clients.
▪ Synchronous Clients: Segregated under “sync” for blocking operations.
- Server Module:
▪ Asynchronous Servers: Including variations for TCP, RTU, and RTU-over-TCP.
- Protocol Encoding Layers:
▪ Codec Module: Handles low-level encoding/decoding of Modbus protocol messages.
▪ Frame Module: Deals with framing and possibly message boundaries.
- Service Module: This can be shown as an intermediary that ties client/server operations together or abstracts communication details.

- Interactions:
- The client components send and receive Modbus requests/responses via underlying layers (codec and frame).
- The server components accept incoming communication, process requests, and provide responses, also utilizing codec and frame modules.

##### Architectural Patterns/Design Principles
- Separation of Concerns: Each module (client, server, codec, frame, service) is designed for a specific aspect of the protocol handling.
- Modularity and Extensibility: The use of Cargo features indicates that functionally distinct components (asynchronous vs synchronous, TCP vs RTU) can be enabled or disabled as needed.
- Clear API Boundaries: The library provides clear divisions between client and server roles, abstracting the differences between blocking and non-blocking operations.

##### Elements
- That both client and server are built upon the Tokio event loop.
- Network interfaces (TCP/RTU connections)
- API implementations (async vs sync)
- Utility layers (codec, frame, service).

- Under the Client branch, show separate nodes (or submodules) for asynchronous (TCP/RTU) and synchronous modes.
- Optionally, add a separate section for “Examples” to indicate that there are sample implementations that demonstrate these interactions.

## Diagram (Mermaid)

```mermaid
flowchart TB
    TR["Tokio Runtime"]:::runtime

    subgraph "Client Modules"
        A1["Asynchronous TCP Client"]:::client
        A2["Asynchronous RTU Client"]:::client
        A3["Synchronous TCP Client"]:::client
        A4["Synchronous RTU Client"]:::client
    end

    SVC["Service Module"]:::service

    subgraph "Protocol Handling"
        PC["Protocol Codec Module"]:::protocol
        PF["Protocol Frame Module"]:::protocol
    end

    subgraph "Server Modules"
        S1["Asynchronous TCP Server"]:::server
        S2["Asynchronous RTU Server"]:::server
        S3["RTU-over-TCP Server"]:::server
    end

    TR --> A1
    TR --> A2
    TR --> A3
    TR --> A4

    A1 --> SVC
    A2 --> SVC
    A3 --> SVC
    A4 --> SVC

    SVC --> PC
    PC --> PF

    PF --> S1
    PF --> S2
    PF --> S3

    click TR "https://github.com/slowtec/tokio-modbus/blob/main/src/lib.rs"
    click A1 "https://github.com/slowtec/tokio-modbus/blob/main/src/client/tcp.rs"
    click A2 "https://github.com/slowtec/tokio-modbus/blob/main/src/client/rtu.rs"
    click A3 "https://github.com/slowtec/tokio-modbus/blob/main/src/client/sync/tcp.rs"
    click A4 "https://github.com/slowtec/tokio-modbus/blob/main/src/client/sync/rtu.rs"
    click S1 "https://github.com/slowtec/tokio-modbus/blob/main/src/server/tcp.rs"
    click S2 "https://github.com/slowtec/tokio-modbus/blob/main/src/server/rtu.rs"
    click S3 "https://github.com/slowtec/tokio-modbus/blob/main/src/server/rtu_over_tcp.rs"
    click PC "https://github.com/slowtec/tokio-modbus/blob/main/src/codec/mod.rs"
    click PF "https://github.com/slowtec/tokio-modbus/blob/main/src/frame/mod.rs"
    click SVC "https://github.com/slowtec/tokio-modbus/blob/main/src/service/mod.rs"

    classDef runtime fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef client fill:#ccffcc,stroke:#009900,stroke-width:2px;
    classDef server fill:#ccccff,stroke:#0000cc,stroke-width:2px;
    classDef protocol fill:#ffffcc,stroke:#999900,stroke-width:2px;
    classDef service fill:#ffe6cc,stroke:#cc6600,stroke-width:2px;
```
