# tanvir-ahmed-m4/hub4com architecture

> Architecture diagram of the GitHub repository tanvir-ahmed-m4/hub4com, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tanvir-ahmed-m4/hub4com
- Repository: https://github.com/tanvir-ahmed-m4/hub4com

## Overview

#### Purpose and runtime
hub4com is a native Windows communications hub in the com0com ecosystem. It opens serial or TCP endpoints, routes data/control signals among them, and can transform streams through dynamically loaded filter plugins. The main executable is built from `hub4com.cpp`, with Visual C++ project metadata in `hub4com.vcproj` and solution `hub4com.sln`.

#### Process startup and configuration
`hub4com.cpp` is the command-line entry point. It parses ordered options and endpoint declarations, including inline/load-file configurations, then builds the hub topology. Configuration is operationally significant: route declarations, selected port driver, queue/reconnect behavior, and filter attachment determine runtime behavior. Core command/status messaging is centralized in `hubmsg.cpp` and `hubmsg.h`.

#### Hub orchestration
`comhub.cpp` / `comhub.h` implement the central coordinator over all opened ports. It owns lifecycle sequencing and distributes port events into routing/filter processing. `timer.cpp` / `timer.h` support timed behavior such as reconnect intervals, making connection management part of the hub control plane rather than a transport-specific concern.

#### Ports and endpoint-driver boundary
The abstract port contract is defined by `port.cpp` / `port.h`. Concrete endpoint implementations are supplied as plugins, separating the core hub from Windows serial and socket transport details:
- Serial transport: `plugins/serial/port.cpp`, `plugins/serial/comport.cpp`, `plugins/serial/comio.cpp`
- TCP transport: `plugins/tcp/port.cpp`, `plugins/tcp/comport.cpp`, `plugins/tcp/comio.cpp`
- Connector transport: `plugins/connector/port.cpp`, `plugins/connector/comport.cpp`

TCP endpoints support client/server-style address forms; serial endpoints integrate physical and com0com virtual COM ports. External infrastructure is Windows serial I/O, TCP/IP networking, and optionally the com0com virtual-null-modem driver.

#### Routing and backpressure
`route.cpp` / `route.h` define directed relationships between port indices. The hub can fan input out to multiple destinations, implement bidirectional routes, and propagate relevant control/flow signals. Per-port write queues and connection state form the key boundary between routing intent and endpoint availability; reconnect and queue-limit settings prevent a failed TCP peer from necessarily blocking unrelated routes.

#### Filter pipeline and plugin ABI
`filter.h`, `filters.cpp`, and `filters.h` provide the core filter-chain mechanism. Plugins are discovered/loaded through `plugins.cpp` / `plugins.h`, against the shared interface in `plugins/plugins_api.h` and export definitions in `plugins/plugins.def`. Filters can be attached by port/route configuration and transform bytes or communications signals before forwarding.

Architecturally important supplied filters include Telnet/RFC 2217 handling (`plugins/telnet/telnet.cpp`, `plugins/telnet/opt_comport.cpp`), encryption-oriented transformation (`plugins/crypt/filter.cpp`), multiplexing/tagging (`plugins/tag/filter.cpp`), tracing (`plugins/trace/filter.cpp`), and pin/control-line mapping (`plugins/pinmap/filter.cpp`, `plugins/pin2con/filter.cpp`).

#### Deployment compositions
The executable is intentionally topology-driven rather than application-server-driven. Batch wrappers compose reusable configurations for common deployments: COM-to-TCP/Telnet in `examples/com2tcp.bat`, RFC 2217 in `examples/com2tcp-rfc2217.bat`, and encrypted or serial-link multiplexing in `examples/multiplexer.bat`. A static-build variant exists in `static/hub4com-static.vcproj`.

