# charmbracelet/bubbletea architecture

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

- Interactive diagram: https://gitdiagram.com/charmbracelet/bubbletea
- Repository: https://github.com/charmbracelet/bubbletea

## Overview

Bubble Tea is a Go terminal UI framework implementing an Elm-style event loop: an application supplies a model, initialization command, update logic and declarative view; the runtime reads terminal events, runs commands, updates state and renders frames. The map covers the documented workflow plus terminal input, rendering, command execution and terminal lifecycle. Source excerpts show key runtime and renderer interactions; other capability branches are retained from README documentation, with unverified links left out.

Main entry points: [`tea.go`](https://github.com/charmbracelet/bubbletea/blob/main/tea.go) (Program loop), [`tty.go`](https://github.com/charmbracelet/bubbletea/blob/main/tty.go) (Input reader), [`renderer.go`](https://github.com/charmbracelet/bubbletea/blob/main/renderer.go) (Renderer interface), [`commands.go`](https://github.com/charmbracelet/bubbletea/blob/main/commands.go) (Commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application contract"]
  node_appmodel["Model logic"]
end

subgraph group_runtime["Program runtime"]
  node_program["Program loop<br/>[tea.go]"]
  node_commands["Commands<br/>[commands.go]"]
  node_exec["Interactive exec<br/>[exec.go]"]
  node_options["Program options<br/>[options.go]"]
end

subgraph group_terminal["Terminal I/O"]
  node_input["Input reader<br/>[tty.go]"]
  node_keys["Keyboard events<br/>[key.go]"]
  node_mouse["Mouse events<br/>[mouse.go]"]
  node_renderer_iface["Renderer interface<br/>[renderer.go]"]
  node_cell_renderer["Cell renderer<br/>[cursed_renderer.go]"]
  node_null_renderer["No-op renderer<br/>[nil_renderer.go]"]
  node_screen["Screen output<br/>[screen.go]"]
  node_tty["Terminal control<br/>[tty.go]"]
end

subgraph group_features["Terminal capabilities"]
  node_clipboard["Clipboard<br/>[clipboard.go]"]
  node_color["Color detection<br/>[color.go]"]
  node_profile["Color profile<br/>[profile.go]"]
  node_focus["Focus handling<br/>[focus.go]"]
  node_paste["Bracketed paste<br/>[paste.go]"]
  node_termcap["Terminal queries<br/>[termcap.go]"]
end

node_developer(("App developer"))
node_terminal_actor(("Terminal user"))

node_developer -->|"implements"| node_appmodel
node_developer -->|"starts"| node_program
node_program -->|"updates"| node_appmodel
node_appmodel -->|"returns commands"| node_commands
node_program -->|"runs"| node_commands
node_commands -->|"sends messages"| node_program
node_program -->|"starts reader"| node_input
node_input -->|"streams events"| node_program
node_terminal_actor -.->|"generates input"| node_input
node_input -.->|"decodes keys"| node_keys
node_input -.->|"decodes mouse"| node_mouse
node_program -->|"renders views"| node_renderer_iface
node_renderer_iface -->|"implemented by"| node_cell_renderer
node_renderer_iface -.->|"implemented by"| node_null_renderer
node_cell_renderer -.->|"writes frames"| node_screen
node_program -->|"manages terminal"| node_tty
node_program -->|"dispatches execution"| node_exec
node_exec -->|"releases and restores"| node_tty
node_developer -->|"configures"| node_options
node_options -->|"sets behavior"| node_program
node_program -->|"handles requests"| node_clipboard
node_program -->|"handles queries"| node_color
node_program -.->|"detects profile"| node_profile
node_program -.->|"reports focus"| node_focus
node_program -.->|"handles paste"| node_paste
node_program -.->|"queries capabilities"| node_termcap

click node_program "https://github.com/charmbracelet/bubbletea/blob/main/tea.go"
click node_commands "https://github.com/charmbracelet/bubbletea/blob/main/commands.go"
click node_exec "https://github.com/charmbracelet/bubbletea/blob/main/exec.go"
click node_options "https://github.com/charmbracelet/bubbletea/blob/main/options.go"
click node_input "https://github.com/charmbracelet/bubbletea/blob/main/tty.go"
click node_keys "https://github.com/charmbracelet/bubbletea/blob/main/key.go"
click node_mouse "https://github.com/charmbracelet/bubbletea/blob/main/mouse.go"
click node_renderer_iface "https://github.com/charmbracelet/bubbletea/blob/main/renderer.go"
click node_cell_renderer "https://github.com/charmbracelet/bubbletea/blob/main/cursed_renderer.go"
click node_null_renderer "https://github.com/charmbracelet/bubbletea/blob/main/nil_renderer.go"
click node_screen "https://github.com/charmbracelet/bubbletea/blob/main/screen.go"
click node_tty "https://github.com/charmbracelet/bubbletea/blob/main/tty.go"
click node_clipboard "https://github.com/charmbracelet/bubbletea/blob/main/clipboard.go"
click node_color "https://github.com/charmbracelet/bubbletea/blob/main/color.go"
click node_profile "https://github.com/charmbracelet/bubbletea/blob/main/profile.go"
click node_focus "https://github.com/charmbracelet/bubbletea/blob/main/focus.go"
click node_paste "https://github.com/charmbracelet/bubbletea/blob/main/paste.go"
click node_termcap "https://github.com/charmbracelet/bubbletea/blob/main/termcap.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_appmodel,node_terminal_actor toneBlue
class node_program,node_commands,node_exec,node_options toneAmber
class node_input,node_keys,node_mouse,node_renderer_iface,node_cell_renderer,node_null_renderer,node_screen,node_tty toneMint
class node_clipboard,node_color,node_profile,node_focus,node_paste,node_termcap toneRose
class node_developer toneIndigo
```

## Components

### Application contract

- **Model logic**

### Program runtime

- [Program loop](https://github.com/charmbracelet/bubbletea/blob/main/tea.go): `tea.go`
- [Commands](https://github.com/charmbracelet/bubbletea/blob/main/commands.go): `commands.go`
- [Interactive exec](https://github.com/charmbracelet/bubbletea/blob/main/exec.go): `exec.go`
- [Program options](https://github.com/charmbracelet/bubbletea/blob/main/options.go): `options.go`

### Terminal I/O

- [Input reader](https://github.com/charmbracelet/bubbletea/blob/main/tty.go): `tty.go`
- [Keyboard events](https://github.com/charmbracelet/bubbletea/blob/main/key.go): `key.go`
- [Mouse events](https://github.com/charmbracelet/bubbletea/blob/main/mouse.go): `mouse.go`
- [Renderer interface](https://github.com/charmbracelet/bubbletea/blob/main/renderer.go): `renderer.go`
- [Cell renderer](https://github.com/charmbracelet/bubbletea/blob/main/cursed_renderer.go): `cursed_renderer.go`
- [No-op renderer](https://github.com/charmbracelet/bubbletea/blob/main/nil_renderer.go): `nil_renderer.go`
- [Screen output](https://github.com/charmbracelet/bubbletea/blob/main/screen.go): `screen.go`
- [Terminal control](https://github.com/charmbracelet/bubbletea/blob/main/tty.go): `tty.go`

### Terminal capabilities

- [Clipboard](https://github.com/charmbracelet/bubbletea/blob/main/clipboard.go): `clipboard.go`
- [Color detection](https://github.com/charmbracelet/bubbletea/blob/main/color.go): `color.go`
- [Color profile](https://github.com/charmbracelet/bubbletea/blob/main/profile.go): `profile.go`
- [Focus handling](https://github.com/charmbracelet/bubbletea/blob/main/focus.go): `focus.go`
- [Bracketed paste](https://github.com/charmbracelet/bubbletea/blob/main/paste.go): `paste.go`
- [Terminal queries](https://github.com/charmbracelet/bubbletea/blob/main/termcap.go): `termcap.go`

### Other components

- **App developer**
- **Terminal user**

## Connections

- App developer → Model logic: implements (evidence: `README.md`)
- App developer → Program loop: starts (evidence: `README.md`)
- Program loop → Model logic: updates (evidence: `README.md`)
- Model logic → Commands: returns commands (evidence: `README.md`)
- Program loop → Commands: runs (evidence: `tea.go`)
- Commands → Program loop: sends messages (evidence: `tea.go`)
- Program loop → Input reader: starts reader (evidence: `tty.go`)
- Input reader → Program loop: streams events (evidence: `tty.go`)
- Terminal user → Input reader: generates input
- Input reader → Keyboard events: decodes keys
- Input reader → Mouse events: decodes mouse
- Program loop → Renderer interface: renders views (evidence: `tea.go`)
- Renderer interface → Cell renderer: implemented by (evidence: `cursed_renderer.go`)
- Renderer interface → No-op renderer: implemented by
- Cell renderer → Screen output: writes frames
- Program loop → Terminal control: manages terminal (evidence: `tty.go`)
- Program loop → Interactive exec: dispatches execution (evidence: `tea.go`)
- Interactive exec → Terminal control: releases and restores (evidence: `exec.go`)
- App developer → Program options: configures (evidence: `options.go`)
- Program options → Program loop: sets behavior (evidence: `options.go`)
- Program loop → Clipboard: handles requests (evidence: `tea.go`)
- Program loop → Color detection: handles queries (evidence: `tea.go`)
- Program loop → Color profile: detects profile
- Program loop → Focus handling: reports focus
- Program loop → Bracketed paste: handles paste
- Program loop → Terminal queries: queries capabilities
