# lepat/webapp-hardware-bridge architecture

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

- Interactive diagram: https://gitdiagram.com/lepat/webapp-hardware-bridge
- Repository: https://github.com/lepat/webapp-hardware-bridge

## Overview

WebApp Hardware Bridge is a localhost Java service that lets browser applications print silently and communicate with serial hardware. The principal flow is WebApp WebSocket request → channel routing → printer job preparation/dispatch or serial-port proxying → response or streamed data. Configuration via the Web UI and HTTP API, printer/serial discovery, notifications, and optional TLS are additional capabilities. Arrows follow README statements or shown calls; unsampled HTTP and UI internals are not expanded.

Main entry points: [`src/main/java/tigerworkshop/webapphardwarebridge/websocketservices/PrinterWebSocketService.java`](https://github.com/lepat/webapp-hardware-bridge/blob/master/src/main/java/tigerworkshop/webapphardwarebridge/websocketservices/PrinterWebSocketService.java) (Printer WebSocket handler), [`src/main/java/tigerworkshop/webapphardwarebridge/Server.java`](https://github.com/lepat/webapp-hardware-bridge/blob/master/src/main/java/tigerworkshop/webapphardwarebridge/Server.java) (Local server and router), [`src/main/java/tigerworkshop/webapphardwarebridge/websocketservices/SerialWebSocketService.java`](https://github.com/lepat/webapp-hardware-bridge/blob/master/src/main/java/tigerworkshop/webapphardwarebridge/websocketservices/SerialWebSocketService.java) (Serial WebSocket proxy), [`src/main/java/tigerworkshop/webapphardwarebridge/services/ConfigService.java`](https://github.com/lepat/webapp-hardware-bridge/blob/master/src/main/java/tigerworkshop/webapphardwarebridge/services/ConfigService.java) (Config persistence)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Server and configuration"]
  node_server["Local server and router<br/>[Server.java]"]
  node_config["Configuration model<br/>[Config.java]"]
  node_configservice["Config persistence<br/>[ConfigService.java]"]
  node_httpconfig["HTTP config and discovery API<br/>[Server.java]"]
end

subgraph group_printing["Print pipeline"]
  node_printerws["Printer WebSocket handler"]
  node_printdoc["Print request model<br/>[PrintDocument.java]"]
  node_document["Document download and decode"]
  node_printer["Mapped printer dispatch"]
  node_printables["Image and annotation rendering"]
  node_annotated["Annotation rendering"]
  node_escpos["ESC/POS printer utility<br/>[EscPOSPrinter.java]"]
  node_printresult["Print result<br/>[PrintResult.java]"]
end

subgraph group_serial["Serial access"]
  node_serialws["Serial WebSocket proxy"]
  node_serialports["Serial port hardware"]
end

subgraph group_support["UI and shared contracts"]
  node_wscontracts["WebSocket service contracts"]
  node_servercontract["Server routing contract"]
  node_notification["Notification message model"]
  node_gui["System tray and Web UI launcher<br/>[GUI.java]"]
  node_cert["TLS certificate generation"]
  node_threadutil["Thread timing utility<br/>[ThreadUtil.java]"]
end

node_webapp(("WebApp"))

node_webapp -->|"connects by WebSocket"| node_server
node_webapp -->|"configures and discovers"| node_httpconfig
node_server -->|"routes print channel"| node_printerws
node_server -->|"registers serial channel"| node_serialws
node_server -->|"loads and saves"| node_configservice
node_configservice -->|"deserializes and persists"| node_config
node_server -->|"serves endpoints"| node_httpconfig
node_server -->|"dispatches service calls"| node_wscontracts
node_printerws -->|"sends results and notices"| node_servercontract
node_serialws -->|"streams serial data"| node_servercontract
node_servercontract -->|"registers services"| node_wscontracts
node_printerws -->|"parses print request"| node_printdoc
node_printerws -->|"prepares documents"| node_document
node_printerws -->|"dispatches print job"| node_printer
node_printerws -->|"returns job status"| node_printresult
node_printerws -->|"adds annotations"| node_annotated
node_annotated -->|"wraps printable"| node_printables
node_printerws -.->|"uses raw printing utility"| node_escpos
node_serialws -->|"reads and writes"| node_serialports
node_serialws -->|"pauses worker loops"| node_threadutil
node_printerws -->|"reads printer mappings"| node_configservice
node_serialws -->|"builds port notices"| node_notification
node_printerws -->|"builds print notices"| node_notification
node_gui -->|"starts and restarts"| node_server
node_gui -->|"parses notifications"| node_notification
node_server -->|"uses for TLS setup"| node_cert

click node_server "https://github.com/lepat/webapp-hardware-bridge/blob/master/src/main/java/tigerworkshop/webapphardwarebridge/Server.java"
click node_config "https://github.com/lepat/webapp-hardware-bridge/blob/master/src/main/java/tigerworkshop/webapphardwarebridge/dtos/Config.java"
click node_configservice "https://github.com/lepat/webapp-hardware-bridge/blob/master/src/main/java/tigerworkshop/webapphardwarebridge/services/ConfigService.java"
click node_httpconfig "https://github.com/lepat/webapp-hardware-bridge/blob/master/src/main/java/tigerworkshop/webapphardwarebridge/Server.java"
click node_printerws "https://github.com/lepat/webapp-hardware-bridge/blob/master/src/main/java/tigerworkshop/webapphardwarebridge/websocketservices/PrinterWebSocketService.java"
click node_printdoc "https://github.com/lepat/webapp-hardware-bridge/blob/master/src/main/java/tigerworkshop/webapphardwarebridge/responses/PrintDocument.java"
click node_document "https://github.com/lepat/webapp-hardware-bridge/blob/master/src/main/java/tigerworkshop/webapphardwarebridge/services/DocumentService.java"
click node_printer "https://github.com/lepat/webapp-hardware-bridge/blob/master/src/main/java/tigerworkshop/webapphardwarebridge/websocketservices/PrinterWebSocketService.java"
click node_printables "https://github.com/lepat/webapp-hardware-bridge/blob/master/src/main/java/tigerworkshop/webapphardwarebridge/utils/ImagePrintable.java"
click node_annotated "https://github.com/lepat/webapp-hardware-bridge/blob/master/src/main/java/tigerworkshop/webapphardwarebridge/utils/AnnotatedPrintable.java"
click node_escpos "https://github.com/lepat/webapp-hardware-bridge/blob/master/src/main/java/tigerworkshop/webapphardwarebridge/utils/EscPOSPrinter.java"
click node_printresult "https://github.com/lepat/webapp-hardware-bridge/blob/master/src/main/java/tigerworkshop/webapphardwarebridge/responses/PrintResult.java"
click node_serialws "https://github.com/lepat/webapp-hardware-bridge/blob/master/src/main/java/tigerworkshop/webapphardwarebridge/websocketservices/SerialWebSocketService.java"
click node_wscontracts "https://github.com/lepat/webapp-hardware-bridge/blob/master/src/main/java/tigerworkshop/webapphardwarebridge/interfaces/WebSocketServiceInterface.java"
click node_servercontract "https://github.com/lepat/webapp-hardware-bridge/blob/master/src/main/java/tigerworkshop/webapphardwarebridge/interfaces/WebSocketServerInterface.java"
click node_notification "https://github.com/lepat/webapp-hardware-bridge/blob/master/src/main/java/tigerworkshop/webapphardwarebridge/dtos/NotificationDTO.java"
click node_gui "https://github.com/lepat/webapp-hardware-bridge/blob/master/src/main/java/tigerworkshop/webapphardwarebridge/GUI.java"
click node_cert "https://github.com/lepat/webapp-hardware-bridge/blob/master/src/main/java/tigerworkshop/webapphardwarebridge/utils/CertificateGenerator.java"
click node_threadutil "https://github.com/lepat/webapp-hardware-bridge/blob/master/src/main/java/tigerworkshop/webapphardwarebridge/utils/ThreadUtil.java"

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_server,node_config,node_configservice,node_httpconfig toneBlue
class node_printerws,node_printdoc,node_document,node_printer,node_printables,node_annotated,node_escpos,node_printresult toneAmber
class node_serialws,node_serialports toneMint
class node_wscontracts,node_servercontract,node_notification,node_gui,node_cert,node_threadutil toneRose
class node_webapp toneIndigo
```

## Components

### Server and configuration

- [Local server and router](https://github.com/lepat/webapp-hardware-bridge/blob/master/src/main/java/tigerworkshop/webapphardwarebridge/Server.java): `src/main/java/tigerworkshop/webapphardwarebridge/Server.java`
- [Configuration model](https://github.com/lepat/webapp-hardware-bridge/blob/master/src/main/java/tigerworkshop/webapphardwarebridge/dtos/Config.java): `src/main/java/tigerworkshop/webapphardwarebridge/dtos/Config.java`
- [Config persistence](https://github.com/lepat/webapp-hardware-bridge/blob/master/src/main/java/tigerworkshop/webapphardwarebridge/services/ConfigService.java): `src/main/java/tigerworkshop/webapphardwarebridge/services/ConfigService.java`
- [HTTP config and discovery API](https://github.com/lepat/webapp-hardware-bridge/blob/master/src/main/java/tigerworkshop/webapphardwarebridge/Server.java): `src/main/java/tigerworkshop/webapphardwarebridge/Server.java`

### Print pipeline

- [Printer WebSocket handler](https://github.com/lepat/webapp-hardware-bridge/blob/master/src/main/java/tigerworkshop/webapphardwarebridge/websocketservices/PrinterWebSocketService.java): `src/main/java/tigerworkshop/webapphardwarebridge/websocketservices/PrinterWebSocketService.java`
- [Print request model](https://github.com/lepat/webapp-hardware-bridge/blob/master/src/main/java/tigerworkshop/webapphardwarebridge/responses/PrintDocument.java): `src/main/java/tigerworkshop/webapphardwarebridge/responses/PrintDocument.java`
- [Document download and decode](https://github.com/lepat/webapp-hardware-bridge/blob/master/src/main/java/tigerworkshop/webapphardwarebridge/services/DocumentService.java): `src/main/java/tigerworkshop/webapphardwarebridge/services/DocumentService.java`
- [Mapped printer dispatch](https://github.com/lepat/webapp-hardware-bridge/blob/master/src/main/java/tigerworkshop/webapphardwarebridge/websocketservices/PrinterWebSocketService.java): `src/main/java/tigerworkshop/webapphardwarebridge/websocketservices/PrinterWebSocketService.java`
- [Image and annotation rendering](https://github.com/lepat/webapp-hardware-bridge/blob/master/src/main/java/tigerworkshop/webapphardwarebridge/utils/ImagePrintable.java): `src/main/java/tigerworkshop/webapphardwarebridge/utils/ImagePrintable.java`
- [Annotation rendering](https://github.com/lepat/webapp-hardware-bridge/blob/master/src/main/java/tigerworkshop/webapphardwarebridge/utils/AnnotatedPrintable.java): `src/main/java/tigerworkshop/webapphardwarebridge/utils/AnnotatedPrintable.java`
- [ESC/POS printer utility](https://github.com/lepat/webapp-hardware-bridge/blob/master/src/main/java/tigerworkshop/webapphardwarebridge/utils/EscPOSPrinter.java): `src/main/java/tigerworkshop/webapphardwarebridge/utils/EscPOSPrinter.java`
- [Print result](https://github.com/lepat/webapp-hardware-bridge/blob/master/src/main/java/tigerworkshop/webapphardwarebridge/responses/PrintResult.java): `src/main/java/tigerworkshop/webapphardwarebridge/responses/PrintResult.java`

### Serial access

- [Serial WebSocket proxy](https://github.com/lepat/webapp-hardware-bridge/blob/master/src/main/java/tigerworkshop/webapphardwarebridge/websocketservices/SerialWebSocketService.java): `src/main/java/tigerworkshop/webapphardwarebridge/websocketservices/SerialWebSocketService.java`
- **Serial port hardware**

### UI and shared contracts

- [WebSocket service contracts](https://github.com/lepat/webapp-hardware-bridge/blob/master/src/main/java/tigerworkshop/webapphardwarebridge/interfaces/WebSocketServiceInterface.java): `src/main/java/tigerworkshop/webapphardwarebridge/interfaces/WebSocketServiceInterface.java`
- [Server routing contract](https://github.com/lepat/webapp-hardware-bridge/blob/master/src/main/java/tigerworkshop/webapphardwarebridge/interfaces/WebSocketServerInterface.java): `src/main/java/tigerworkshop/webapphardwarebridge/interfaces/WebSocketServerInterface.java`
- [Notification message model](https://github.com/lepat/webapp-hardware-bridge/blob/master/src/main/java/tigerworkshop/webapphardwarebridge/dtos/NotificationDTO.java): `src/main/java/tigerworkshop/webapphardwarebridge/dtos/NotificationDTO.java`
- [System tray and Web UI launcher](https://github.com/lepat/webapp-hardware-bridge/blob/master/src/main/java/tigerworkshop/webapphardwarebridge/GUI.java): `src/main/java/tigerworkshop/webapphardwarebridge/GUI.java`
- [TLS certificate generation](https://github.com/lepat/webapp-hardware-bridge/blob/master/src/main/java/tigerworkshop/webapphardwarebridge/utils/CertificateGenerator.java): `src/main/java/tigerworkshop/webapphardwarebridge/utils/CertificateGenerator.java`
- [Thread timing utility](https://github.com/lepat/webapp-hardware-bridge/blob/master/src/main/java/tigerworkshop/webapphardwarebridge/utils/ThreadUtil.java): `src/main/java/tigerworkshop/webapphardwarebridge/utils/ThreadUtil.java`

### Other components

- **WebApp**

## Connections

- WebApp → Local server and router: connects by WebSocket (evidence: `README.md`)
- WebApp → HTTP config and discovery API: configures and discovers (evidence: `README.md`)
- Local server and router → Printer WebSocket handler: routes print channel (evidence: `src/main/java/tigerworkshop/webapphardwarebridge/Server.java`)
- Local server and router → Serial WebSocket proxy: registers serial channel (evidence: `src/main/java/tigerworkshop/webapphardwarebridge/Server.java`)
- Local server and router → Config persistence: loads and saves (evidence: `src/main/java/tigerworkshop/webapphardwarebridge/Server.java`)
- Config persistence → Configuration model: deserializes and persists (evidence: `src/main/java/tigerworkshop/webapphardwarebridge/services/ConfigService.java`)
- Local server and router → HTTP config and discovery API: serves endpoints (evidence: `src/main/java/tigerworkshop/webapphardwarebridge/Server.java`)
- Local server and router → WebSocket service contracts: dispatches service calls (evidence: `src/main/java/tigerworkshop/webapphardwarebridge/Server.java`)
- Printer WebSocket handler → Server routing contract: sends results and notices (evidence: `src/main/java/tigerworkshop/webapphardwarebridge/websocketservices/PrinterWebSocketService.java`)
- Serial WebSocket proxy → Server routing contract: streams serial data (evidence: `src/main/java/tigerworkshop/webapphardwarebridge/websocketservices/SerialWebSocketService.java`)
- Server routing contract → WebSocket service contracts: registers services (evidence: `src/main/java/tigerworkshop/webapphardwarebridge/interfaces/WebSocketServerInterface.java`)
- Printer WebSocket handler → Print request model: parses print request (evidence: `src/main/java/tigerworkshop/webapphardwarebridge/websocketservices/PrinterWebSocketService.java`)
- Printer WebSocket handler → Document download and decode: prepares documents (evidence: `src/main/java/tigerworkshop/webapphardwarebridge/websocketservices/PrinterWebSocketService.java`)
- Printer WebSocket handler → Mapped printer dispatch: dispatches print job (evidence: `src/main/java/tigerworkshop/webapphardwarebridge/websocketservices/PrinterWebSocketService.java`)
- Printer WebSocket handler → Print result: returns job status (evidence: `src/main/java/tigerworkshop/webapphardwarebridge/websocketservices/PrinterWebSocketService.java`)
- Printer WebSocket handler → Annotation rendering: adds annotations (evidence: `src/main/java/tigerworkshop/webapphardwarebridge/websocketservices/PrinterWebSocketService.java`)
- Annotation rendering → Image and annotation rendering: wraps printable
- Printer WebSocket handler → ESC/POS printer utility: uses raw printing utility
- Serial WebSocket proxy → Serial port hardware: reads and writes (evidence: `src/main/java/tigerworkshop/webapphardwarebridge/websocketservices/SerialWebSocketService.java`)
- Serial WebSocket proxy → Thread timing utility: pauses worker loops (evidence: `src/main/java/tigerworkshop/webapphardwarebridge/websocketservices/SerialWebSocketService.java`)
- Printer WebSocket handler → Config persistence: reads printer mappings (evidence: `src/main/java/tigerworkshop/webapphardwarebridge/websocketservices/PrinterWebSocketService.java`)
- Serial WebSocket proxy → Notification message model: builds port notices (evidence: `src/main/java/tigerworkshop/webapphardwarebridge/websocketservices/SerialWebSocketService.java`)
- Printer WebSocket handler → Notification message model: builds print notices (evidence: `src/main/java/tigerworkshop/webapphardwarebridge/websocketservices/PrinterWebSocketService.java`)
- System tray and Web UI launcher → Local server and router: starts and restarts (evidence: `src/main/java/tigerworkshop/webapphardwarebridge/GUI.java`)
- System tray and Web UI launcher → Notification message model: parses notifications (evidence: `src/main/java/tigerworkshop/webapphardwarebridge/GUI.java`)
- Local server and router → TLS certificate generation: uses for TLS setup (evidence: `src/main/java/tigerworkshop/webapphardwarebridge/Server.java`)
