# nishantverse/topdock architecture

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

- Interactive diagram: https://gitdiagram.com/nishantverse/topdock
- Repository: https://github.com/nishantverse/topdock

## Overview

1. **Repository shape**
   - This is a small, mostly single-module Python CLI application.
   - The core runtime appears to live in `topdock.py`, with packaging metadata in `pyproject.toml`.
   - `install.sh` and `install.ps1` provide convenience installation paths for Unix-like shells and Windows PowerShell.

2. **Primary purpose**
   - TopDock is a terminal dashboard for live Docker container metrics.
   - It presents per-container CPU, memory, network, and block I/O statistics in real time, and can also emit one-shot snapshot output.

3. **Runtime boundary**
   - The app runs locally on the user’s machine and talks to a Docker daemon.
   - It can connect either to the local Docker socket or to a remote Docker host via the `--host` option, so the Docker daemon is the main external dependency and data source.

4. **Core data flow**
   - Docker container statistics are collected from the daemon.
   - Those stats are transformed into a tabular view model for the terminal.
   - The view model is then rendered into a live dashboard, or serialized into snapshot output such as JSON/CSV.

5. **Main functional subsystems**
   - **CLI/command parsing**: handles flags such as `--sort`, `--refresh`, `--alert`, `--snapshot`, `--format`, `--host`, and `--version`.
   - **Docker metrics acquisition**: fetches live container stats from Docker.
   - **Ranking/sorting**: orders containers by CPU, memory, network, or block I/O.
   - **Terminal dashboard UI**: displays a continuously updating table and responds to keyboard input.
   - **Export/output path**: supports snapshot mode and export of CSV/JSON.
   - **Alert handling**: tracks threshold-based alerting, with a command to clear alerts.

6. **Interactive control boundary**
   - The live dashboard is event-driven through keyboard shortcuts.
   - Navigation keys scroll the table; letter keys change sort mode, export data, clear alerts, or quit.
   - This makes the UI stateful: the same underlying metric set can be viewed with different sort order and scroll position.

7. **Modes of operation**
   - **Live mode**: continuous refresh, interactive terminal UI, default behavior.
   - **Snapshot mode**: one-shot capture intended for machine-readable output.
   - These are distinct output paths, which is important for an architecture diagram because rendering and serialization are alternate sinks from the same metrics source.

8. **Output and integration points**
   - Human-facing output is the terminal dashboard.
   - Machine-facing output is JSON and CSV export/snapshot data.
   - There are no signs of a database, web server, message queue, or background service; the application seems self-contained aside from Docker access.

9. **Packaging and distribution**
   - `pyproject.toml` indicates standard Python packaging, likely exposing a console script entrypoint.
   - The install scripts suggest the repo supports direct local installation in addition to package-manager-based installation via `pipx` or `pip`.

10. **Platform considerations**
   - The README claims Linux, macOS, and Windows support.
   - That implies the architecture is designed around cross-platform Python code and a terminal interface rather than OS-specific GUI components.
   - Remote Docker host support also suggests the Docker communication layer is configurable, not hardwired to a local socket.

11. **Likely diagram framing**
   - A good architecture diagram would place the **user terminal** at the center, with an **interactive dashboard UI** consuming data from a **Docker daemon**.
   - Beside it, show an alternate **snapshot/export path** for JSON/CSV.
   - Surround those with a thin **CLI/configuration layer** and **packaging/install scripts** as the entry and distribution boundary.

12. **What is notably absent**
   - No evidence of backend services, persistence, authentication, or multi-process coordination.
   - No signs of separate frontend/backend separation; this is a single-process CLI tool with a clear external dependency on Docker.

