# geekcoding007/flexmodbus architecture

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

- Interactive diagram: https://gitdiagram.com/geekcoding007/flexmodbus
- Repository: https://github.com/geekcoding007/flexmodbus

## Overview

FlexModbus is a configurable Home Assistant integration for reading and writing user-selected Modbus TCP registers, including RTU framing over TCP. The main workflow is device setup, register definition (or YAML import), shared polling and decoding, then exposure as Sensor, Number, and Switch entities; writable entities send values back through the coordinator. The graph also preserves connection configuration and optional log filtering. Polling internals are sampled, while some flow and setup links rely on the excerpted-file reference index or README; unsampled platform details are not inferred.

Main entry points: [`custom_components/flexmodbus/__init__.py`](https://github.com/geekcoding007/flexmodbus/blob/main/custom_components/flexmodbus/__init__.py) (Entry setup), [`custom_components/flexmodbus/coordinator.py`](https://github.com/geekcoding007/flexmodbus/blob/main/custom_components/flexmodbus/coordinator.py) (Polling coordinator), [`custom_components/flexmodbus/config_flow.py`](https://github.com/geekcoding007/flexmodbus/blob/main/custom_components/flexmodbus/config_flow.py) (Config and options flow), [`custom_components/flexmodbus/register.py`](https://github.com/geekcoding007/flexmodbus/blob/main/custom_components/flexmodbus/register.py) (Register parsing and decoding)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Setup and Configuration"]
  node_config_flow["Config and options flow<br/>[config_flow.py]"]
  node_yaml_import["YAML importer<br/>[yaml_import.py]"]
  node_setup_entry["Entry setup<br/>[__init__.py]"]
  node_constants["Integration settings<br/>[const.py]"]
  node_log_filter["Optional log filter<br/>[log_filter.py]"]
end

subgraph group_registers["Register Definitions"]
  node_register_defs["Register parsing and decoding<br/>[register.py]"]
end

subgraph group_runtime["Polling and Connection"]
  node_coordinator["Polling coordinator<br/>[coordinator.py]"]
  node_connection["TCP client factory<br/>[connection.py]"]
end

subgraph group_entities["Home Assistant Entities"]
  node_sensor["Sensor entities<br/>[sensor.py]"]
  node_number["Number entities<br/>[number.py]"]
  node_switch["Switch entities<br/>[switch.py]"]
  node_entity_base["Shared entity behavior<br/>[entity.py]"]
end

node_user(("Home Assistant user"))
node_modbus_device(("Modbus device or gateway"))

node_user -->|"configures device"| node_config_flow
node_user -->|"defines registers"| node_config_flow
node_config_flow -->|"converts YAML"| node_yaml_import
node_yaml_import -->|"validates registers"| node_register_defs
node_config_flow -->|"parses register settings"| node_register_defs
node_setup_entry -->|"parses entry registers"| node_register_defs
node_setup_entry -->|"creates client"| node_connection
node_setup_entry -->|"starts polling"| node_coordinator
node_setup_entry -->|"enables optionally"| node_log_filter
node_coordinator -->|"reads and writes registers"| node_modbus_device
node_coordinator -->|"decodes values"| node_register_defs
node_sensor -->|"inherits behavior"| node_entity_base
node_number -->|"inherits behavior"| node_entity_base
node_switch -->|"inherits behavior"| node_entity_base
node_sensor -->|"uses runtime data"| node_coordinator
node_number -->|"reads and writes values"| node_coordinator
node_switch -->|"reads and writes values"| node_coordinator
node_setup_entry -->|"forwards platform setup"| node_sensor
node_setup_entry -->|"forwards platform setup"| node_number
node_setup_entry -->|"forwards platform setup"| node_switch
node_config_flow -->|"tests connection"| node_modbus_device
node_constants -.->|"defines register options"| node_register_defs

click node_config_flow "https://github.com/geekcoding007/flexmodbus/blob/main/custom_components/flexmodbus/config_flow.py"
click node_yaml_import "https://github.com/geekcoding007/flexmodbus/blob/main/custom_components/flexmodbus/yaml_import.py"
click node_setup_entry "https://github.com/geekcoding007/flexmodbus/blob/main/custom_components/flexmodbus/__init__.py"
click node_constants "https://github.com/geekcoding007/flexmodbus/blob/main/custom_components/flexmodbus/const.py"
click node_log_filter "https://github.com/geekcoding007/flexmodbus/blob/main/custom_components/flexmodbus/log_filter.py"
click node_register_defs "https://github.com/geekcoding007/flexmodbus/blob/main/custom_components/flexmodbus/register.py"
click node_coordinator "https://github.com/geekcoding007/flexmodbus/blob/main/custom_components/flexmodbus/coordinator.py"
click node_connection "https://github.com/geekcoding007/flexmodbus/blob/main/custom_components/flexmodbus/connection.py"
click node_sensor "https://github.com/geekcoding007/flexmodbus/blob/main/custom_components/flexmodbus/sensor.py"
click node_number "https://github.com/geekcoding007/flexmodbus/blob/main/custom_components/flexmodbus/number.py"
click node_switch "https://github.com/geekcoding007/flexmodbus/blob/main/custom_components/flexmodbus/switch.py"
click node_entity_base "https://github.com/geekcoding007/flexmodbus/blob/main/custom_components/flexmodbus/entity.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_config_flow,node_yaml_import,node_setup_entry,node_constants,node_log_filter,node_user toneBlue
class node_register_defs toneAmber
class node_coordinator,node_connection toneMint
class node_sensor,node_number,node_switch,node_entity_base toneRose
class node_modbus_device toneIndigo
```

## Components

### Setup and Configuration

- [Config and options flow](https://github.com/geekcoding007/flexmodbus/blob/main/custom_components/flexmodbus/config_flow.py): `custom_components/flexmodbus/config_flow.py`
- [YAML importer](https://github.com/geekcoding007/flexmodbus/blob/main/custom_components/flexmodbus/yaml_import.py): `custom_components/flexmodbus/yaml_import.py`
- [Entry setup](https://github.com/geekcoding007/flexmodbus/blob/main/custom_components/flexmodbus/__init__.py): `custom_components/flexmodbus/__init__.py`
- [Integration settings](https://github.com/geekcoding007/flexmodbus/blob/main/custom_components/flexmodbus/const.py): `custom_components/flexmodbus/const.py`
- [Optional log filter](https://github.com/geekcoding007/flexmodbus/blob/main/custom_components/flexmodbus/log_filter.py): `custom_components/flexmodbus/log_filter.py`

### Register Definitions

- [Register parsing and decoding](https://github.com/geekcoding007/flexmodbus/blob/main/custom_components/flexmodbus/register.py): `custom_components/flexmodbus/register.py`

### Polling and Connection

- [Polling coordinator](https://github.com/geekcoding007/flexmodbus/blob/main/custom_components/flexmodbus/coordinator.py): `custom_components/flexmodbus/coordinator.py`
- [TCP client factory](https://github.com/geekcoding007/flexmodbus/blob/main/custom_components/flexmodbus/connection.py): `custom_components/flexmodbus/connection.py`

### Home Assistant Entities

- [Sensor entities](https://github.com/geekcoding007/flexmodbus/blob/main/custom_components/flexmodbus/sensor.py): `custom_components/flexmodbus/sensor.py`
- [Number entities](https://github.com/geekcoding007/flexmodbus/blob/main/custom_components/flexmodbus/number.py): `custom_components/flexmodbus/number.py`
- [Switch entities](https://github.com/geekcoding007/flexmodbus/blob/main/custom_components/flexmodbus/switch.py): `custom_components/flexmodbus/switch.py`
- [Shared entity behavior](https://github.com/geekcoding007/flexmodbus/blob/main/custom_components/flexmodbus/entity.py): `custom_components/flexmodbus/entity.py`

### Other components

- **Home Assistant user**
- **Modbus device or gateway**

## Connections

- Home Assistant user → Config and options flow: configures device (evidence: `README.md`)
- Home Assistant user → Config and options flow: defines registers (evidence: `README.md`)
- Config and options flow → YAML importer: converts YAML (evidence: `custom_components/flexmodbus/config_flow.py`)
- YAML importer → Register parsing and decoding: validates registers (evidence: `custom_components/flexmodbus/yaml_import.py`)
- Config and options flow → Register parsing and decoding: parses register settings (evidence: `custom_components/flexmodbus/config_flow.py`)
- Entry setup → Register parsing and decoding: parses entry registers (evidence: `custom_components/flexmodbus/__init__.py`)
- Entry setup → TCP client factory: creates client (evidence: `custom_components/flexmodbus/__init__.py`)
- Entry setup → Polling coordinator: starts polling (evidence: `custom_components/flexmodbus/__init__.py`)
- Entry setup → Optional log filter: enables optionally (evidence: `custom_components/flexmodbus/__init__.py`)
- Polling coordinator → Modbus device or gateway: reads and writes registers (evidence: `custom_components/flexmodbus/coordinator.py`)
- Polling coordinator → Register parsing and decoding: decodes values (evidence: `custom_components/flexmodbus/coordinator.py`)
- Sensor entities → Shared entity behavior: inherits behavior (evidence: `custom_components/flexmodbus/sensor.py`)
- Number entities → Shared entity behavior: inherits behavior (evidence: `custom_components/flexmodbus/number.py`)
- Switch entities → Shared entity behavior: inherits behavior (evidence: `custom_components/flexmodbus/switch.py`)
- Sensor entities → Polling coordinator: uses runtime data (evidence: `custom_components/flexmodbus/sensor.py`)
- Number entities → Polling coordinator: reads and writes values (evidence: `custom_components/flexmodbus/number.py`)
- Switch entities → Polling coordinator: reads and writes values (evidence: `custom_components/flexmodbus/switch.py`)
- Entry setup → Sensor entities: forwards platform setup (evidence: `custom_components/flexmodbus/__init__.py`)
- Entry setup → Number entities: forwards platform setup (evidence: `custom_components/flexmodbus/__init__.py`)
- Entry setup → Switch entities: forwards platform setup (evidence: `custom_components/flexmodbus/__init__.py`)
- Config and options flow → Modbus device or gateway: tests connection (evidence: `README.md`)
- Integration settings → Register parsing and decoding: defines register options (evidence: `custom_components/flexmodbus/register.py`)
