# finsys/dockhand architecture

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

- Interactive diagram: https://gitdiagram.com/finsys/dockhand
- Repository: https://github.com/finsys/dockhand

## Overview

Dockhand is a web-based Docker management application. Users connect to Docker environments, inspect and operate containers and Compose stacks, and receive live status, logs, and metrics; the README also documents Git deployments, backups, vulnerability scans, schedules, and authentication. The map emphasizes those product domains and the API/server layer. Several capabilities are documented but their route-to-service wiring was not sampled, so those links are marked unverified rather than presented as observed calls.

Main entry points: [`src/lib/components`](https://github.com/finsys/dockhand/tree/main/src/lib/components) (Management UI), [`src/lib/server/backups/backup-service.ts`](https://github.com/finsys/dockhand/blob/main/src/lib/server/backups/backup-service.ts) (Backup execution), [`src/lib/server/subprocess-manager.ts`](https://github.com/finsys/dockhand/blob/main/src/lib/server/subprocess-manager.ts) (Worker manager), [`src/routes/api/schedules/+server.ts`](https://github.com/finsys/dockhand/blob/main/src/routes/api/schedules/%2Bserver.ts) (Schedule API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_frontend["Management UI"]
end

subgraph group_api["API and access"]
  node_container_api["Container API<br/>[+server.ts]"]
  node_stack_api["Stack API<br/>[+server.ts]"]
  node_schedule_api["Schedule API<br/>[+server.ts]"]
  node_environment_api["Environment API<br/>[+server.ts]"]
end

subgraph group_operations["Docker operations"]
  node_docker["Docker operations<br/>[docker.ts]"]
  node_collector["Metrics collector<br/>[main.go]"]
  node_subprocess["Worker manager"]
  node_stacks["Stack management<br/>[stacks.ts]"]
  node_scanner["Image scanning<br/>[scanner.ts]"]
end

subgraph group_automation["Automation and backup"]
  node_scheduler["Scheduled tasks<br/>[index.ts]"]
  node_backup_api["Backup API<br/>[index.ts]"]
  node_backup_service["Backup execution<br/>[backup-service.ts]"]
  node_restore_service["Restore execution<br/>[restore-service.ts]"]
  node_backup_models["Backup models<br/>[models.ts]"]
end

subgraph group_platform["Persistence and integrations"]
  node_db["Database operations<br/>[db.ts]"]
  node_drizzle["Database adapter<br/>[drizzle.ts]"]
  node_database[("SQLite / PostgreSQL")]
  node_notification["Notification services<br/>[index.ts]"]
end

node_user(("Operator"))
node_docker_hosts["Docker hosts"]
node_restic["Restic"]

node_user -->|"operates"| node_frontend
node_frontend -.->|"manages containers"| node_container_api
node_frontend -.->|"orchestrates stacks"| node_stack_api
node_frontend -.->|"selects environments"| node_environment_api
node_frontend -.->|"configures schedules"| node_schedule_api
node_container_api -.->|"Docker operations"| node_docker
node_stack_api -.->|"manages stacks"| node_stacks
node_docker -->|"controls hosts"| node_docker_hosts
node_subprocess -->|"runs worker"| node_collector
node_collector -->|"collects events"| node_docker_hosts
node_subprocess -->|"records events"| node_db
node_schedule_api -->|"reads schedules"| node_db
node_schedule_api -->|"lists system schedules"| node_scheduler
node_scheduler -.->|"runs backups"| node_backup_service
node_backup_api -.->|"starts backup"| node_backup_service
node_backup_api -.->|"starts restore"| node_restore_service
node_backup_service -->|"uses result types"| node_backup_models
node_restore_service -->|"uses error types"| node_backup_models
node_backup_service -.->|"runs snapshots"| node_restic
node_restore_service -.->|"restores snapshots"| node_restic
node_db -->|"uses adapter"| node_drizzle
node_drizzle -.->|"persists records"| node_database
node_scanner -->|"scans images"| node_docker_hosts
node_subprocess -->|"sends notifications"| node_notification

click node_frontend "https://github.com/finsys/dockhand/tree/main/src/lib/components"
click node_container_api "https://github.com/finsys/dockhand/blob/main/src/routes/api/containers/%2Bserver.ts"
click node_stack_api "https://github.com/finsys/dockhand/blob/main/src/routes/api/stacks/%2Bserver.ts"
click node_schedule_api "https://github.com/finsys/dockhand/blob/main/src/routes/api/schedules/%2Bserver.ts"
click node_environment_api "https://github.com/finsys/dockhand/blob/main/src/routes/api/environments/%2Bserver.ts"
click node_docker "https://github.com/finsys/dockhand/blob/main/src/lib/server/docker.ts"
click node_collector "https://github.com/finsys/dockhand/blob/main/collector/main.go"
click node_subprocess "https://github.com/finsys/dockhand/blob/main/src/lib/server/subprocess-manager.ts"
click node_stacks "https://github.com/finsys/dockhand/blob/main/src/lib/server/stacks.ts"
click node_scanner "https://github.com/finsys/dockhand/blob/main/src/lib/server/scanner.ts"
click node_scheduler "https://github.com/finsys/dockhand/blob/main/src/lib/server/scheduler/index.ts"
click node_backup_api "https://github.com/finsys/dockhand/blob/main/src/lib/server/backups/index.ts"
click node_backup_service "https://github.com/finsys/dockhand/blob/main/src/lib/server/backups/backup-service.ts"
click node_restore_service "https://github.com/finsys/dockhand/blob/main/src/lib/server/backups/restore-service.ts"
click node_backup_models "https://github.com/finsys/dockhand/blob/main/src/lib/server/backups/models.ts"
click node_db "https://github.com/finsys/dockhand/blob/main/src/lib/server/db.ts"
click node_drizzle "https://github.com/finsys/dockhand/blob/main/src/lib/server/db/drizzle.ts"
click node_notification "https://github.com/finsys/dockhand/blob/main/src/lib/server/notifications/index.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_frontend toneBlue
class node_container_api,node_stack_api,node_schedule_api,node_environment_api toneAmber
class node_docker,node_collector,node_subprocess,node_stacks,node_scanner toneMint
class node_scheduler,node_backup_api,node_backup_service,node_restore_service,node_backup_models toneRose
class node_db,node_drizzle,node_database,node_notification,node_user,node_docker_hosts,node_restic toneIndigo
```

## Components

### User experience

- [Management UI](https://github.com/finsys/dockhand/tree/main/src/lib/components): `src/lib/components`

### API and access

- [Container API](https://github.com/finsys/dockhand/blob/main/src/routes/api/containers/%2Bserver.ts): `src/routes/api/containers/+server.ts`
- [Stack API](https://github.com/finsys/dockhand/blob/main/src/routes/api/stacks/%2Bserver.ts): `src/routes/api/stacks/+server.ts`
- [Schedule API](https://github.com/finsys/dockhand/blob/main/src/routes/api/schedules/%2Bserver.ts): `src/routes/api/schedules/+server.ts`
- [Environment API](https://github.com/finsys/dockhand/blob/main/src/routes/api/environments/%2Bserver.ts): `src/routes/api/environments/+server.ts`

### Docker operations

- [Docker operations](https://github.com/finsys/dockhand/blob/main/src/lib/server/docker.ts): `src/lib/server/docker.ts`
- [Metrics collector](https://github.com/finsys/dockhand/blob/main/collector/main.go): `collector/main.go`
- [Worker manager](https://github.com/finsys/dockhand/blob/main/src/lib/server/subprocess-manager.ts): `src/lib/server/subprocess-manager.ts`
- [Stack management](https://github.com/finsys/dockhand/blob/main/src/lib/server/stacks.ts): `src/lib/server/stacks.ts`
- [Image scanning](https://github.com/finsys/dockhand/blob/main/src/lib/server/scanner.ts): `src/lib/server/scanner.ts`

### Automation and backup

- [Scheduled tasks](https://github.com/finsys/dockhand/blob/main/src/lib/server/scheduler/index.ts): `src/lib/server/scheduler/index.ts`
- [Backup API](https://github.com/finsys/dockhand/blob/main/src/lib/server/backups/index.ts): `src/lib/server/backups/index.ts`
- [Backup execution](https://github.com/finsys/dockhand/blob/main/src/lib/server/backups/backup-service.ts): `src/lib/server/backups/backup-service.ts`
- [Restore execution](https://github.com/finsys/dockhand/blob/main/src/lib/server/backups/restore-service.ts): `src/lib/server/backups/restore-service.ts`
- [Backup models](https://github.com/finsys/dockhand/blob/main/src/lib/server/backups/models.ts): `src/lib/server/backups/models.ts`

### Persistence and integrations

- [Database operations](https://github.com/finsys/dockhand/blob/main/src/lib/server/db.ts): `src/lib/server/db.ts`
- [Database adapter](https://github.com/finsys/dockhand/blob/main/src/lib/server/db/drizzle.ts): `src/lib/server/db/drizzle.ts`
- **SQLite / PostgreSQL**
- [Notification services](https://github.com/finsys/dockhand/blob/main/src/lib/server/notifications/index.ts): `src/lib/server/notifications/index.ts`

### Other components

- **Operator**
- **Docker hosts**
- **Restic**

## Connections

- Operator → Management UI: operates
- Management UI → Container API: manages containers
- Management UI → Stack API: orchestrates stacks
- Management UI → Environment API: selects environments
- Management UI → Schedule API: configures schedules
- Container API → Docker operations: Docker operations
- Stack API → Stack management: manages stacks
- Docker operations → Docker hosts: controls hosts
- Worker manager → Metrics collector: runs worker (evidence: `src/lib/server/subprocess-manager.ts`)
- Metrics collector → Docker hosts: collects events
- Worker manager → Database operations: records events (evidence: `src/lib/server/subprocess-manager.ts`)
- Schedule API → Database operations: reads schedules (evidence: `src/routes/api/schedules/+server.ts`)
- Schedule API → Scheduled tasks: lists system schedules (evidence: `src/routes/api/schedules/+server.ts`)
- Scheduled tasks → Backup execution: runs backups
- Backup API → Backup execution: starts backup
- Backup API → Restore execution: starts restore
- Backup execution → Backup models: uses result types (evidence: `src/lib/server/backups/backup-service.ts`)
- Restore execution → Backup models: uses error types (evidence: `src/lib/server/backups/restore-service.ts`)
- Backup execution → Restic: runs snapshots
- Restore execution → Restic: restores snapshots
- Database operations → Database adapter: uses adapter (evidence: `src/lib/server/db.ts`)
- Database adapter → SQLite / PostgreSQL: persists records
- Image scanning → Docker hosts: scans images
- Worker manager → Notification services: sends notifications (evidence: `src/lib/server/subprocess-manager.ts`)