Main entry points: [`plugins.cpp`](https://github.com/tanvir-ahmed-m4/hub4com/blob/master/plugins.cpp) (Plugin loader), [`filter.h`](https://github.com/tanvir-ahmed-m4/hub4com/blob/master/filter.h) (Filter chain), [`port.h`](https://github.com/tanvir-ahmed-m4/hub4com/blob/master/port.h) (Abstract port contract), [`comhub.cpp`](https://github.com/tanvir-ahmed-m4/hub4com/blob/master/comhub.cpp) (Hub coordinator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["Startup & Control"]
  node_cli["CLI topology builder<br/>native entry point<br/>[hub4com.cpp]"]
  node_messages["Command/status messaging<br/>[hubmsg.cpp]"]
end

subgraph group_core["Hub Data Plane"]
  node_hub{{"Hub coordinator<br/>orchestrator<br/>[comhub.cpp]"}}
  node_timer["Reconnect timers<br/>control plane<br/>[timer.cpp]"]
  node_routes["Directed routes<br/>routing model<br/>[route.cpp]"]
  node_port_contract["Abstract port contract<br/>port API<br/>[port.h]"]
  node_write_queues["Write queues &amp; state<br/>backpressure boundary<br/>[port.cpp]"]
  node_filter_chain["Filter chain<br/>stream pipeline<br/>[filter.h]"]
end

subgraph group_plugins["Plugin Ecosystem"]
  node_plugin_loader["Plugin loader<br/>dynamic loader<br/>[plugins.cpp]"]
  node_plugin_abi["Plugin ABI<br/>shared interface<br/>[plugins_api.h]"]
  node_telnet["Telnet / RFC 2217<br/>filter plugin<br/>[telnet.cpp]"]
  node_transforms["Crypt, tag &amp; trace filters<br/>filter plugins<br/>[filter.cpp]"]
  node_pin_filters["Pin mapping filters<br/>filter plugins<br/>[filter.cpp]"]
end

subgraph group_endpoints["Endpoint Drivers"]
  node_serial_driver["Serial endpoint plugin<br/>port driver<br/>[port.cpp]"]
  node_tcp_driver["TCP endpoint plugin<br/>port driver<br/>[port.cpp]"]
  node_connector_driver["Connector endpoint plugin<br/>port driver<br/>[port.cpp]"]
  node_windows_io[("Windows serial I/O<br/>external infrastructure")]
  node_tcp_network(("TCP/IP networking<br/>external infrastructure"))
end

subgraph group_deploy["Deployment"]
  node_batch_compositions["Topology batch wrappers<br/>deployment composition<br/>[com2tcp.bat]"]
  node_static_build["Static build variant<br/>build composition"]
end

node_cli -->|"builds topology"| node_hub
node_cli -->|"reports through"| node_messages
node_hub -->|"schedules reconnects"| node_timer
node_hub -->|"dispatches events to"| node_routes
node_routes -->|"forwards to"| node_write_queues
node_write_queues -->|"writes via"| node_port_contract
node_routes -->|"applies attached filters"| node_filter_chain
node_filter_chain -->|"emits transformed traffic"| node_write_queues
node_hub -->|"manages ports"| node_port_contract
node_plugin_loader -->|"loads against"| node_plugin_abi
node_plugin_loader -->|"loads"| node_serial_driver
node_plugin_loader -->|"loads"| node_tcp_driver
node_plugin_loader -->|"loads"| node_connector_driver
node_plugin_loader -->|"loads"| node_telnet
node_plugin_loader -->|"loads"| node_transforms
node_plugin_loader -->|"loads"| node_pin_filters
node_serial_driver -->|"implements"| node_port_contract
node_tcp_driver -->|"implements"| node_port_contract
node_connector_driver -->|"implements"| node_port_contract
node_telnet -->|"extends"| node_filter_chain
node_transforms -->|"extends"| node_filter_chain
node_pin_filters -->|"extends"| node_filter_chain
node_serial_driver -->|"uses"| node_windows_io
node_tcp_driver -->|"uses"| node_tcp_network
node_batch_compositions -->|"invokes"| node_cli
node_static_build -.->|"builds"| node_cli

click node_cli "https://github.com/tanvir-ahmed-m4/hub4com/blob/master/hub4com.cpp"
click node_messages "https://github.com/tanvir-ahmed-m4/hub4com/blob/master/hubmsg.cpp"
click node_hub "https://github.com/tanvir-ahmed-m4/hub4com/blob/master/comhub.cpp"
click node_timer "https://github.com/tanvir-ahmed-m4/hub4com/blob/master/timer.cpp"
click node_routes "https://github.com/tanvir-ahmed-m4/hub4com/blob/master/route.cpp"
click node_port_contract "https://github.com/tanvir-ahmed-m4/hub4com/blob/master/port.h"
click node_write_queues "https://github.com/tanvir-ahmed-m4/hub4com/blob/master/port.cpp"
click node_filter_chain "https://github.com/tanvir-ahmed-m4/hub4com/blob/master/filter.h"
click node_plugin_loader "https://github.com/tanvir-ahmed-m4/hub4com/blob/master/plugins.cpp"
click node_plugin_abi "https://github.com/tanvir-ahmed-m4/hub4com/blob/master/plugins/plugins_api.h"
click node_telnet "https://github.com/tanvir-ahmed-m4/hub4com/blob/master/plugins/telnet/telnet.cpp"
click node_transforms "https://github.com/tanvir-ahmed-m4/hub4com/blob/master/plugins/crypt/filter.cpp"
click node_pin_filters "https://github.com/tanvir-ahmed-m4/hub4com/blob/master/plugins/pinmap/filter.cpp"
click node_serial_driver "https://github.com/tanvir-ahmed-m4/hub4com/blob/master/plugins/serial/port.cpp"
click node_tcp_driver "https://github.com/tanvir-ahmed-m4/hub4com/blob/master/plugins/tcp/port.cpp"
click node_connector_driver "https://github.com/tanvir-ahmed-m4/hub4com/blob/master/plugins/connector/port.cpp"
click node_batch_compositions "https://github.com/tanvir-ahmed-m4/hub4com/blob/master/examples/com2tcp.bat"
click node_static_build "https://github.com/tanvir-ahmed-m4/hub4com/blob/master/static/hub4com-static.vcproj"

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_cli,node_messages toneBlue
class node_hub,node_timer,node_routes,node_port_contract,node_write_queues,node_filter_chain toneAmber
class node_plugin_loader,node_plugin_abi,node_telnet,node_transforms,node_pin_filters toneMint
class node_serial_driver,node_tcp_driver,node_connector_driver,node_windows_io,node_tcp_network toneRose
class node_batch_compositions,node_static_build toneIndigo
```

## Components

### Startup & Control

- [CLI topology builder](https://github.com/tanvir-ahmed-m4/hub4com/blob/master/hub4com.cpp): native entry point · Parses ordered options, endpoint declarations, and loaded configurations. · `hub4com.cpp`
- [Command/status messaging](https://github.com/tanvir-ahmed-m4/hub4com/blob/master/hubmsg.cpp): messaging · `hubmsg.cpp`

### Hub Data Plane

- [Hub coordinator](https://github.com/tanvir-ahmed-m4/hub4com/blob/master/comhub.cpp): orchestrator · Owns opened ports, lifecycle sequencing, and port-event dispatch. · `comhub.cpp`
- [Reconnect timers](https://github.com/tanvir-ahmed-m4/hub4com/blob/master/timer.cpp): control plane · `timer.cpp`
- [Directed routes](https://github.com/tanvir-ahmed-m4/hub4com/blob/master/route.cpp): routing model · Supports fan-out, bidirectional forwarding, and control-signal propagation. · `route.cpp`
- [Abstract port contract](https://github.com/tanvir-ahmed-m4/hub4com/blob/master/port.h): port API · `port.h`
- [Write queues & state](https://github.com/tanvir-ahmed-m4/hub4com/blob/master/port.cpp): backpressure boundary · Queues and connection state isolate routes from unavailable peers. · `port.cpp`
- [Filter chain](https://github.com/tanvir-ahmed-m4/hub4com/blob/master/filter.h): stream pipeline · Transforms bytes and communications signals before forwarding. · `filter.h`

### Plugin Ecosystem

- [Plugin loader](https://github.com/tanvir-ahmed-m4/hub4com/blob/master/plugins.cpp): dynamic loader · Discovers and loads endpoint and filter plugins. · `plugins.cpp`
- [Plugin ABI](https://github.com/tanvir-ahmed-m4/hub4com/blob/master/plugins/plugins_api.h): shared interface · `plugins/plugins_api.h`
- [Telnet / RFC 2217](https://github.com/tanvir-ahmed-m4/hub4com/blob/master/plugins/telnet/telnet.cpp): filter plugin · `plugins/telnet/telnet.cpp`
- [Crypt, tag & trace filters](https://github.com/tanvir-ahmed-m4/hub4com/blob/master/plugins/crypt/filter.cpp): filter plugins · Supplied encryption, multiplexing/tagging, and tracing transforms. · `plugins/crypt/filter.cpp`
- [Pin mapping filters](https://github.com/tanvir-ahmed-m4/hub4com/blob/master/plugins/pinmap/filter.cpp): filter plugins · `plugins/pinmap/filter.cpp`

### Endpoint Drivers

- [Serial endpoint plugin](https://github.com/tanvir-ahmed-m4/hub4com/blob/master/plugins/serial/port.cpp): port driver · Connects physical and com0com virtual COM ports. · `plugins/serial/port.cpp`
- [TCP endpoint plugin](https://github.com/tanvir-ahmed-m4/hub4com/blob/master/plugins/tcp/port.cpp): port driver · Provides client/server-style TCP address endpoints. · `plugins/tcp/port.cpp`
- [Connector endpoint plugin](https://github.com/tanvir-ahmed-m4/hub4com/blob/master/plugins/connector/port.cpp): port driver · `plugins/connector/port.cpp`
- **Windows serial I/O**: external infrastructure
- **TCP/IP networking**: external infrastructure

### Deployment

- [Topology batch wrappers](https://github.com/tanvir-ahmed-m4/hub4com/blob/master/examples/com2tcp.bat): deployment composition · Reusable COM-to-TCP, RFC 2217, encryption, and multiplexing configurations. · `examples/com2tcp.bat`
- [Static build variant](https://github.com/tanvir-ahmed-m4/hub4com/blob/master/static/hub4com-static.vcproj): build composition · `static/hub4com-static.vcproj`

## Connections

- CLI topology builder → Hub coordinator: builds topology
- CLI topology builder → Command/status messaging: reports through
- Hub coordinator → Reconnect timers: schedules reconnects
- Hub coordinator → Directed routes: dispatches events to
- Directed routes → Write queues & state: forwards to
- Write queues & state → Abstract port contract: writes via
- Directed routes → Filter chain: applies attached filters
- Filter chain → Write queues & state: emits transformed traffic
- Hub coordinator → Abstract port contract: manages ports
- Plugin loader → Plugin ABI: loads against
- Plugin loader → Serial endpoint plugin: loads
- Plugin loader → TCP endpoint plugin: loads
- Plugin loader → Connector endpoint plugin: loads
- Plugin loader → Telnet / RFC 2217: loads
- Plugin loader → Crypt, tag & trace filters: loads
- Plugin loader → Pin mapping filters: loads
- Serial endpoint plugin → Abstract port contract: implements
- TCP endpoint plugin → Abstract port contract: implements
- Connector endpoint plugin → Abstract port contract: implements
- Telnet / RFC 2217 → Filter chain: extends
- Crypt, tag & trace filters → Filter chain: extends
- Pin mapping filters → Filter chain: extends
- Serial endpoint plugin → Windows serial I/O: uses
- TCP endpoint plugin → TCP/IP networking: uses
- Topology batch wrappers → CLI topology builder: invokes
- Static build variant → CLI topology builder: builds