# bcicen/ctop architecture

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

- Interactive diagram: https://gitdiagram.com/bcicen/ctop
- Repository: https://github.com/bcicen/ctop

## Overview

ctop is a terminal dashboard for live container metrics, with compact multi-container and detailed single-container views. The main workflow initializes configuration and a selected connector, discovers containers, collects metrics, then renders and sorts/filter them in the UI. Docker collection, container lifecycle management, logs, and the documented runC connector are distinct product stages. Edges are limited to relationships shown in excerpts, SOURCE INDEX references, or README statements; unsampled implementation details are not inferred.

Main entry points: [`main.go`](https://github.com/bcicen/ctop/blob/master/main.go) (ctop Application), [`connector/docker.go`](https://github.com/bcicen/ctop/blob/master/connector/docker.go) (Docker Connector), [`container/main.go`](https://github.com/bcicen/ctop/blob/master/container/main.go) (Container Model), [`menus.go`](https://github.com/bcicen/ctop/blob/master/menus.go) (Menus and Actions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application and UI"]
  node_app["ctop Application<br/>[main.go]"]
  node_config["Configuration<br/>[file.go]"]
  node_menus["Menus and Actions<br/>[menus.go]"]
  node_widgets["Terminal Widgets<br/>[view.go]"]
end

subgraph group_connectors["Container Connectors"]
  node_registry["Connector Registry<br/>[main.go]"]
  node_docker["Docker Connector<br/>[docker.go]"]
  node_runc["runC Connector<br/>[runc.go]"]
end

subgraph group_runtime["Container Runtime Data"]
  node_container["Container Model<br/>[main.go]"]
  node_manager["Lifecycle Manager<br/>[docker.go]"]
  node_metrics["Metric Types<br/>[main.go]"]
  node_collector["Docker Metrics<br/>[docker.go]"]
  node_logs["Container Logs<br/>[docker_logs.go]"]
  node_sortfilter["Sort and Filter<br/>[sort.go]"]
end

subgraph group_views["Monitoring Views"]
  node_compact["Compact Dashboard<br/>[grid.go]"]
  node_row["Metric Rows<br/>[row.go]"]
  node_single["Single View<br/>[main.go]"]
  node_logview["Log View<br/>[logs.go]"]
  node_grid["View Layout<br/>[grid.go]"]
end

node_operator(("Operator"))
node_dockerengine["Docker Engine"]

node_operator -->|"runs"| node_app
node_app -->|"loads"| node_config
node_app -->|"selects connector"| node_registry
node_app -->|"initializes"| node_compact
node_app -->|"initializes"| node_widgets
node_operator -->|"uses keybindings"| node_menus
node_menus -->|"invokes actions"| node_container
node_menus -->|"updates options"| node_config
node_registry -->|"creates"| node_docker
node_registry -.->|"creates"| node_runc
node_docker -->|"queries and watches"| node_dockerengine
node_docker -->|"creates"| node_collector
node_docker -->|"creates"| node_manager
node_docker -->|"discovers and refreshes"| node_container
node_docker -.->|"provides"| node_logs
node_container -->|"starts and reads"| node_collector
node_container -->|"delegates lifecycle"| node_manager
node_container -->|"stores metrics"| node_metrics
node_collector -->|"streams"| node_metrics
node_container -->|"updates widgets"| node_row
node_container -->|"exposes logs"| node_logs
node_docker -->|"sorts and filters"| node_sortfilter
node_sortfilter -->|"reads preferences"| node_config
node_compact -.->|"renders rows"| node_row
node_app -->|"supports inspection view"| node_single
node_single -.->|"includes logs"| node_logview
node_app -->|"lays out views"| node_grid

click node_app "https://github.com/bcicen/ctop/blob/master/main.go"
click node_config "https://github.com/bcicen/ctop/blob/master/config/file.go"
click node_menus "https://github.com/bcicen/ctop/blob/master/menus.go"
click node_widgets "https://github.com/bcicen/ctop/blob/master/widgets/view.go"
click node_registry "https://github.com/bcicen/ctop/blob/master/connector/main.go"
click node_docker "https://github.com/bcicen/ctop/blob/master/connector/docker.go"
click node_runc "https://github.com/bcicen/ctop/blob/master/connector/runc.go"
click node_container "https://github.com/bcicen/ctop/blob/master/container/main.go"
click node_manager "https://github.com/bcicen/ctop/blob/master/connector/manager/docker.go"
click node_metrics "https://github.com/bcicen/ctop/blob/master/models/main.go"
click node_collector "https://github.com/bcicen/ctop/blob/master/connector/collector/docker.go"
click node_logs "https://github.com/bcicen/ctop/blob/master/connector/collector/docker_logs.go"
click node_sortfilter "https://github.com/bcicen/ctop/blob/master/container/sort.go"
click node_compact "https://github.com/bcicen/ctop/blob/master/cwidgets/compact/grid.go"
click node_row "https://github.com/bcicen/ctop/blob/master/cwidgets/compact/row.go"
click node_single "https://github.com/bcicen/ctop/blob/master/cwidgets/single/main.go"
click node_logview "https://github.com/bcicen/ctop/blob/master/cwidgets/single/logs.go"
click node_grid "https://github.com/bcicen/ctop/blob/master/grid.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_app,node_config,node_menus,node_widgets toneBlue
class node_registry,node_docker,node_runc toneAmber
class node_container,node_manager,node_metrics,node_collector,node_logs,node_sortfilter toneMint
class node_compact,node_row,node_single,node_logview,node_grid toneRose
class node_operator,node_dockerengine toneIndigo
```

## Components

### Application and UI

- [ctop Application](https://github.com/bcicen/ctop/blob/master/main.go): `main.go`
- [Configuration](https://github.com/bcicen/ctop/blob/master/config/file.go): `config/file.go`
- [Menus and Actions](https://github.com/bcicen/ctop/blob/master/menus.go): `menus.go`
- [Terminal Widgets](https://github.com/bcicen/ctop/blob/master/widgets/view.go): `widgets/view.go`

### Container Connectors

- [Connector Registry](https://github.com/bcicen/ctop/blob/master/connector/main.go): `connector/main.go`
- [Docker Connector](https://github.com/bcicen/ctop/blob/master/connector/docker.go): `connector/docker.go`
- [runC Connector](https://github.com/bcicen/ctop/blob/master/connector/runc.go): `connector/runc.go`

### Container Runtime Data

- [Container Model](https://github.com/bcicen/ctop/blob/master/container/main.go): `container/main.go`
- [Lifecycle Manager](https://github.com/bcicen/ctop/blob/master/connector/manager/docker.go): `connector/manager/docker.go`
- [Metric Types](https://github.com/bcicen/ctop/blob/master/models/main.go): `models/main.go`
- [Docker Metrics](https://github.com/bcicen/ctop/blob/master/connector/collector/docker.go): `connector/collector/docker.go`
- [Container Logs](https://github.com/bcicen/ctop/blob/master/connector/collector/docker_logs.go): `connector/collector/docker_logs.go`
- [Sort and Filter](https://github.com/bcicen/ctop/blob/master/container/sort.go): `container/sort.go`

### Monitoring Views

- [Compact Dashboard](https://github.com/bcicen/ctop/blob/master/cwidgets/compact/grid.go): `cwidgets/compact/grid.go`
- [Metric Rows](https://github.com/bcicen/ctop/blob/master/cwidgets/compact/row.go): `cwidgets/compact/row.go`
- [Single View](https://github.com/bcicen/ctop/blob/master/cwidgets/single/main.go): `cwidgets/single/main.go`
- [Log View](https://github.com/bcicen/ctop/blob/master/cwidgets/single/logs.go): `cwidgets/single/logs.go`
- [View Layout](https://github.com/bcicen/ctop/blob/master/grid.go): `grid.go`

### Other components

- **Operator**
- **Docker Engine**

## Connections

- Operator → ctop Application: runs
- ctop Application → Configuration: loads (evidence: `main.go`)
- ctop Application → Connector Registry: selects connector (evidence: `main.go`)
- ctop Application → Compact Dashboard: initializes (evidence: `main.go`)
- ctop Application → Terminal Widgets: initializes (evidence: `main.go`)
- Operator → Menus and Actions: uses keybindings
- Menus and Actions → Container Model: invokes actions (evidence: `menus.go`)
- Menus and Actions → Configuration: updates options (evidence: `menus.go`)
- Connector Registry → Docker Connector: creates (evidence: `connector/docker.go`)
- Connector Registry → runC Connector: creates
- Docker Connector → Docker Engine: queries and watches (evidence: `connector/docker.go`)
- Docker Connector → Docker Metrics: creates (evidence: `connector/docker.go`)
- Docker Connector → Lifecycle Manager: creates (evidence: `connector/docker.go`)
- Docker Connector → Container Model: discovers and refreshes (evidence: `connector/docker.go`)
- Docker Connector → Container Logs: provides
- Container Model → Docker Metrics: starts and reads (evidence: `container/main.go`)
- Container Model → Lifecycle Manager: delegates lifecycle (evidence: `container/main.go`)
- Container Model → Metric Types: stores metrics (evidence: `container/main.go`)
- Docker Metrics → Metric Types: streams
- Container Model → Metric Rows: updates widgets (evidence: `container/main.go`)
- Container Model → Container Logs: exposes logs (evidence: `container/main.go`)
- Docker Connector → Sort and Filter: sorts and filters (evidence: `connector/docker.go`)
- Sort and Filter → Configuration: reads preferences (evidence: `container/sort.go`)
- Compact Dashboard → Metric Rows: renders rows
- ctop Application → Single View: supports inspection view
- Single View → Log View: includes logs
- ctop Application → View Layout: lays out views (evidence: `main.go`)