# textualize/textual architecture

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

- Interactive diagram: https://gitdiagram.com/textualize/textual
- Repository: https://github.com/textualize/textual

## Overview

Textual is a Python framework for building asynchronous, cross-platform terminal and browser interfaces. The user workflow is to define an App and compose widgets, then run it: the App manages screens and message handling, widgets render through layout and styling, and a platform driver exchanges input and output with the terminal or browser. Other major capabilities include CSS queries, reactive state, command palettes, and rich built-in widgets such as tables, Markdown, and text areas. Edges reflect README statements and sampled source references; unsampled implementation links are omitted where evidence is insufficient.

Main entry points: [`src/textual/widget.py`](https://github.com/textualize/textual/blob/main/src/textual/widget.py) (Widget base), [`src/textual/app.py`](https://github.com/textualize/textual/blob/main/src/textual/app.py) (App lifecycle), [`src/textual/driver.py`](https://github.com/textualize/textual/blob/main/src/textual/driver.py) (Driver interface), [`src/textual/screen.py`](https://github.com/textualize/textual/blob/main/src/textual/screen.py) (Screens)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app_runtime["App runtime"]
  node_app["App lifecycle<br/>[app.py]"]
  node_screen["Screens<br/>[screen.py]"]
  node_message["Message dispatch<br/>[message_pump.py]"]
  node_worker["Async workers<br/>[worker.py]"]
end

subgraph group_ui_model["UI model"]
  node_dom["DOM tree<br/>[dom.py]"]
  node_reactive["Reactive state<br/>[reactive.py]"]
  node_events["Events<br/>[events.py]"]
  node_bindings["Key bindings<br/>[binding.py]"]
end

subgraph group_presentation["Presentation"]
  node_css_parse["CSS parsing<br/>[parse.py]"]
  node_css_query["CSS queries<br/>[query.py]"]
  node_styles["Styles<br/>[styles.py]"]
  node_layout["Layout engine<br/>[layout.py]"]
  node_render["Rendering<br/>[render.py]"]
end

subgraph group_platform_io["Platform I/O"]
  node_driver["Driver interface<br/>[driver.py]"]
  node_terminal_driver["Terminal drivers<br/>[linux_driver.py]"]
  node_browser_driver["Browser driver<br/>[web_driver.py]"]
end

subgraph group_widgets["Widgets"]
  node_widget["Widget base<br/>[widget.py]"]
  node_widget_library["Built-in widgets"]
  node_text_area["Text editor<br/>[_text_area.py]"]
  node_data_table["Data table<br/>[_data_table.py]"]
  node_markdown["Markdown viewer<br/>[_markdown.py]"]
end

node_developer(("App developer"))
node_terminal(("Terminal"))
node_browser(("Browser client"))

node_developer -->|"defines and runs"| node_app
node_app -.->|"manages screens"| node_screen
node_app -.->|"dispatches messages"| node_message
node_app -->|"uses driver"| node_driver
node_app -->|"runs workers"| node_worker
node_screen -.->|"hosts widgets"| node_widget
node_widget -->|"extends DOM"| node_dom
node_widget -->|"uses state"| node_reactive
node_widget -->|"handles events"| node_events
node_widget -->|"uses bindings"| node_bindings
node_dom -->|"creates queries"| node_css_query
node_css_query -->|"parses selectors"| node_css_parse
node_widget -->|"applies styles"| node_styles
node_widget -->|"arranges children"| node_layout
node_widget -->|"renders content"| node_render
node_css_parse -.->|"builds styles"| node_styles
node_widget_library -.->|"extends base"| node_widget
node_text_area -->|"extends base"| node_widget
node_data_table -->|"extends base"| node_widget
node_markdown -->|"extends base"| node_widget
node_driver -->|"selects platform"| node_terminal_driver
node_driver -->|"selects platform"| node_browser_driver
node_terminal_driver -.->|"exchanges I/O"| node_terminal
node_browser_driver -.->|"exchanges I/O"| node_browser

click node_app "https://github.com/textualize/textual/blob/main/src/textual/app.py"
click node_screen "https://github.com/textualize/textual/blob/main/src/textual/screen.py"
click node_message "https://github.com/textualize/textual/blob/main/src/textual/message_pump.py"
click node_worker "https://github.com/textualize/textual/blob/main/src/textual/worker.py"
click node_dom "https://github.com/textualize/textual/blob/main/src/textual/dom.py"
click node_reactive "https://github.com/textualize/textual/blob/main/src/textual/reactive.py"
click node_events "https://github.com/textualize/textual/blob/main/src/textual/events.py"
click node_bindings "https://github.com/textualize/textual/blob/main/src/textual/binding.py"
click node_css_parse "https://github.com/textualize/textual/blob/main/src/textual/css/parse.py"
click node_css_query "https://github.com/textualize/textual/blob/main/src/textual/css/query.py"
click node_styles "https://github.com/textualize/textual/blob/main/src/textual/css/styles.py"
click node_layout "https://github.com/textualize/textual/blob/main/src/textual/layout.py"
click node_render "https://github.com/textualize/textual/blob/main/src/textual/render.py"
click node_widget "https://github.com/textualize/textual/blob/main/src/textual/widget.py"
click node_widget_library "https://github.com/textualize/textual/tree/main/src/textual/widgets"
click node_text_area "https://github.com/textualize/textual/blob/main/src/textual/widgets/_text_area.py"
click node_data_table "https://github.com/textualize/textual/blob/main/src/textual/widgets/_data_table.py"
click node_markdown "https://github.com/textualize/textual/blob/main/src/textual/widgets/_markdown.py"
click node_driver "https://github.com/textualize/textual/blob/main/src/textual/driver.py"
click node_terminal_driver "https://github.com/textualize/textual/blob/main/src/textual/drivers/linux_driver.py"
click node_browser_driver "https://github.com/textualize/textual/blob/main/src/textual/drivers/web_driver.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_app,node_screen,node_message,node_worker,node_browser toneBlue
class node_dom,node_reactive,node_events,node_bindings toneAmber
class node_css_parse,node_css_query,node_styles,node_layout,node_render toneMint
class node_driver,node_terminal_driver,node_browser_driver toneRose
class node_widget,node_widget_library,node_text_area,node_data_table,node_markdown,node_developer,node_terminal toneIndigo
```

## Components

### App runtime

- [App lifecycle](https://github.com/textualize/textual/blob/main/src/textual/app.py): `src/textual/app.py`
- [Screens](https://github.com/textualize/textual/blob/main/src/textual/screen.py): `src/textual/screen.py`
- [Message dispatch](https://github.com/textualize/textual/blob/main/src/textual/message_pump.py): `src/textual/message_pump.py`
- [Async workers](https://github.com/textualize/textual/blob/main/src/textual/worker.py): `src/textual/worker.py`

### UI model

- [DOM tree](https://github.com/textualize/textual/blob/main/src/textual/dom.py): `src/textual/dom.py`
- [Reactive state](https://github.com/textualize/textual/blob/main/src/textual/reactive.py): `src/textual/reactive.py`
- [Events](https://github.com/textualize/textual/blob/main/src/textual/events.py): `src/textual/events.py`
- [Key bindings](https://github.com/textualize/textual/blob/main/src/textual/binding.py): `src/textual/binding.py`

### Presentation

- [CSS parsing](https://github.com/textualize/textual/blob/main/src/textual/css/parse.py): `src/textual/css/parse.py`
- [CSS queries](https://github.com/textualize/textual/blob/main/src/textual/css/query.py): `src/textual/css/query.py`
- [Styles](https://github.com/textualize/textual/blob/main/src/textual/css/styles.py): `src/textual/css/styles.py`
- [Layout engine](https://github.com/textualize/textual/blob/main/src/textual/layout.py): `src/textual/layout.py`
- [Rendering](https://github.com/textualize/textual/blob/main/src/textual/render.py): `src/textual/render.py`

### Platform I/O

- [Driver interface](https://github.com/textualize/textual/blob/main/src/textual/driver.py): `src/textual/driver.py`
- [Terminal drivers](https://github.com/textualize/textual/blob/main/src/textual/drivers/linux_driver.py): `src/textual/drivers/linux_driver.py`
- [Browser driver](https://github.com/textualize/textual/blob/main/src/textual/drivers/web_driver.py): `src/textual/drivers/web_driver.py`

### Widgets

- [Widget base](https://github.com/textualize/textual/blob/main/src/textual/widget.py): `src/textual/widget.py`
- [Built-in widgets](https://github.com/textualize/textual/tree/main/src/textual/widgets): `src/textual/widgets`
- [Text editor](https://github.com/textualize/textual/blob/main/src/textual/widgets/_text_area.py): `src/textual/widgets/_text_area.py`
- [Data table](https://github.com/textualize/textual/blob/main/src/textual/widgets/_data_table.py): `src/textual/widgets/_data_table.py`
- [Markdown viewer](https://github.com/textualize/textual/blob/main/src/textual/widgets/_markdown.py): `src/textual/widgets/_markdown.py`

### Other components

- **App developer**
- **Terminal**
- **Browser client**

## Connections

- App developer → App lifecycle: defines and runs
- App lifecycle → Screens: manages screens (evidence: `src/textual/app.py`)
- App lifecycle → Message dispatch: dispatches messages
- App lifecycle → Driver interface: uses driver (evidence: `src/textual/driver.py`)
- App lifecycle → Async workers: runs workers (evidence: `src/textual/worker.py`)
- Screens → Widget base: hosts widgets
- Widget base → DOM tree: extends DOM (evidence: `src/textual/dom.py`)
- Widget base → Reactive state: uses state (evidence: `src/textual/reactive.py`)
- Widget base → Events: handles events (evidence: `src/textual/events.py`)
- Widget base → Key bindings: uses bindings (evidence: `src/textual/binding.py`)
- DOM tree → CSS queries: creates queries (evidence: `src/textual/dom.py`)
- CSS queries → CSS parsing: parses selectors (evidence: `src/textual/css/query.py`)
- Widget base → Styles: applies styles (evidence: `src/textual/widget.py`)
- Widget base → Layout engine: arranges children (evidence: `src/textual/widget.py`)
- Widget base → Rendering: renders content (evidence: `src/textual/widget.py`)
- CSS parsing → Styles: builds styles (evidence: `src/textual/css/styles.py`)
- Built-in widgets → Widget base: extends base (evidence: `src/textual/widgets/_data_table.py`)
- Text editor → Widget base: extends base (evidence: `src/textual/widgets/_text_area.py`)
- Data table → Widget base: extends base (evidence: `src/textual/widgets/_data_table.py`)
- Markdown viewer → Widget base: extends base (evidence: `src/textual/widgets/_markdown.py`)
- Driver interface → Terminal drivers: selects platform (evidence: `src/textual/drivers/linux_driver.py`)
- Driver interface → Browser driver: selects platform (evidence: `src/textual/drivers/web_driver.py`)
- Terminal drivers → Terminal: exchanges I/O
- Browser driver → Browser client: exchanges I/O
