# msudipta888/dockview-dashboard architecture

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

- Interactive diagram: https://gitdiagram.com/msudipta888/dockview-dashboard
- Repository: https://github.com/msudipta888/dockview-dashboard

## Overview

#### Purpose and Launch Model
DockView is a local Docker Engine management and monitoring dashboard. It is distributed as an npm CLI that verifies/uses the local Docker daemon, launches a Python backend and Next.js frontend, then opens the browser. Primary entry points: `bin/cli.js`, `backend/app/main.py`, and `frontend/src/app/layout.tsx`.

#### Process Orchestration Boundary
The Node CLI is the product launcher and owns process-level concerns: command-line ports, development mode, browser opening, and starting the two servers. The backend and frontend remain independently runnable services behind localhost ports. Paths: `bin/cli.js`, `package.json`, `backend/Dockerfile`.

#### Backend API and Docker Adapter
FastAPI exposes REST operations for Docker resources and summary data. Docker SDK interaction is centralized behind a client wrapper, insulating route handlers from Docker Engine access details. This is the trust boundary to the local Docker socket/daemon: dashboard requests become Docker lifecycle, inspection, and deletion calls. Paths: `backend/app/main.py`, `backend/app/docker_client.py`, `backend/app/routes/containers.py`.

#### Resource Management Stages
REST route modules divide management by Docker resource: containers (list/start/stop/restart/remove), images, volumes, builds, and aggregate system summary. These routes are the request/response path consumed by the frontend API client. Paths: `backend/app/routes/images.py`, `backend/app/routes/volumes.py`, `backend/app/routes/builds.py`, `backend/app/routes/summary.py`.

#### Real-Time Streaming Plane
Socket handlers provide persistent streams distinct from REST: Docker daemon events, container stdout/stderr logs, per-container stats, and live build output. The backend bridges Docker’s streaming interfaces into Socket.IO/WebSocket-facing events; clients subscribe through a dedicated frontend WebSocket layer. Paths: `backend/app/sockets/events.py`, `backend/app/sockets/logs.py`, `backend/app/sockets/stats.py`, `frontend/src/lib/api/ws.ts`.

#### Frontend Dashboard Composition
The Next.js App Router frontend renders separate operational pages for overview, containers, images, volumes, builds, logs, and event/error feed. Shared shell components provide navigation and command-palette navigation, while domain hooks fetch resource data. Paths: `frontend/src/app/page.tsx`, `frontend/src/app/containers/page.tsx`, `frontend/src/app/builds/page.tsx`, `frontend/src/components/layout/sidebar.tsx`.

#### Client State and Service Integration
Frontend REST calls are centralized in an API client; TypeScript types define the frontend/backend data contract. Zustand-style stores hold daemon/dashboard state, supporting cross-page status and live updates. Material runtime dependencies are Node.js 18+, Python 3.9+, FastAPI/Uvicorn, Next.js, Socket.IO, and the Docker Python SDK; the sole external operational dependency is an accessible local Docker Engine. Paths: `frontend/src/lib/api/client.ts`, `frontend/src/lib/types/index.ts`, `frontend/src/store/use-daemon-store.ts`, `backend/requirements.txt`.