Main entry points: [`topdock.py`](https://github.com/nishantverse/topdock/blob/main/topdock.py) (Core CLI), [`pyproject.toml`](https://github.com/nishantverse/topdock/blob/main/pyproject.toml) (pyproject.toml), [`install.sh`](https://github.com/nishantverse/topdock/blob/main/install.sh) (install.sh), [`install.ps1`](https://github.com/nishantverse/topdock/blob/main/install.ps1) (install.ps1)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_user_terminal(("Terminal<br/>user interface"))
  node_docker_daemon[("Docker Daemon<br/>external service")]
  node_core_cli["Core CLI<br/>python module<br/>[topdock.py]"]
  node_cli_parser["CLI Parser<br/>argument parsing"]
  node_metric_fetcher["Metrics Fetcher<br/>docker client"]
  node_sort_ranker["Sorter<br/>ranking logic"]
  node_dashboard_ui["Dashboard UI<br/>terminal table"]
  node_keyboard_input["Keyboard Input<br/>event loop"]
  node_snapshot_export["Snapshot Export<br/>serializer"]
  node_alert_manager["Alerts<br/>threshold logic"]
end

subgraph group_distribution["Distribution"]
  node_pyproject["pyproject.toml<br/>packaging metadata<br/>[pyproject.toml]"]
  node_install_sh["install.sh<br/>unix installer<br/>[install.sh]"]
  node_install_ps1["install.ps1<br/>windows installer<br/>[install.ps1]"]
end

node_user_terminal -->|"launches"| node_core_cli
node_pyproject -->|"exposes"| node_core_cli
node_install_sh -->|"installs"| node_pyproject
node_install_ps1 -->|"installs"| node_pyproject
node_core_cli -->|"parses"| node_cli_parser
node_cli_parser -->|"configures"| node_metric_fetcher
node_metric_fetcher -->|"queries"| node_docker_daemon
node_metric_fetcher -->|"provides"| node_sort_ranker
node_sort_ranker -->|"orders"| node_dashboard_ui
node_sort_ranker -->|"orders"| node_snapshot_export
node_dashboard_ui -->|"renders"| node_user_terminal
node_keyboard_input -->|"controls"| node_dashboard_ui
node_dashboard_ui -->|"reads"| node_keyboard_input
node_core_cli -->|"runs"| node_dashboard_ui
node_core_cli -->|"runs"| node_snapshot_export
node_metric_fetcher -->|"feeds"| node_alert_manager
node_alert_manager -->|"annotates"| node_dashboard_ui
node_alert_manager -->|"annotates"| node_snapshot_export

click node_core_cli "https://github.com/nishantverse/topdock/blob/main/topdock.py"
click node_pyproject "https://github.com/nishantverse/topdock/blob/main/pyproject.toml"
click node_install_sh "https://github.com/nishantverse/topdock/blob/main/install.sh"
click node_install_ps1 "https://github.com/nishantverse/topdock/blob/main/install.ps1"

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_user_terminal,node_docker_daemon,node_core_cli,node_cli_parser,node_metric_fetcher,node_sort_ranker,node_dashboard_ui,node_keyboard_input,node_snapshot_export,node_alert_manager toneBlue
class node_pyproject,node_install_sh,node_install_ps1 toneAmber
```

## Components

### Runtime

Interactive CLI execution and Docker data flow

- **Terminal**: user interface · Where the dashboard is viewed and controlled
- **Docker Daemon**: external service · Source of container metrics via local socket or remote host
- [Core CLI](https://github.com/nishantverse/topdock/blob/main/topdock.py): python module · Main application module coordinating runtime behavior · `topdock.py`
- **CLI Parser**: argument parsing · Handles flags, modes, sorting, refresh, host, and version
- **Metrics Fetcher**: docker client · Collects live CPU, memory, network, and block I/O stats
- **Sorter**: ranking logic · Orders containers by the selected metric
- **Dashboard UI**: terminal table · Renders the live updating container view
- **Keyboard Input**: event loop · Processes navigation and command shortcuts
- **Snapshot Export**: serializer · Produces one-shot JSON or CSV output
- **Alerts**: threshold logic · Tracks and clears threshold-based alerts

### Distribution

Packaging and install entry points

- [pyproject.toml](https://github.com/nishantverse/topdock/blob/main/pyproject.toml): packaging metadata · Defines project metadata and console entrypoint · `pyproject.toml`
- [install.sh](https://github.com/nishantverse/topdock/blob/main/install.sh): unix installer · Convenience install path for Unix-like shells · `install.sh`
- [install.ps1](https://github.com/nishantverse/topdock/blob/main/install.ps1): windows installer · Convenience install path for PowerShell · `install.ps1`

## Connections

- Terminal → Core CLI: launches · User starts the CLI in the terminal
- pyproject.toml → Core CLI: exposes · Packaging metadata points to the runnable entrypoint
- install.sh → pyproject.toml: installs · Unix helper installs the packaged CLI
- install.ps1 → pyproject.toml: installs · PowerShell helper installs the packaged CLI
- Core CLI → CLI Parser: parses · Reads command-line flags and mode selection
- CLI Parser → Metrics Fetcher: configures · Passes host, refresh, and snapshot settings
- Metrics Fetcher → Docker Daemon: queries · Fetches live container statistics from Docker
- Metrics Fetcher → Sorter: provides · Hands collected metrics to the ranking layer
- Sorter → Dashboard UI: orders · Supplies containers in the chosen sort order
- Sorter → Snapshot Export: orders · Formats ranked metrics for machine output
- Dashboard UI → Terminal: renders · Displays the live table in the terminal
- Keyboard Input → Dashboard UI: controls · Scrolls, changes sort, exports, clears alerts, and quits
- Dashboard UI → Keyboard Input: reads · Consumes interactive key events
- Core CLI → Dashboard UI: runs · Starts live dashboard mode
- Core CLI → Snapshot Export: runs · Starts snapshot mode for one-shot output
- Metrics Fetcher → Alerts: feeds · Threshold checks operate on incoming stats
- Alerts → Dashboard UI: annotates · Alerts are surfaced in the live view
- Alerts → Snapshot Export: annotates · Alert state can be included in exported output