# polds/tui-streamer architecture

> Architecture diagram of the GitHub repository polds/tui-streamer, 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/polds/tui-streamer
- Repository: https://github.com/polds/tui-streamer
- Video tour (about a minute): https://gitdiagram.com/polds/tui-streamer/video

## Overview

tui-streamer runs commands in named sessions and streams their output to a browser terminal. Users create or import sessions, submit commands, and receive live output over WebSockets; sessions also support control operations and multiple subscribers. YAML Bundles and BundleSets add preconfigured sessions, autorun commands, themes, allowlists, and files. The map includes the command runner and in-memory session state as internal layers. Some capabilities are documented but their implementation was not sampled, so uncertain internal wiring is omitted.

Main entry points: [`internal/server/server.go`](https://github.com/polds/tui-streamer/blob/main/internal/server/server.go) (HTTP / WS API), [`cmd/server/main.go`](https://github.com/polds/tui-streamer/blob/main/cmd/server/main.go) (Server Entry), [`internal/session/session.go`](https://github.com/polds/tui-streamer/blob/main/internal/session/session.go) (Session State), [`internal/server/import.go`](https://github.com/polds/tui-streamer/blob/main/internal/server/import.go) (Bundle Import)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Server Runtime"]
  node_entry["Server Entry<br/>[main.go]"]
  node_http["HTTP / WS API<br/>[server.go]"]
  node_manager[("Session Manager<br/>[manager.go]")]
  node_session["Session State<br/>[session.go]"]
  node_client["WS Client<br/>[client.go]"]
  node_browseropen["Browser Launcher<br/>[open.go]"]
end

subgraph group_execution["Command Execution"]
  node_executor["Command Runner<br/>[executor.go]"]
  node_allow["Command Allowlist<br/>[allow.go]"]
end

subgraph group_bundles["Bundle Configuration"]
  node_bundleload["Bundle Loader<br/>[bundle.go]"]
  node_bundleimport["Bundle Import<br/>[import.go]"]
  node_bundlefiles["Bundle Files<br/>[files.go]"]
end

subgraph group_web["Web Terminal"]
  node_webembed["Embedded UI<br/>[embed.go]"]
  node_app["Terminal UI<br/>[app.js]"]
  node_ansi["ANSI Rendering<br/>[app.js]"]
  node_themes["Themes<br/>[themes.go]"]
end

node_user(("User"))
node_browser(("Browser"))
node_os{{"OS Processes"}}

node_user -->|"uses"| node_browser
node_user -->|"starts server"| node_entry
node_entry -.->|"loads YAML"| node_bundleload
node_entry -->|"creates"| node_manager
node_entry -.->|"imports startup bundle"| node_bundleimport
node_entry -->|"starts listener"| node_http
node_entry -->|"provides static files"| node_webembed
node_entry -.->|"opens UI"| node_browseropen
node_browseropen -.->|"launches"| node_browser
node_browser -->|"HTTP requests"| node_http
node_http -->|"serves UI"| node_webembed
node_http -->|"manages sessions"| node_manager
node_http -->|"executes / controls"| node_session
node_http -->|"parses imports"| node_bundleload
node_http -->|"checks commands"| node_allow
node_bundleimport -->|"creates sessions"| node_manager
node_bundleimport -->|"sets session details"| node_session
node_bundleimport -->|"merges allowlists"| node_allow
node_bundleload -->|"resolves files"| node_bundlefiles
node_session -->|"runs command"| node_executor
node_executor -->|"starts process"| node_os
node_os -->|"writes output"| node_executor
node_executor -->|"streams lines"| node_session
node_session -->|"broadcasts lines"| node_client
node_http -->|"upgrades connection"| node_client
node_browser -->|"opens WebSocket"| node_http
node_client -->|"sends output"| node_browser
node_browser -->|"interacts"| node_app
node_app -->|"calls API"| node_http
node_app -->|"formats output"| node_ansi
node_app -->|"selects theme"| node_themes

click node_entry "https://github.com/polds/tui-streamer/blob/main/cmd/server/main.go"
click node_http "https://github.com/polds/tui-streamer/blob/main/internal/server/server.go"
click node_manager "https://github.com/polds/tui-streamer/blob/main/internal/session/manager.go"
click node_session "https://github.com/polds/tui-streamer/blob/main/internal/session/session.go"
click node_client "https://github.com/polds/tui-streamer/blob/main/internal/session/client.go"
click node_executor "https://github.com/polds/tui-streamer/blob/main/internal/executor/executor.go"
click node_allow "https://github.com/polds/tui-streamer/blob/main/internal/bundle/allow.go"
click node_bundleload "https://github.com/polds/tui-streamer/blob/main/internal/bundle/bundle.go"
click node_bundleimport "https://github.com/polds/tui-streamer/blob/main/internal/server/import.go"
click node_bundlefiles "https://github.com/polds/tui-streamer/blob/main/internal/bundle/files.go"
click node_webembed "https://github.com/polds/tui-streamer/blob/main/web/embed.go"
click node_app "https://github.com/polds/tui-streamer/blob/main/web/static/app.js"
click node_ansi "https://github.com/polds/tui-streamer/blob/main/web/static/app.js"
click node_themes "https://github.com/polds/tui-streamer/blob/main/internal/bundle/themes.go"
click node_browseropen "https://github.com/polds/tui-streamer/blob/main/internal/browser/open.go"

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_entry,node_http,node_manager,node_session,node_client,node_browseropen,node_user,node_browser toneBlue
class node_executor,node_allow toneAmber
class node_bundleload,node_bundleimport,node_bundlefiles toneMint
class node_webembed,node_app,node_ansi,node_themes toneRose
class node_os toneIndigo
```

## Components

### Server Runtime

- [Server Entry](https://github.com/polds/tui-streamer/blob/main/cmd/server/main.go): `cmd/server/main.go`
- [HTTP / WS API](https://github.com/polds/tui-streamer/blob/main/internal/server/server.go): `internal/server/server.go`
- [Session Manager](https://github.com/polds/tui-streamer/blob/main/internal/session/manager.go): `internal/session/manager.go`
- [Session State](https://github.com/polds/tui-streamer/blob/main/internal/session/session.go): `internal/session/session.go`
- [WS Client](https://github.com/polds/tui-streamer/blob/main/internal/session/client.go): `internal/session/client.go`
- [Browser Launcher](https://github.com/polds/tui-streamer/blob/main/internal/browser/open.go): `internal/browser/open.go`

### Command Execution

- [Command Runner](https://github.com/polds/tui-streamer/blob/main/internal/executor/executor.go): `internal/executor/executor.go`
- [Command Allowlist](https://github.com/polds/tui-streamer/blob/main/internal/bundle/allow.go): `internal/bundle/allow.go`

### Bundle Configuration

- [Bundle Loader](https://github.com/polds/tui-streamer/blob/main/internal/bundle/bundle.go): `internal/bundle/bundle.go`
- [Bundle Import](https://github.com/polds/tui-streamer/blob/main/internal/server/import.go): `internal/server/import.go`
- [Bundle Files](https://github.com/polds/tui-streamer/blob/main/internal/bundle/files.go): `internal/bundle/files.go`

### Web Terminal

- [Embedded UI](https://github.com/polds/tui-streamer/blob/main/web/embed.go): `web/embed.go`
- [Terminal UI](https://github.com/polds/tui-streamer/blob/main/web/static/app.js): `web/static/app.js`
- [ANSI Rendering](https://github.com/polds/tui-streamer/blob/main/web/static/app.js): `web/static/app.js`
- [Themes](https://github.com/polds/tui-streamer/blob/main/internal/bundle/themes.go): `internal/bundle/themes.go`

### Other components

- **User**
- **Browser**
- **OS Processes**

## Connections

- User → Browser: uses
- User → Server Entry: starts server
- Server Entry → Bundle Loader: loads YAML
- Server Entry → Session Manager: creates
- Server Entry → Bundle Import: imports startup bundle
- Server Entry → HTTP / WS API: starts listener
- Server Entry → Embedded UI: provides static files
- Server Entry → Browser Launcher: opens UI
- Browser Launcher → Browser: launches
- Browser → HTTP / WS API: HTTP requests
- HTTP / WS API → Embedded UI: serves UI
- HTTP / WS API → Session Manager: manages sessions
- HTTP / WS API → Session State: executes / controls
- HTTP / WS API → Bundle Loader: parses imports
- HTTP / WS API → Command Allowlist: checks commands
- Bundle Import → Session Manager: creates sessions
- Bundle Import → Session State: sets session details
- Bundle Import → Command Allowlist: merges allowlists
- Bundle Loader → Bundle Files: resolves files
- Session State → Command Runner: runs command
- Command Runner → OS Processes: starts process
- OS Processes → Command Runner: writes output
- Command Runner → Session State: streams lines
- Session State → WS Client: broadcasts lines
- HTTP / WS API → WS Client: upgrades connection
- Browser → HTTP / WS API: opens WebSocket
- WS Client → Browser: sends output
- Browser → Terminal UI: interacts
- Terminal UI → HTTP / WS API: calls API
- Terminal UI → ANSI Rendering: formats output
- Terminal UI → Themes: selects theme