# nuuttisir/tuiwatchers architecture

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

- Interactive diagram: https://gitdiagram.com/nuuttisir/tuiwatchers
- Repository: https://github.com/nuuttisir/tuiwatchers

## Overview

#### Purpose and Entry Point
TuiWatchers is a Go terminal-oriented Twitch client: it authenticates a user, lists followed live channels, launches playback through MPV, and opens a separate terminal for interactive chat. Process startup and top-level dependency wiring are in `main.go`.

#### Authentication and Session Persistence
OAuth acquisition, refresh/use of saved credentials, and Twitch authorization interactions are centered in:
- `internal/twitch/oauth.go`
- `internal/tui/auth.go`
- `internal/storage/storage.go`

Persisted token state forms the boundary between local session storage and authenticated Twitch API/EventSub requests.

#### Twitch Platform Integration
The Twitch integration layer encapsulates HTTP/API client setup, Helix-style data retrieval, OAuth-backed requests, and EventSub/WebSocket-related behavior:
- `internal/twitch/client.go`
- `internal/twitch/api.go`
- `internal/twitch/eventsub.go`

This layer supplies authenticated user/followed-stream data to the UI and chat subscription/control paths, keeping Twitch protocol concerns outside rendering code.

#### Stream Browser and Playback Flow
The primary UI presents followed channels that are currently live and maps keyboard selection to stream playback:
- `internal/tui/streams.go`
- `internal/tui/styles.go`
- `main.go`

Selecting a channel starts external MPV playback; MPV relies on `yt-dlp` for stream extraction. These are required host executables rather than Go-managed streaming infrastructure.

#### Dedicated Chat Terminal
Chat is intentionally separate from the stream-browser UI: the application spawns a Ghostty terminal window for a selected channel, then runs live chat display and message input there:
- `internal/chat/terminal.go`
- `internal/chat/render.go`
- `internal/chat/input.go`

The terminal launcher is a platform/runtime boundary, while rendering and input handle the interactive chat loop.

#### Chat Events and Emotes
Live chat transport is driven by Twitch WebSocket/EventSub functionality, with incoming messages rendered after emote-aware transformation:
- `internal/twitch/eventsub.go`
- `internal/chat/render.go`
- `internal/emotes/emotes.go`

Outbound text from chat input flows back through the Twitch client; incoming messages flow from Twitch events through emote parsing into terminal rendering.

#### Material Runtime Dependencies
The binary is a Go module (`go.mod`) and depends operationally on Twitch services plus local tools: Ghostty for chat windows, MPV for viewing, and yt-dlp for source resolution. Setup-specific dependency expectations are documented in `Dependencies.md`.