Main entry points: [`backend/app/main.py`](https://github.com/msudipta888/dockview-dashboard/blob/main/backend/app/main.py) (FastAPI application), [`frontend/src/app/layout.tsx`](https://github.com/msudipta888/dockview-dashboard/blob/main/frontend/src/app/layout.tsx) (App shell), [`backend/app/docker_client.py`](https://github.com/msudipta888/dockview-dashboard/blob/main/backend/app/docker_client.py) (Docker client wrapper), [`frontend/src/lib/api/client.ts`](https://github.com/msudipta888/dockview-dashboard/blob/main/frontend/src/lib/api/client.ts) (REST API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_launcher["Launch"]
  node_cli{{"DockView CLI<br/>npm launcher<br/>[cli.js]"}}
  node_package["Package runtime<br/>npm package<br/>[package.json]"]
end

subgraph group_backend["Backend service"]
  node_backend_main["FastAPI application<br/>API server<br/>[main.py]"]
  node_docker_client["Docker client wrapper<br/>Docker adapter<br/>[docker_client.py]"]
  node_container_routes["Container routes<br/>REST routes<br/>[containers.py]"]
  node_resource_routes["Resource routes<br/>REST routes<br/>[images.py]"]
  node_event_socket["Event stream<br/>socket handler<br/>[events.py]"]
  node_log_socket["Log stream<br/>socket handler<br/>[logs.py]"]
  node_stats_socket["Stats stream<br/>socket handler<br/>[stats.py]"]
end

subgraph group_frontend["Frontend dashboard"]
  node_app_shell["App shell<br/>Next.js layout<br/>[layout.tsx]"]
  node_dashboard_pages["Operational pages<br/>Next.js pages<br/>[page.tsx]"]
  node_container_page["Containers page<br/>Next.js page<br/>[page.tsx]"]
  node_builds_page["Builds page<br/>Next.js page<br/>[page.tsx]"]
  node_sidebar["Sidebar navigation<br/>shared component<br/>[sidebar.tsx]"]
  node_api_client["REST API client<br/>frontend service<br/>[client.ts]"]
  node_ws_client["WebSocket client<br/>frontend service<br/>[ws.ts]"]
  node_data_contract["Data contracts<br/>TypeScript types<br/>[index.ts]"]
  node_daemon_store[("Daemon state store<br/>client state")]
end

subgraph group_docker["Local Docker Engine"]
  node_docker_engine[("Docker daemon<br/>external dependency")]
end

node_package -->|"defines CLI runtime"| node_cli
node_cli -->|"starts"| node_backend_main
node_cli -->|"starts frontend"| node_app_shell
node_backend_main -->|"serves REST"| node_container_routes
node_backend_main -->|"serves REST"| node_resource_routes
node_backend_main -->|"hosts stream"| node_event_socket
node_backend_main -->|"hosts stream"| node_log_socket
node_backend_main -->|"hosts stream"| node_stats_socket
node_container_routes -->|"Docker operations"| node_docker_client
node_resource_routes -->|"Docker operations"| node_docker_client
node_event_socket -->|"daemon events"| node_docker_client
node_log_socket -->|"container logs"| node_docker_client
node_stats_socket -->|"container stats"| node_docker_client
node_docker_client -->|"Docker SDK/socket"| node_docker_engine
node_app_shell -->|"renders"| node_sidebar
node_app_shell -->|"hosts"| node_dashboard_pages
node_app_shell -->|"hosts"| node_container_page
node_app_shell -->|"hosts"| node_builds_page
node_dashboard_pages -->|"fetches data"| node_api_client
node_container_page -->|"manages containers"| node_api_client
node_builds_page -->|"manages builds"| node_api_client
node_api_client -->|"REST requests"| node_backend_main
node_ws_client -->|"stream subscriptions"| node_backend_main
node_ws_client -->|"live updates"| node_daemon_store
node_api_client -.->|"uses payload types"| node_data_contract
node_daemon_store -->|"dashboard state"| node_app_shell

click node_cli "https://github.com/msudipta888/dockview-dashboard/blob/main/bin/cli.js"
click node_package "https://github.com/msudipta888/dockview-dashboard/blob/main/package.json"
click node_backend_main "https://github.com/msudipta888/dockview-dashboard/blob/main/backend/app/main.py"
click node_docker_client "https://github.com/msudipta888/dockview-dashboard/blob/main/backend/app/docker_client.py"
click node_container_routes "https://github.com/msudipta888/dockview-dashboard/blob/main/backend/app/routes/containers.py"
click node_resource_routes "https://github.com/msudipta888/dockview-dashboard/blob/main/backend/app/routes/images.py"
click node_event_socket "https://github.com/msudipta888/dockview-dashboard/blob/main/backend/app/sockets/events.py"
click node_log_socket "https://github.com/msudipta888/dockview-dashboard/blob/main/backend/app/sockets/logs.py"
click node_stats_socket "https://github.com/msudipta888/dockview-dashboard/blob/main/backend/app/sockets/stats.py"
click node_app_shell "https://github.com/msudipta888/dockview-dashboard/blob/main/frontend/src/app/layout.tsx"
click node_dashboard_pages "https://github.com/msudipta888/dockview-dashboard/blob/main/frontend/src/app/page.tsx"
click node_container_page "https://github.com/msudipta888/dockview-dashboard/blob/main/frontend/src/app/containers/page.tsx"
click node_builds_page "https://github.com/msudipta888/dockview-dashboard/blob/main/frontend/src/app/builds/page.tsx"
click node_sidebar "https://github.com/msudipta888/dockview-dashboard/blob/main/frontend/src/components/layout/sidebar.tsx"
click node_api_client "https://github.com/msudipta888/dockview-dashboard/blob/main/frontend/src/lib/api/client.ts"
click node_ws_client "https://github.com/msudipta888/dockview-dashboard/blob/main/frontend/src/lib/api/ws.ts"
click node_data_contract "https://github.com/msudipta888/dockview-dashboard/blob/main/frontend/src/lib/types/index.ts"
click node_daemon_store "https://github.com/msudipta888/dockview-dashboard/blob/main/frontend/src/store/use-daemon-store.ts"

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_cli,node_package toneBlue
class node_backend_main,node_docker_client,node_container_routes,node_resource_routes,node_event_socket,node_log_socket,node_stats_socket toneAmber
class node_app_shell,node_dashboard_pages,node_container_page,node_builds_page,node_sidebar,node_api_client,node_ws_client,node_data_contract,node_daemon_store toneMint
class node_docker_engine toneRose
```

## Components

### Launch

- [DockView CLI](https://github.com/msudipta888/dockview-dashboard/blob/main/bin/cli.js): npm launcher · Starts local services and opens the browser. · `bin/cli.js`
- [Package runtime](https://github.com/msudipta888/dockview-dashboard/blob/main/package.json): npm package · `package.json`

### Backend service

- [FastAPI application](https://github.com/msudipta888/dockview-dashboard/blob/main/backend/app/main.py): API server · REST and streaming service behind localhost. · `backend/app/main.py`
- [Docker client wrapper](https://github.com/msudipta888/dockview-dashboard/blob/main/backend/app/docker_client.py): Docker adapter · Centralizes Docker SDK access. · `backend/app/docker_client.py`
- [Container routes](https://github.com/msudipta888/dockview-dashboard/blob/main/backend/app/routes/containers.py): REST routes · Lifecycle and inspection operations. · `backend/app/routes/containers.py`
- [Resource routes](https://github.com/msudipta888/dockview-dashboard/blob/main/backend/app/routes/images.py): REST routes · Images, volumes, builds, and summary endpoints. · `backend/app/routes/images.py`
- [Event stream](https://github.com/msudipta888/dockview-dashboard/blob/main/backend/app/sockets/events.py): socket handler · Bridges Docker daemon events. · `backend/app/sockets/events.py`
- [Log stream](https://github.com/msudipta888/dockview-dashboard/blob/main/backend/app/sockets/logs.py): socket handler · Bridges container stdout and stderr. · `backend/app/sockets/logs.py`
- [Stats stream](https://github.com/msudipta888/dockview-dashboard/blob/main/backend/app/sockets/stats.py): socket handler · Bridges per-container metrics. · `backend/app/sockets/stats.py`

### Frontend dashboard

- [App shell](https://github.com/msudipta888/dockview-dashboard/blob/main/frontend/src/app/layout.tsx): Next.js layout · Shared dashboard shell and navigation. · `frontend/src/app/layout.tsx`
- [Operational pages](https://github.com/msudipta888/dockview-dashboard/blob/main/frontend/src/app/page.tsx): Next.js pages · Overview and Docker resource views. · `frontend/src/app/page.tsx`
- [Containers page](https://github.com/msudipta888/dockview-dashboard/blob/main/frontend/src/app/containers/page.tsx): Next.js page · `frontend/src/app/containers/page.tsx`
- [Builds page](https://github.com/msudipta888/dockview-dashboard/blob/main/frontend/src/app/builds/page.tsx): Next.js page · `frontend/src/app/builds/page.tsx`
- [Sidebar navigation](https://github.com/msudipta888/dockview-dashboard/blob/main/frontend/src/components/layout/sidebar.tsx): shared component · `frontend/src/components/layout/sidebar.tsx`
- [REST API client](https://github.com/msudipta888/dockview-dashboard/blob/main/frontend/src/lib/api/client.ts): frontend service · Centralizes backend REST calls. · `frontend/src/lib/api/client.ts`
- [WebSocket client](https://github.com/msudipta888/dockview-dashboard/blob/main/frontend/src/lib/api/ws.ts): frontend service · Subscribes to live backend streams. · `frontend/src/lib/api/ws.ts`
- [Data contracts](https://github.com/msudipta888/dockview-dashboard/blob/main/frontend/src/lib/types/index.ts): TypeScript types · Frontend/backend payload definitions. · `frontend/src/lib/types/index.ts`
- [Daemon state store](https://github.com/msudipta888/dockview-dashboard/blob/main/frontend/src/store/use-daemon-store.ts): client state · Cross-page daemon status and live state. · `frontend/src/store/use-daemon-store.ts`

### Local Docker Engine

- **Docker daemon**: external dependency · Local Docker Engine and socket.

## Connections

- Package runtime → DockView CLI: defines CLI runtime
- DockView CLI → FastAPI application: starts
- DockView CLI → App shell: starts frontend
- FastAPI application → Container routes: serves REST
- FastAPI application → Resource routes: serves REST
- FastAPI application → Event stream: hosts stream
- FastAPI application → Log stream: hosts stream
- FastAPI application → Stats stream: hosts stream
- Container routes → Docker client wrapper: Docker operations
- Resource routes → Docker client wrapper: Docker operations
- Event stream → Docker client wrapper: daemon events
- Log stream → Docker client wrapper: container logs
- Stats stream → Docker client wrapper: container stats
- Docker client wrapper → Docker daemon: Docker SDK/socket
- App shell → Sidebar navigation: renders
- App shell → Operational pages: hosts
- App shell → Containers page: hosts
- App shell → Builds page: hosts
- Operational pages → REST API client: fetches data
- Containers page → REST API client: manages containers
- Builds page → REST API client: manages builds
- REST API client → FastAPI application: REST requests
- WebSocket client → FastAPI application: stream subscriptions
- WebSocket client → Daemon state store: live updates
- REST API client → Data contracts: uses payload types
- Daemon state store → App shell: dashboard state