# hamanpaul/serialwrap architecture

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

- Interactive diagram: https://gitdiagram.com/hamanpaul/serialwrap
- Repository: https://github.com/hamanpaul/serialwrap

## Overview

serialwrap is a UART broker: CLI and human-console clients submit work to a daemon, which coordinates session state and serialized writes to real devices while capturing raw evidence. The graph also preserves documented event-rule, file-transfer, flashing, and device-discovery capabilities. Relationships come from the README and SOURCE INDEX; unsampled subsystems are shown only where documented or explicitly referenced, so some internal links are omitted.

Main entry points: [`sw_core/service.py`](https://github.com/hamanpaul/serialwrap/blob/main/sw_core/service.py) (Service dispatcher), [`sw_core/uart_io.py`](https://github.com/hamanpaul/serialwrap/blob/main/sw_core/uart_io.py) (UART bridge), [`sw_core/session_manager.py`](https://github.com/hamanpaul/serialwrap/blob/main/sw_core/session_manager.py) (Session manager), [`sw_core/event_engine/engine.py`](https://github.com/hamanpaul/serialwrap/blob/main/sw_core/event_engine/engine.py) (Event engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Clients and daemon"]
  node_cli["CLI client<br/>[cli.py]"]
  node_daemon["Broker daemon<br/>[daemon.py]"]
  node_service["Service dispatcher<br/>[service.py]"]
end

subgraph group_sessions["Session and transport"]
  node_config["Profiles and config<br/>[config.py]"]
  node_sessions_mgr["Session manager<br/>[session_manager.py]"]
  node_arbiter["Command arbiter<br/>[arbiter.py]"]
  node_uart["UART bridge<br/>[uart_io.py]"]
end

subgraph group_evidence["Evidence and events"]
  node_wal[("Raw WAL and mirror<br/>[wal.py]")]
  node_event_engine["Event engine<br/>[engine.py]"]
  node_matcher["Rule matcher<br/>[matcher.py]"]
  node_dispatcher["Event dispatcher<br/>[dispatcher.py]"]
end

subgraph group_integrations["Device integrations"]
  node_file_transfer["File transfer<br/>[file_transfer.py]"]
  node_flash["Flash endpoint<br/>[flash_endpoint.py]"]
  node_watcher["Device watcher<br/>[device_watcher.py]"]
  node_device_source["Device discovery<br/>[device_source.py]"]
end

node_agents(("Agents and CLI users"))
node_console(("Human console"))
node_target(("Real UART device"))
node_external_flasher(("External flasher"))

node_agents -->|"issue commands"| node_cli
node_console -->|"use broker"| node_cli
node_cli -->|"RPC requests"| node_daemon
node_daemon -->|"dispatches"| node_service
node_service -->|"coordinates sessions"| node_sessions_mgr
node_service -->|"submits work"| node_arbiter
node_service -->|"feeds RX lines"| node_event_engine
node_service -->|"writes capture"| node_wal
node_service -->|"routes transfer"| node_file_transfer
node_service -->|"routes flashing"| node_flash
node_sessions_mgr -->|"loads profiles"| node_config
node_sessions_mgr -->|"manages bridge"| node_uart
node_arbiter -->|"serializes writes"| node_uart
node_uart -->|"reads and writes"| node_target
node_uart -->|"captures raw bytes"| node_wal
node_uart -->|"fans out RX"| node_console
node_event_engine -->|"matches lines"| node_matcher
node_event_engine -->|"dispatches events"| node_dispatcher
node_watcher -->|"discovers devices"| node_device_source
node_service -->|"coordinates discovery"| node_watcher
node_flash -->|"bridges flashing"| node_external_flasher

click node_cli "https://github.com/hamanpaul/serialwrap/blob/main/sw_core/cli.py"
click node_daemon "https://github.com/hamanpaul/serialwrap/blob/main/sw_core/daemon.py"
click node_service "https://github.com/hamanpaul/serialwrap/blob/main/sw_core/service.py"
click node_config "https://github.com/hamanpaul/serialwrap/blob/main/sw_core/config.py"
click node_sessions_mgr "https://github.com/hamanpaul/serialwrap/blob/main/sw_core/session_manager.py"
click node_arbiter "https://github.com/hamanpaul/serialwrap/blob/main/sw_core/arbiter.py"
click node_uart "https://github.com/hamanpaul/serialwrap/blob/main/sw_core/uart_io.py"
click node_wal "https://github.com/hamanpaul/serialwrap/blob/main/sw_core/wal.py"
click node_event_engine "https://github.com/hamanpaul/serialwrap/blob/main/sw_core/event_engine/engine.py"
click node_matcher "https://github.com/hamanpaul/serialwrap/blob/main/sw_core/event_engine/matcher.py"
click node_dispatcher "https://github.com/hamanpaul/serialwrap/blob/main/sw_core/event_engine/dispatcher.py"
click node_file_transfer "https://github.com/hamanpaul/serialwrap/blob/main/sw_core/file_transfer.py"
click node_flash "https://github.com/hamanpaul/serialwrap/blob/main/sw_core/flash_endpoint.py"
click node_watcher "https://github.com/hamanpaul/serialwrap/blob/main/sw_core/device_watcher.py"
click node_device_source "https://github.com/hamanpaul/serialwrap/blob/main/sw_core/device_source.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_cli,node_daemon,node_service,node_agents toneBlue
class node_config,node_sessions_mgr,node_arbiter,node_uart toneAmber
class node_wal,node_event_engine,node_matcher,node_dispatcher toneMint
class node_file_transfer,node_flash,node_watcher,node_device_source toneRose
class node_console,node_target,node_external_flasher toneIndigo
```

## Components

### Clients and daemon

- [CLI client](https://github.com/hamanpaul/serialwrap/blob/main/sw_core/cli.py): `sw_core/cli.py`
- [Broker daemon](https://github.com/hamanpaul/serialwrap/blob/main/sw_core/daemon.py): `sw_core/daemon.py`
- [Service dispatcher](https://github.com/hamanpaul/serialwrap/blob/main/sw_core/service.py): `sw_core/service.py`

### Session and transport

- [Profiles and config](https://github.com/hamanpaul/serialwrap/blob/main/sw_core/config.py): `sw_core/config.py`
- [Session manager](https://github.com/hamanpaul/serialwrap/blob/main/sw_core/session_manager.py): `sw_core/session_manager.py`
- [Command arbiter](https://github.com/hamanpaul/serialwrap/blob/main/sw_core/arbiter.py): `sw_core/arbiter.py`
- [UART bridge](https://github.com/hamanpaul/serialwrap/blob/main/sw_core/uart_io.py): `sw_core/uart_io.py`

### Evidence and events

- [Raw WAL and mirror](https://github.com/hamanpaul/serialwrap/blob/main/sw_core/wal.py): `sw_core/wal.py`
- [Event engine](https://github.com/hamanpaul/serialwrap/blob/main/sw_core/event_engine/engine.py): `sw_core/event_engine/engine.py`
- [Rule matcher](https://github.com/hamanpaul/serialwrap/blob/main/sw_core/event_engine/matcher.py): `sw_core/event_engine/matcher.py`
- [Event dispatcher](https://github.com/hamanpaul/serialwrap/blob/main/sw_core/event_engine/dispatcher.py): `sw_core/event_engine/dispatcher.py`

### Device integrations

- [File transfer](https://github.com/hamanpaul/serialwrap/blob/main/sw_core/file_transfer.py): `sw_core/file_transfer.py`
- [Flash endpoint](https://github.com/hamanpaul/serialwrap/blob/main/sw_core/flash_endpoint.py): `sw_core/flash_endpoint.py`
- [Device watcher](https://github.com/hamanpaul/serialwrap/blob/main/sw_core/device_watcher.py): `sw_core/device_watcher.py`
- [Device discovery](https://github.com/hamanpaul/serialwrap/blob/main/sw_core/device_source.py): `sw_core/device_source.py`

### Other components

- **Agents and CLI users**
- **Human console**
- **Real UART device**
- **External flasher**

## Connections

- Agents and CLI users → CLI client: issue commands (evidence: `README.md`)
- Human console → CLI client: use broker (evidence: `README.md`)
- CLI client → Broker daemon: RPC requests (evidence: `README.md`)
- Broker daemon → Service dispatcher: dispatches (evidence: `README.md`)
- Service dispatcher → Session manager: coordinates sessions (evidence: `README.md`)
- Service dispatcher → Command arbiter: submits work (evidence: `README.md`)
- Service dispatcher → Event engine: feeds RX lines (evidence: `sw_core/service.py`)
- Service dispatcher → Raw WAL and mirror: writes capture (evidence: `README.md`)
- Service dispatcher → File transfer: routes transfer (evidence: `sw_core/service.py`)
- Service dispatcher → Flash endpoint: routes flashing (evidence: `sw_core/service.py`)
- Session manager → Profiles and config: loads profiles (evidence: `sw_core/session_manager.py`)
- Session manager → UART bridge: manages bridge (evidence: `sw_core/session_manager.py`)
- Command arbiter → UART bridge: serializes writes (evidence: `README.md`)
- UART bridge → Real UART device: reads and writes (evidence: `README.md`)
- UART bridge → Raw WAL and mirror: captures raw bytes (evidence: `README.md`)
- UART bridge → Human console: fans out RX (evidence: `README.md`)
- Event engine → Rule matcher: matches lines (evidence: `sw_core/event_engine/engine.py`)
- Event engine → Event dispatcher: dispatches events (evidence: `sw_core/event_engine/engine.py`)
- Device watcher → Device discovery: discovers devices (evidence: `sw_core/device_watcher.py`)
- Service dispatcher → Device watcher: coordinates discovery (evidence: `sw_core/service.py`)
- Flash endpoint → External flasher: bridges flashing (evidence: `README.md`)