Main entry points: [`internal/tui/streams.go`](https://github.com/nuuttisir/tuiwatchers/blob/main/internal/tui/streams.go) (Live stream browser), [`internal/twitch/client.go`](https://github.com/nuuttisir/tuiwatchers/blob/main/internal/twitch/client.go) (Twitch API client), [`internal/chat/terminal.go`](https://github.com/nuuttisir/tuiwatchers/blob/main/internal/chat/terminal.go) (Chat terminal launcher), [`main.go`](https://github.com/nuuttisir/tuiwatchers/blob/main/main.go) (Process wiring)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_main["Process wiring<br/>Go entry point<br/>[main.go]"]
  node_auth_ui["Authentication UI<br/>TUI auth<br/>[auth.go]"]
  node_streams_ui["Live stream browser<br/>TUI screen<br/>[streams.go]"]
  node_styles["TUI styles<br/>presentation<br/>[styles.go]"]
  node_storage[("Token storage<br/>session persistence<br/>[storage.go]")]
  node_go_module["Go module<br/>build module<br/>[go.mod]"]
end

subgraph group_twitch["Twitch integration"]
  node_oauth["OAuth flow<br/>Twitch auth<br/>[oauth.go]"]
  node_twitch_client["Twitch API client<br/>platform client<br/>[client.go]"]
  node_twitch_api["Helix data access<br/>API operations<br/>[api.go]"]
  node_eventsub["EventSub transport<br/>WebSocket events<br/>[eventsub.go]"]
end

subgraph group_chat["Chat runtime"]
  node_chat_terminal["Chat terminal launcher<br/>terminal boundary<br/>[terminal.go]"]
  node_chat_input["Chat input loop<br/>interactive input<br/>[input.go]"]
  node_chat_render["Chat renderer<br/>terminal rendering<br/>[render.go]"]
  node_emotes["Emote transformer<br/>message parsing<br/>[emotes.go]"]
end

subgraph group_external["External dependencies"]
  node_twitch_service{{"Twitch services<br/>OAuth, Helix, EventSub"}}
  node_ghostty{{"Ghostty<br/>host terminal"}}
  node_mpv{{"MPV<br/>host player"}}
  node_yt_dlp{{"yt-dlp<br/>stream extractor"}}
  node_dependencies["Dependency guide<br/>setup documentation<br/>[Dependencies.md]"]
end

node_main -->|"starts"| node_auth_ui
node_main -->|"starts"| node_streams_ui
node_main -->|"wires"| node_twitch_client
node_auth_ui -->|"authenticates with"| node_oauth
node_oauth -->|"loads and saves tokens"| node_storage
node_oauth -->|"OAuth authorization"| node_twitch_service
node_twitch_client -->|"provides"| node_twitch_api
node_twitch_client -->|"authenticates"| node_eventsub
node_twitch_client -->|"API requests"| node_twitch_service
node_streams_ui -->|"loads followed live channels"| node_twitch_api
node_streams_ui -->|"uses"| node_styles
node_streams_ui -->|"launches selected stream"| node_mpv
node_mpv -->|"extracts stream source"| node_yt_dlp
node_streams_ui -->|"opens chat for channel"| node_chat_terminal
node_chat_terminal -->|"spawns window"| node_ghostty
node_chat_terminal -->|"runs"| node_chat_render
node_chat_terminal -->|"runs"| node_chat_input
node_eventsub -->|"incoming messages"| node_chat_render
node_chat_render -->|"transforms messages"| node_emotes
node_chat_input -->|"sends chat text"| node_twitch_client
node_dependencies -.->|"documents"| node_ghostty
node_dependencies -.->|"documents"| node_mpv
node_dependencies -.->|"documents"| node_yt_dlp

click node_main "https://github.com/nuuttisir/tuiwatchers/blob/main/main.go"
click node_auth_ui "https://github.com/nuuttisir/tuiwatchers/blob/main/internal/tui/auth.go"
click node_streams_ui "https://github.com/nuuttisir/tuiwatchers/blob/main/internal/tui/streams.go"
click node_styles "https://github.com/nuuttisir/tuiwatchers/blob/main/internal/tui/styles.go"
click node_storage "https://github.com/nuuttisir/tuiwatchers/blob/main/internal/storage/storage.go"
click node_oauth "https://github.com/nuuttisir/tuiwatchers/blob/main/internal/twitch/oauth.go"
click node_twitch_client "https://github.com/nuuttisir/tuiwatchers/blob/main/internal/twitch/client.go"
click node_twitch_api "https://github.com/nuuttisir/tuiwatchers/blob/main/internal/twitch/api.go"
click node_eventsub "https://github.com/nuuttisir/tuiwatchers/blob/main/internal/twitch/eventsub.go"
click node_chat_terminal "https://github.com/nuuttisir/tuiwatchers/blob/main/internal/chat/terminal.go"
click node_chat_input "https://github.com/nuuttisir/tuiwatchers/blob/main/internal/chat/input.go"
click node_chat_render "https://github.com/nuuttisir/tuiwatchers/blob/main/internal/chat/render.go"
click node_emotes "https://github.com/nuuttisir/tuiwatchers/blob/main/internal/emotes/emotes.go"
click node_dependencies "https://github.com/nuuttisir/tuiwatchers/blob/main/Dependencies.md"
click node_go_module "https://github.com/nuuttisir/tuiwatchers/blob/main/go.mod"

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_main,node_auth_ui,node_streams_ui,node_styles,node_storage,node_go_module toneBlue
class node_oauth,node_twitch_client,node_twitch_api,node_eventsub toneAmber
class node_chat_terminal,node_chat_input,node_chat_render,node_emotes toneMint
class node_twitch_service,node_ghostty,node_mpv,node_yt_dlp,node_dependencies toneRose
```

## Components

### Application

- [Process wiring](https://github.com/nuuttisir/tuiwatchers/blob/main/main.go): Go entry point · Starts the client and wires top-level flows. · `main.go`
- [Authentication UI](https://github.com/nuuttisir/tuiwatchers/blob/main/internal/tui/auth.go): TUI auth · `internal/tui/auth.go`
- [Live stream browser](https://github.com/nuuttisir/tuiwatchers/blob/main/internal/tui/streams.go): TUI screen · Lists followed live channels and handles selection. · `internal/tui/streams.go`
- [TUI styles](https://github.com/nuuttisir/tuiwatchers/blob/main/internal/tui/styles.go): presentation · `internal/tui/styles.go`
- [Token storage](https://github.com/nuuttisir/tuiwatchers/blob/main/internal/storage/storage.go): session persistence · Persists OAuth token state locally. · `internal/storage/storage.go`
- [Go module](https://github.com/nuuttisir/tuiwatchers/blob/main/go.mod): build module · `go.mod`

### Twitch integration

- [OAuth flow](https://github.com/nuuttisir/tuiwatchers/blob/main/internal/twitch/oauth.go): Twitch auth · Acquires and refreshes user credentials. · `internal/twitch/oauth.go`
- [Twitch API client](https://github.com/nuuttisir/tuiwatchers/blob/main/internal/twitch/client.go): platform client · Owns authenticated HTTP setup and Helix data access. · `internal/twitch/client.go`
- [Helix data access](https://github.com/nuuttisir/tuiwatchers/blob/main/internal/twitch/api.go): API operations · Retrieves authenticated user and followed-stream data. · `internal/twitch/api.go`
- [EventSub transport](https://github.com/nuuttisir/tuiwatchers/blob/main/internal/twitch/eventsub.go): WebSocket events · Receives chat events and supports chat control paths. · `internal/twitch/eventsub.go`

### Chat runtime

- [Chat terminal launcher](https://github.com/nuuttisir/tuiwatchers/blob/main/internal/chat/terminal.go): terminal boundary · Spawns a separate Ghostty window for a channel. · `internal/chat/terminal.go`
- [Chat input loop](https://github.com/nuuttisir/tuiwatchers/blob/main/internal/chat/input.go): interactive input · `internal/chat/input.go`
- [Chat renderer](https://github.com/nuuttisir/tuiwatchers/blob/main/internal/chat/render.go): terminal rendering · `internal/chat/render.go`
- [Emote transformer](https://github.com/nuuttisir/tuiwatchers/blob/main/internal/emotes/emotes.go): message parsing · `internal/emotes/emotes.go`

### External dependencies

- **Twitch services**: OAuth, Helix, EventSub
- **Ghostty**: host terminal
- **MPV**: host player · Plays selected streams.
- **yt-dlp**: stream extractor · Resolves playable stream sources for MPV.
- [Dependency guide](https://github.com/nuuttisir/tuiwatchers/blob/main/Dependencies.md): setup documentation · `Dependencies.md`

## Connections

- Process wiring → Authentication UI: starts
- Process wiring → Live stream browser: starts
- Process wiring → Twitch API client: wires
- Authentication UI → OAuth flow: authenticates with
- OAuth flow → Token storage: loads and saves tokens
- OAuth flow → Twitch services: OAuth authorization
- Twitch API client → Helix data access: provides
- Twitch API client → EventSub transport: authenticates
- Twitch API client → Twitch services: API requests
- Live stream browser → Helix data access: loads followed live channels
- Live stream browser → TUI styles: uses
- Live stream browser → MPV: launches selected stream
- MPV → yt-dlp: extracts stream source
- Live stream browser → Chat terminal launcher: opens chat for channel
- Chat terminal launcher → Ghostty: spawns window
- Chat terminal launcher → Chat renderer: runs
- Chat terminal launcher → Chat input loop: runs
- EventSub transport → Chat renderer: incoming messages
- Chat renderer → Emote transformer: transforms messages
- Chat input loop → Twitch API client: sends chat text
- Dependency guide → Ghostty: documents
- Dependency guide → MPV: documents
- Dependency guide → yt-dlp: documents
