# mightymoud/sidekick architecture

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

- Interactive diagram: https://gitdiagram.com/mightymoud/sidekick
- Repository: https://github.com/mightymoud/sidekick

## Overview

Sidekick is a CLI for provisioning a VPS and deploying Dockerfile-based applications to it. The main workflow is init (prepare the server and its Docker/Traefik environment), launch (build and transfer an app, then configure routing), and deploy (ship later versions); preview deployments add commit-specific environments that can be listed or removed. Local configuration, SSH access, and secret handling support these workflows. The README documents SSL, load balancing, and SOPS-backed secrets. Some command implementations are unsampled, so links to those subsystems are limited to documented behavior.

Main entry points: [`cmd/preview/preview.go`](https://github.com/mightymoud/sidekick/blob/main/cmd/preview/preview.go) (Preview deploy), [`cmd/root.go`](https://github.com/mightymoud/sidekick/blob/main/cmd/root.go) (Command router), [`cmd/launch/launch.go`](https://github.com/mightymoud/sidekick/blob/main/cmd/launch/launch.go) (Launch app), [`cmd/deploy/deploy.go`](https://github.com/mightymoud/sidekick/blob/main/cmd/deploy/deploy.go) (Deploy version)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI workflows"]
  node_entry["CLI entry<br/>[main.go]"]
  node_commands["Command router<br/>[root.go]"]
  node_render["Progress interface<br/>[tui.go]"]
end

subgraph group_deploy["Application deployment"]
  node_launch["Launch app<br/>[launch.go]"]
  node_deployapp["Deploy version<br/>[deploy.go]"]
  node_preview["Preview deploy<br/>[preview.go]"]
  node_previewlist["List previews<br/>[list.go]"]
  node_previewremove["Remove preview<br/>[remove.go]"]
  node_localdocker["Local Docker"]
end

subgraph group_infra["VPS and access"]
  node_initialize["VPS init<br/>[initialize.go]"]
  node_ssh["SSH access<br/>[auth.go]"]
  node_scripts["Remote setup scripts<br/>[scripts.go]"]
end

subgraph group_config["Configuration and secrets"]
  node_configcmd["Config commands"]
  node_appconfig["App configuration<br/>[config.go]"]
  node_globalconfig["CLI configuration<br/>[root.go]"]
  node_sopsage["SOPS and age"]
end

node_user(("CLI user"))
node_vps["Target VPS"]
node_dockerremote["Remote Docker"]
node_traefik["Traefik routing"]
node_domains["Domains and SSL"]

node_user -->|"runs command"| node_entry
node_entry -->|"executes"| node_commands
node_commands -->|"dispatches init"| node_initialize
node_commands -->|"dispatches launch"| node_launch
node_commands -->|"dispatches deploy"| node_deployapp
node_commands -->|"dispatches preview"| node_preview
node_commands -->|"dispatches config"| node_configcmd
node_preview -->|"dispatches list"| node_previewlist
node_preview -->|"dispatches remove"| node_previewremove
node_commands -->|"loads settings"| node_globalconfig
node_configcmd -->|"manages settings"| node_globalconfig
node_launch -->|"writes app config"| node_appconfig
node_deployapp -->|"reads app config"| node_appconfig
node_preview -->|"reads app config"| node_appconfig
node_previewlist -->|"reads previews"| node_appconfig
node_previewremove -->|"updates previews"| node_appconfig
node_initialize -->|"connects by SSH"| node_ssh
node_launch -->|"connects by SSH"| node_ssh
node_deployapp -->|"connects by SSH"| node_ssh
node_preview -->|"connects by SSH"| node_ssh
node_previewremove -->|"connects by SSH"| node_ssh
node_initialize -->|"runs setup scripts"| node_scripts
node_initialize -->|"provisions"| node_vps
node_launch -->|"builds image"| node_localdocker
node_deployapp -->|"builds image"| node_localdocker
node_preview -->|"builds image"| node_localdocker
node_launch -->|"transfers app"| node_vps
node_deployapp -->|"transfers release"| node_vps
node_preview -->|"transfers preview"| node_vps
node_previewremove -->|"removes preview"| node_vps
node_launch -.->|"encrypts secrets"| node_sopsage
node_deployapp -.->|"refreshes secrets"| node_sopsage
node_preview -.->|"encrypts secrets"| node_sopsage
node_vps -->|"runs containers"| node_dockerremote
node_vps -->|"hosts routing"| node_traefik
node_traefik -->|"serves HTTPS"| node_domains
node_initialize -->|"reports stages"| node_render
node_launch -->|"reports stages"| node_render
node_deployapp -->|"reports stages"| node_render
node_preview -->|"reports stages"| node_render

click node_entry "https://github.com/mightymoud/sidekick/blob/main/main.go"
click node_commands "https://github.com/mightymoud/sidekick/blob/main/cmd/root.go"
click node_initialize "https://github.com/mightymoud/sidekick/blob/main/cmd/initialize/initialize.go"
click node_launch "https://github.com/mightymoud/sidekick/blob/main/cmd/launch/launch.go"
click node_deployapp "https://github.com/mightymoud/sidekick/blob/main/cmd/deploy/deploy.go"
click node_preview "https://github.com/mightymoud/sidekick/blob/main/cmd/preview/preview.go"
click node_previewlist "https://github.com/mightymoud/sidekick/blob/main/cmd/preview/list/list.go"
click node_previewremove "https://github.com/mightymoud/sidekick/blob/main/cmd/preview/remove/remove.go"
click node_configcmd "https://github.com/mightymoud/sidekick/tree/main/cmd/config"
click node_appconfig "https://github.com/mightymoud/sidekick/blob/main/utils/config.go"
click node_globalconfig "https://github.com/mightymoud/sidekick/blob/main/cmd/root.go"
click node_ssh "https://github.com/mightymoud/sidekick/blob/main/utils/auth.go"
click node_scripts "https://github.com/mightymoud/sidekick/blob/main/utils/scripts.go"
click node_render "https://github.com/mightymoud/sidekick/blob/main/render/tui.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_entry,node_commands,node_render,node_user toneBlue
class node_launch,node_deployapp,node_preview,node_previewlist,node_previewremove,node_localdocker toneAmber
class node_initialize,node_ssh,node_scripts toneMint
class node_configcmd,node_appconfig,node_globalconfig,node_sopsage toneRose
class node_vps,node_dockerremote,node_traefik,node_domains toneIndigo
```

## Components

### CLI workflows

- [CLI entry](https://github.com/mightymoud/sidekick/blob/main/main.go): `main.go`
- [Command router](https://github.com/mightymoud/sidekick/blob/main/cmd/root.go): `cmd/root.go`
- [Progress interface](https://github.com/mightymoud/sidekick/blob/main/render/tui.go): `render/tui.go`

### Application deployment

- [Launch app](https://github.com/mightymoud/sidekick/blob/main/cmd/launch/launch.go): `cmd/launch/launch.go`
- [Deploy version](https://github.com/mightymoud/sidekick/blob/main/cmd/deploy/deploy.go): `cmd/deploy/deploy.go`
- [Preview deploy](https://github.com/mightymoud/sidekick/blob/main/cmd/preview/preview.go): `cmd/preview/preview.go`
- [List previews](https://github.com/mightymoud/sidekick/blob/main/cmd/preview/list/list.go): `cmd/preview/list/list.go`
- [Remove preview](https://github.com/mightymoud/sidekick/blob/main/cmd/preview/remove/remove.go): `cmd/preview/remove/remove.go`
- **Local Docker**

### VPS and access

- [VPS init](https://github.com/mightymoud/sidekick/blob/main/cmd/initialize/initialize.go): `cmd/initialize/initialize.go`
- [SSH access](https://github.com/mightymoud/sidekick/blob/main/utils/auth.go): `utils/auth.go`
- [Remote setup scripts](https://github.com/mightymoud/sidekick/blob/main/utils/scripts.go): `utils/scripts.go`

### Configuration and secrets

- [Config commands](https://github.com/mightymoud/sidekick/tree/main/cmd/config): `cmd/config`
- [App configuration](https://github.com/mightymoud/sidekick/blob/main/utils/config.go): `utils/config.go`
- [CLI configuration](https://github.com/mightymoud/sidekick/blob/main/cmd/root.go): `cmd/root.go`
- **SOPS and age**

### Other components

- **CLI user**
- **Target VPS**
- **Remote Docker**
- **Traefik routing**
- **Domains and SSL**

## Connections

- CLI user → CLI entry: runs command
- CLI entry → Command router: executes
- Command router → VPS init: dispatches init
- Command router → Launch app: dispatches launch
- Command router → Deploy version: dispatches deploy
- Command router → Preview deploy: dispatches preview
- Command router → Config commands: dispatches config
- Preview deploy → List previews: dispatches list
- Preview deploy → Remove preview: dispatches remove
- Command router → CLI configuration: loads settings
- Config commands → CLI configuration: manages settings
- Launch app → App configuration: writes app config
- Deploy version → App configuration: reads app config
- Preview deploy → App configuration: reads app config
- List previews → App configuration: reads previews
- Remove preview → App configuration: updates previews
- VPS init → SSH access: connects by SSH
- Launch app → SSH access: connects by SSH
- Deploy version → SSH access: connects by SSH
- Preview deploy → SSH access: connects by SSH
- Remove preview → SSH access: connects by SSH
- VPS init → Remote setup scripts: runs setup scripts
- VPS init → Target VPS: provisions
- Launch app → Local Docker: builds image
- Deploy version → Local Docker: builds image
- Preview deploy → Local Docker: builds image
- Launch app → Target VPS: transfers app
- Deploy version → Target VPS: transfers release
- Preview deploy → Target VPS: transfers preview
- Remove preview → Target VPS: removes preview
- Launch app → SOPS and age: encrypts secrets
- Deploy version → SOPS and age: refreshes secrets
- Preview deploy → SOPS and age: encrypts secrets
- Target VPS → Remote Docker: runs containers
- Target VPS → Traefik routing: hosts routing
- Traefik routing → Domains and SSL: serves HTTPS
- VPS init → Progress interface: reports stages
- Launch app → Progress interface: reports stages
- Deploy version → Progress interface: reports stages
- Preview deploy → Progress interface: reports stages