# yiaobang/kserial architecture

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

- Interactive diagram: https://gitdiagram.com/yiaobang/kserial
- Repository: https://github.com/yiaobang/kserial

## Overview

KSerial is a desktop serial-workbench with three user workflows: connect and inspect a serial device, simulate a configured device response, or route data between serial ports. The graph follows the documented workspace and capabilities; some subsystem wiring is inferred only where the README explicitly describes behavior, since several implementation files were not sampled.

Main entry points: [`composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/SerialViewModel.kt`](https://github.com/yiaobang/kserial/blob/master/composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/SerialViewModel.kt) (Terminal session), [`composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/feature/GatewayViewModel.kt`](https://github.com/yiaobang/kserial/blob/master/composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/feature/GatewayViewModel.kt) (Gateway session), [`composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/App.kt`](https://github.com/yiaobang/kserial/blob/master/composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/App.kt) (Workspace screens), [`composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/serial/SerialComm.kt`](https://github.com/yiaobang/kserial/blob/master/composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/serial/SerialComm.kt) (Serial transport)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Workspace UI"]
  node_app["Desktop app<br/>[main.kt]"]
  node_workspace_state["Workspace state<br/>[WorkspaceState.kt]"]
  node_tab_content["Workspace tabs"]
  node_app_ui["Workspace screens<br/>[App.kt]"]
end

subgraph group_terminal["Serial terminal"]
  node_terminal_vm["Terminal session<br/>[SerialViewModel.kt]"]
  node_serial_config["Port settings"]
  node_serial["Serial transport<br/>[SerialComm.kt]"]
  node_port_monitor["Port discovery<br/>[PortMonitor.kt]"]
end

subgraph group_simulation["Device simulation"]
  node_sim_vm["Simulator session<br/>[App.kt]"]
  node_simulator["Response rules<br/>[DeviceSimulator.kt]"]
end

subgraph group_gateway["Serial gateway"]
  node_gateway_vm["Gateway session"]
end

subgraph group_shared["Shared services"]
  node_config_validation["Config validation"]
  node_frame_parser["Frame parsing<br/>[FrameParser.kt]"]
  node_checksum["Checksums<br/>[ChecksumUtils.kt]"]
  node_log_export["Log export<br/>[LogExporter.kt]"]
  node_settings[("Settings store")]
end

node_user(("Operator"))
node_hardware(("Serial device"))
node_config_files["HOCON configs"]

node_user -->|"uses"| node_app
node_app -->|"creates"| node_workspace_state
node_workspace_state -->|"manages"| node_tab_content
node_app -->|"renders"| node_app_ui
node_app_ui -->|"controls"| node_terminal_vm
node_app_ui -->|"controls"| node_sim_vm
node_app_ui -->|"controls"| node_gateway_vm
node_terminal_vm -->|"opens and transfers"| node_serial
node_serial -->|"reads and writes"| node_hardware
node_port_monitor -->|"reports ports"| node_terminal_vm
node_terminal_vm -->|"uses settings"| node_serial_config
node_sim_vm -->|"validates config"| node_config_validation
node_sim_vm -->|"matches requests"| node_simulator
node_sim_vm -->|"communicates over"| node_serial
node_config_files -->|"loads rules"| node_sim_vm
node_gateway_vm -->|"validates config"| node_config_validation
node_gateway_vm -->|"opens endpoints"| node_serial
node_gateway_vm -->|"routes received bytes"| node_gateway_vm
node_config_files -->|"loads routes"| node_gateway_vm
node_terminal_vm -.->|"frames received data"| node_frame_parser
node_terminal_vm -.->|"calculates checksums"| node_checksum
node_app_ui -->|"exports logs"| node_log_export
node_workspace_state -->|"loads and saves"| node_settings

click node_app "https://github.com/yiaobang/kserial/blob/master/composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/main.kt"
click node_workspace_state "https://github.com/yiaobang/kserial/blob/master/composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/workspace/WorkspaceState.kt"
click node_tab_content "https://github.com/yiaobang/kserial/blob/master/composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/workspace/WorkspaceTabContent.kt"
click node_app_ui "https://github.com/yiaobang/kserial/blob/master/composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/App.kt"
click node_terminal_vm "https://github.com/yiaobang/kserial/blob/master/composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/SerialViewModel.kt"
click node_serial_config "https://github.com/yiaobang/kserial/blob/master/composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/model/SerialPortConfig.kt"
click node_serial "https://github.com/yiaobang/kserial/blob/master/composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/serial/SerialComm.kt"
click node_port_monitor "https://github.com/yiaobang/kserial/blob/master/composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/serial/PortMonitor.kt"
click node_sim_vm "https://github.com/yiaobang/kserial/blob/master/composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/App.kt"
click node_simulator "https://github.com/yiaobang/kserial/blob/master/composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/model/DeviceSimulator.kt"
click node_config_validation "https://github.com/yiaobang/kserial/blob/master/composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/model/ConfigValidation.kt"
click node_gateway_vm "https://github.com/yiaobang/kserial/blob/master/composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/feature/GatewayViewModel.kt"
click node_frame_parser "https://github.com/yiaobang/kserial/blob/master/composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/utils/FrameParser.kt"
click node_checksum "https://github.com/yiaobang/kserial/blob/master/composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/utils/ChecksumUtils.kt"
click node_log_export "https://github.com/yiaobang/kserial/blob/master/composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/utils/LogExporter.kt"
click node_settings "https://github.com/yiaobang/kserial/blob/master/composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/model/AppSettingsStore.kt"

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_app,node_workspace_state,node_tab_content,node_app_ui toneBlue
class node_terminal_vm,node_serial_config,node_serial,node_port_monitor toneAmber
class node_sim_vm,node_simulator toneMint
class node_gateway_vm toneRose
class node_config_validation,node_frame_parser,node_checksum,node_log_export,node_settings,node_user,node_hardware,node_config_files toneIndigo
```

## Components

### Workspace UI

- [Desktop app](https://github.com/yiaobang/kserial/blob/master/composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/main.kt): `composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/main.kt`
- [Workspace state](https://github.com/yiaobang/kserial/blob/master/composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/workspace/WorkspaceState.kt): `composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/workspace/WorkspaceState.kt`
- [Workspace tabs](https://github.com/yiaobang/kserial/blob/master/composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/workspace/WorkspaceTabContent.kt): `composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/workspace/WorkspaceTabContent.kt`
- [Workspace screens](https://github.com/yiaobang/kserial/blob/master/composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/App.kt): `composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/App.kt`

### Serial terminal

- [Terminal session](https://github.com/yiaobang/kserial/blob/master/composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/SerialViewModel.kt): `composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/SerialViewModel.kt`
- [Port settings](https://github.com/yiaobang/kserial/blob/master/composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/model/SerialPortConfig.kt): `composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/model/SerialPortConfig.kt`
- [Serial transport](https://github.com/yiaobang/kserial/blob/master/composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/serial/SerialComm.kt): `composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/serial/SerialComm.kt`
- [Port discovery](https://github.com/yiaobang/kserial/blob/master/composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/serial/PortMonitor.kt): `composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/serial/PortMonitor.kt`

### Device simulation

- [Simulator session](https://github.com/yiaobang/kserial/blob/master/composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/App.kt): `composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/App.kt`
- [Response rules](https://github.com/yiaobang/kserial/blob/master/composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/model/DeviceSimulator.kt): `composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/model/DeviceSimulator.kt`

### Serial gateway

- [Gateway session](https://github.com/yiaobang/kserial/blob/master/composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/feature/GatewayViewModel.kt): `composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/feature/GatewayViewModel.kt`

### Shared services

- [Config validation](https://github.com/yiaobang/kserial/blob/master/composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/model/ConfigValidation.kt): `composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/model/ConfigValidation.kt`
- [Frame parsing](https://github.com/yiaobang/kserial/blob/master/composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/utils/FrameParser.kt): `composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/utils/FrameParser.kt`
- [Checksums](https://github.com/yiaobang/kserial/blob/master/composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/utils/ChecksumUtils.kt): `composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/utils/ChecksumUtils.kt`
- [Log export](https://github.com/yiaobang/kserial/blob/master/composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/utils/LogExporter.kt): `composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/utils/LogExporter.kt`
- [Settings store](https://github.com/yiaobang/kserial/blob/master/composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/model/AppSettingsStore.kt): `composeApp/src/jvmMain/kotlin/com/yiaobang/kserial/model/AppSettingsStore.kt`

### Other components

- **Operator**
- **Serial device**
- **HOCON configs**

## Connections

- Operator → Desktop app: uses
- Desktop app → Workspace state: creates
- Workspace state → Workspace tabs: manages
- Desktop app → Workspace screens: renders
- Workspace screens → Terminal session: controls
- Workspace screens → Simulator session: controls
- Workspace screens → Gateway session: controls
- Terminal session → Serial transport: opens and transfers
- Serial transport → Serial device: reads and writes
- Port discovery → Terminal session: reports ports
- Terminal session → Port settings: uses settings
- Simulator session → Config validation: validates config
- Simulator session → Response rules: matches requests
- Simulator session → Serial transport: communicates over
- HOCON configs → Simulator session: loads rules
- Gateway session → Config validation: validates config
- Gateway session → Serial transport: opens endpoints
- Gateway session → Gateway session: routes received bytes
- HOCON configs → Gateway session: loads routes
- Terminal session → Frame parsing: frames received data
- Terminal session → Checksums: calculates checksums
- Workspace screens → Log export: exports logs
- Workspace state → Settings store: loads and saves