# beeware/toga architecture

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

- Interactive diagram: https://gitdiagram.com/beeware/toga
- Repository: https://github.com/beeware/toga

## Overview

Toga is a Python native, OS-native GUI toolkit. An application uses the shared Toga API to define app behavior and UI; platform selection then supplies a native backend that presents widgets and handles OS events. The repository also includes shared commands, dialogs, documents, hardware access, screens, and data sources. Backend coverage is broad, but only a subset of backend source was sampled; uncertain dispatch and runtime links are therefore omitted or marked unverified.

Main entry points: [`core/src/toga/platform.py`](https://github.com/beeware/toga/blob/main/core/src/toga/platform.py) (Backend selection), [`core/src/toga/app.py`](https://github.com/beeware/toga/blob/main/core/src/toga/app.py) (App lifecycle), [`core/src/toga/command.py`](https://github.com/beeware/toga/blob/main/core/src/toga/command.py) (Commands and menus), [`core/src/toga/screens.py`](https://github.com/beeware/toga/blob/main/core/src/toga/screens.py) (Screens)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shared["Shared toolkit"]
  node_app["App lifecycle<br/>[app.py]"]
  node_platform["Backend selection<br/>[platform.py]"]
  node_commands["Commands and menus<br/>[command.py]"]
  node_handlers["Async handlers<br/>[handlers.py]"]
  node_dialogs["Dialogs<br/>[dialogs.py]"]
  node_documents["Document support<br/>[documents.py]"]
end

subgraph group_ui["UI and data"]
  node_widgets["Widget interfaces"]
  node_window["Windows<br/>[window.py]"]
  node_sources["List and tree data"]
  node_style["Style and layout"]
end

subgraph group_native["Native backends"]
  node_android["Android backend<br/>[app.py]"]
  node_cocoa["Cocoa backend<br/>[app.py]"]
  node_gtk["GTK backend<br/>[app.py]"]
  node_ios["iOS backend<br/>[app.py]"]
  node_qt["Qt backend<br/>[app.py]"]
  node_web["Web backend<br/>[app.py]"]
  node_textual["Textual backend<br/>[app.py]"]
  node_winforms["Windows backend<br/>[app.py]"]
end

subgraph group_extensions["Platform services"]
  node_hardware["Hardware access"]
  node_screens["Screens<br/>[screens.py]"]
  node_icons["Icons and assets<br/>[icons.py]"]
end

node_developer(("Python app developer"))

node_developer -->|"defines app"| node_app
node_app -->|"selects backend"| node_platform
node_app -->|"creates commands"| node_commands
node_app -->|"opens dialogs"| node_dialogs
node_app -->|"configures documents"| node_documents
node_app -->|"accesses hardware"| node_hardware
node_app -->|"uses screens"| node_screens
node_app -->|"uses icons"| node_icons
node_commands -->|"wraps handlers"| node_handlers
node_commands -->|"uses icons"| node_icons
node_platform -.->|"loads backend"| node_android
node_platform -.->|"loads backend"| node_cocoa
node_platform -.->|"loads backend"| node_gtk
node_platform -.->|"loads backend"| node_ios
node_platform -.->|"loads backend"| node_qt
node_platform -.->|"loads backend"| node_web
node_platform -.->|"loads backend"| node_textual
node_platform -.->|"loads backend"| node_winforms
node_android -->|"implements screens"| node_screens
node_cocoa -->|"builds menus"| node_commands
node_gtk -->|"registers actions"| node_commands
node_ios -->|"uses screens"| node_screens
node_qt -->|"uses commands"| node_commands
node_web -->|"uses screens"| node_screens
node_textual -->|"uses screens"| node_screens
node_winforms -->|"uses dialogs"| node_dialogs
node_widgets -.->|"uses data sources"| node_sources
node_widgets -.->|"uses styling"| node_style
node_widgets -.->|"displayed in"| node_window

click node_app "https://github.com/beeware/toga/blob/main/core/src/toga/app.py"
click node_platform "https://github.com/beeware/toga/blob/main/core/src/toga/platform.py"
click node_commands "https://github.com/beeware/toga/blob/main/core/src/toga/command.py"
click node_handlers "https://github.com/beeware/toga/blob/main/core/src/toga/handlers.py"
click node_dialogs "https://github.com/beeware/toga/blob/main/core/src/toga/dialogs.py"
click node_documents "https://github.com/beeware/toga/blob/main/core/src/toga/documents.py"
click node_widgets "https://github.com/beeware/toga/tree/main/core/src/toga/widgets"
click node_window "https://github.com/beeware/toga/blob/main/core/src/toga/window.py"
click node_sources "https://github.com/beeware/toga/tree/main/core/src/toga/sources"
click node_style "https://github.com/beeware/toga/tree/main/core/src/toga/style"
click node_android "https://github.com/beeware/toga/blob/main/android/src/toga_android/app.py"
click node_cocoa "https://github.com/beeware/toga/blob/main/cocoa/src/toga_cocoa/app.py"
click node_gtk "https://github.com/beeware/toga/blob/main/gtk/src/toga_gtk/app.py"
click node_ios "https://github.com/beeware/toga/blob/main/iOS/src/toga_iOS/app.py"
click node_qt "https://github.com/beeware/toga/blob/main/qt/src/toga_qt/app.py"
click node_web "https://github.com/beeware/toga/blob/main/web/src/toga_web/app.py"
click node_textual "https://github.com/beeware/toga/blob/main/textual/src/toga_textual/app.py"
click node_winforms "https://github.com/beeware/toga/blob/main/winforms/src/toga_winforms/app.py"
click node_hardware "https://github.com/beeware/toga/tree/main/core/src/toga/hardware"
click node_screens "https://github.com/beeware/toga/blob/main/core/src/toga/screens.py"
click node_icons "https://github.com/beeware/toga/blob/main/core/src/toga/icons.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_platform,node_commands,node_handlers,node_dialogs,node_documents toneBlue
class node_widgets,node_window,node_sources,node_style toneAmber
class node_android,node_cocoa,node_gtk,node_ios,node_qt,node_web,node_textual,node_winforms toneMint
class node_hardware,node_screens,node_icons toneRose
class node_developer toneIndigo
```

## Components

### Shared toolkit

- [App lifecycle](https://github.com/beeware/toga/blob/main/core/src/toga/app.py): `core/src/toga/app.py`
- [Backend selection](https://github.com/beeware/toga/blob/main/core/src/toga/platform.py): `core/src/toga/platform.py`
- [Commands and menus](https://github.com/beeware/toga/blob/main/core/src/toga/command.py): `core/src/toga/command.py`
- [Async handlers](https://github.com/beeware/toga/blob/main/core/src/toga/handlers.py): `core/src/toga/handlers.py`
- [Dialogs](https://github.com/beeware/toga/blob/main/core/src/toga/dialogs.py): `core/src/toga/dialogs.py`
- [Document support](https://github.com/beeware/toga/blob/main/core/src/toga/documents.py): `core/src/toga/documents.py`

### UI and data

- [Widget interfaces](https://github.com/beeware/toga/tree/main/core/src/toga/widgets): `core/src/toga/widgets`
- [Windows](https://github.com/beeware/toga/blob/main/core/src/toga/window.py): `core/src/toga/window.py`
- [List and tree data](https://github.com/beeware/toga/tree/main/core/src/toga/sources): `core/src/toga/sources`
- [Style and layout](https://github.com/beeware/toga/tree/main/core/src/toga/style): `core/src/toga/style`

### Native backends

- [Android backend](https://github.com/beeware/toga/blob/main/android/src/toga_android/app.py): `android/src/toga_android/app.py`
- [Cocoa backend](https://github.com/beeware/toga/blob/main/cocoa/src/toga_cocoa/app.py): `cocoa/src/toga_cocoa/app.py`
- [GTK backend](https://github.com/beeware/toga/blob/main/gtk/src/toga_gtk/app.py): `gtk/src/toga_gtk/app.py`
- [iOS backend](https://github.com/beeware/toga/blob/main/iOS/src/toga_iOS/app.py): `iOS/src/toga_iOS/app.py`
- [Qt backend](https://github.com/beeware/toga/blob/main/qt/src/toga_qt/app.py): `qt/src/toga_qt/app.py`
- [Web backend](https://github.com/beeware/toga/blob/main/web/src/toga_web/app.py): `web/src/toga_web/app.py`
- [Textual backend](https://github.com/beeware/toga/blob/main/textual/src/toga_textual/app.py): `textual/src/toga_textual/app.py`
- [Windows backend](https://github.com/beeware/toga/blob/main/winforms/src/toga_winforms/app.py): `winforms/src/toga_winforms/app.py`

### Platform services

- [Hardware access](https://github.com/beeware/toga/tree/main/core/src/toga/hardware): `core/src/toga/hardware`
- [Screens](https://github.com/beeware/toga/blob/main/core/src/toga/screens.py): `core/src/toga/screens.py`
- [Icons and assets](https://github.com/beeware/toga/blob/main/core/src/toga/icons.py): `core/src/toga/icons.py`

### Other components

- **Python app developer**

## Connections

- Python app developer → App lifecycle: defines app (evidence: `README.md`)
- App lifecycle → Backend selection: selects backend (evidence: `core/src/toga/app.py`)
- App lifecycle → Commands and menus: creates commands (evidence: `core/src/toga/app.py`)
- App lifecycle → Dialogs: opens dialogs (evidence: `core/src/toga/app.py`)
- App lifecycle → Document support: configures documents (evidence: `core/src/toga/app.py`)
- App lifecycle → Hardware access: accesses hardware (evidence: `core/src/toga/app.py`)
- App lifecycle → Screens: uses screens (evidence: `core/src/toga/app.py`)
- App lifecycle → Icons and assets: uses icons (evidence: `core/src/toga/app.py`)
- Commands and menus → Async handlers: wraps handlers (evidence: `core/src/toga/command.py`)
- Commands and menus → Icons and assets: uses icons (evidence: `core/src/toga/command.py`)
- Backend selection → Android backend: loads backend
- Backend selection → Cocoa backend: loads backend (evidence: `cocoa/src/toga_cocoa/app.py`)
- Backend selection → GTK backend: loads backend
- Backend selection → iOS backend: loads backend
- Backend selection → Qt backend: loads backend
- Backend selection → Web backend: loads backend
- Backend selection → Textual backend: loads backend
- Backend selection → Windows backend: loads backend
- Android backend → Screens: implements screens
- Cocoa backend → Commands and menus: builds menus (evidence: `cocoa/src/toga_cocoa/app.py`)
- GTK backend → Commands and menus: registers actions (evidence: `gtk/src/toga_gtk/app.py`)
- iOS backend → Screens: uses screens (evidence: `iOS/src/toga_iOS/app.py`)
- Qt backend → Commands and menus: uses commands (evidence: `qt/src/toga_qt/app.py`)
- Web backend → Screens: uses screens (evidence: `web/src/toga_web/app.py`)
- Textual backend → Screens: uses screens (evidence: `textual/src/toga_textual/app.py`)
- Windows backend → Dialogs: uses dialogs (evidence: `winforms/src/toga_winforms/app.py`)
- Widget interfaces → List and tree data: uses data sources
- Widget interfaces → Style and layout: uses styling
- Widget interfaces → Windows: displayed in
