# littledrongo/deployctl architecture

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

- Interactive diagram: https://gitdiagram.com/littledrongo/deployctl
- Repository: https://github.com/littledrongo/deployctl

## Overview

deployctl is a Go command-line tool that builds applications locally, deploys them to configured servers over SSH/SCP, and manages Docker containers. The main workflow is CLI → project/config resolution → cross-platform build → artifact transfer and transactional remote launch, followed by readiness checks and rollback on failure. Separate branches initialize projects, inspect server prerequisites, observe/manage containers, create releases, clean artifacts, and provide Bash completion. Several implementation files are unsampled; edges there are limited to documented behavior and indexed references.

Main entry points: [`internal/cli/cli.go`](https://github.com/littledrongo/deployctl/blob/main/internal/cli/cli.go) (Command dispatch), [`internal/cli/remote.go`](https://github.com/littledrongo/deployctl/blob/main/internal/cli/remote.go) (Remote commands), [`internal/deploy/ssh.go`](https://github.com/littledrongo/deployctl/blob/main/internal/deploy/ssh.go) (SSH and SCP), [`internal/deploy/deploy.go`](https://github.com/littledrongo/deployctl/blob/main/internal/deploy/deploy.go) (Deployment transaction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Command interface"]
  node_cli["Command dispatch<br/>[cli.go]"]
  node_remote_commands["Remote commands<br/>[remote.go]"]
  node_completion["Bash completion<br/>[completion.go]"]
end

subgraph group_project["Project preparation"]
  node_setup["Project initialization<br/>[setup.go]"]
  node_config["Configuration<br/>[config.go]"]
  node_project_root["Module discovery<br/>[project.go]"]
end

subgraph group_build["Build and metadata"]
  node_build_run["Cross-platform build<br/>[build.go]"]
  node_build_artifact["Artifact handling<br/>[artifact.go]"]
  node_gitmeta["Git metadata<br/>[git.go]"]
  node_release["Git release<br/>[release.go]"]
  node_clean["Artifact cleanup<br/>[clean.go]"]
end

subgraph group_remote["Remote operations"]
  node_deploy_transaction["Deployment transaction<br/>[deploy.go]"]
  node_remote_scripts["Remote Docker scripts<br/>[scripts.go]"]
  node_ssh_transport["SSH and SCP<br/>[ssh.go]"]
  node_doctor["Server checks<br/>[doctor.go]"]
  node_observe["Status and logs<br/>[observe.go]"]
  node_manage["Container controls<br/>[manage.go]"]
  node_images["Image versioning<br/>[images.go]"]
  node_redaction["Diagnostic redaction<br/>[redact.go]"]
  node_terminal["Remote output<br/>[remote.go]"]
end

node_developer(("Developer"))
node_server(("Deployment server"))

node_developer -->|"runs commands"| node_cli
node_cli -->|"dispatches remote"| node_remote_commands
node_cli -->|"initializes project"| node_setup
node_cli -->|"runs build"| node_build_run
node_cli -->|"creates release"| node_release
node_cli -->|"cleans artifacts"| node_clean
node_cli -->|"dispatches completion"| node_completion
node_cli -->|"checks config"| node_config
node_cli -->|"reads Git metadata"| node_gitmeta
node_setup -->|"generates config"| node_config
node_remote_commands -->|"finds module"| node_project_root
node_remote_commands -->|"loads targets"| node_config
node_remote_commands -->|"builds target"| node_build_run
node_remote_commands -->|"starts deployment"| node_deploy_transaction
node_remote_commands -->|"checks target"| node_doctor
node_remote_commands -->|"queries status/logs"| node_observe
node_remote_commands -->|"manages container"| node_manage
node_build_run -.->|"writes artifact"| node_build_artifact
node_build_run -.->|"uses repository metadata"| node_gitmeta
node_remote_commands -.->|"versions image"| node_images
node_deploy_transaction -->|"uploads and executes"| node_ssh_transport
node_deploy_transaction -.->|"runs transaction script"| node_remote_scripts
node_deploy_transaction -->|"deploys remotely"| node_server
node_doctor -->|"runs remote checks"| node_ssh_transport
node_observe -->|"requests remote state"| node_ssh_transport
node_manage -.->|"runs container action"| node_ssh_transport
node_ssh_transport -->|"redacts diagnostics"| node_redaction
node_ssh_transport -->|"formats remote output"| node_terminal
node_clean -.->|"removes artifact directory"| node_build_artifact
node_completion -->|"loads target names"| node_config
node_completion -->|"finds module"| node_project_root

click node_cli "https://github.com/littledrongo/deployctl/blob/main/internal/cli/cli.go"
click node_remote_commands "https://github.com/littledrongo/deployctl/blob/main/internal/cli/remote.go"
click node_completion "https://github.com/littledrongo/deployctl/blob/main/internal/completion/completion.go"
click node_setup "https://github.com/littledrongo/deployctl/blob/main/internal/setup/setup.go"
click node_config "https://github.com/littledrongo/deployctl/blob/main/internal/config/config.go"
click node_project_root "https://github.com/littledrongo/deployctl/blob/main/internal/project/project.go"
click node_build_run "https://github.com/littledrongo/deployctl/blob/main/internal/build/build.go"
click node_build_artifact "https://github.com/littledrongo/deployctl/blob/main/internal/build/artifact.go"
click node_gitmeta "https://github.com/littledrongo/deployctl/blob/main/internal/gitmeta/git.go"
click node_release "https://github.com/littledrongo/deployctl/blob/main/internal/release/release.go"
click node_clean "https://github.com/littledrongo/deployctl/blob/main/internal/clean/clean.go"
click node_deploy_transaction "https://github.com/littledrongo/deployctl/blob/main/internal/deploy/deploy.go"
click node_remote_scripts "https://github.com/littledrongo/deployctl/blob/main/internal/deploy/scripts.go"
click node_ssh_transport "https://github.com/littledrongo/deployctl/blob/main/internal/deploy/ssh.go"
click node_doctor "https://github.com/littledrongo/deployctl/blob/main/internal/deploy/doctor.go"
click node_observe "https://github.com/littledrongo/deployctl/blob/main/internal/deploy/observe.go"
click node_manage "https://github.com/littledrongo/deployctl/blob/main/internal/deploy/manage.go"
click node_images "https://github.com/littledrongo/deployctl/blob/main/internal/deploy/images.go"
click node_redaction "https://github.com/littledrongo/deployctl/blob/main/internal/deploy/redact.go"
click node_terminal "https://github.com/littledrongo/deployctl/blob/main/internal/terminal/remote.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_cli,node_remote_commands,node_completion toneBlue
class node_setup,node_config,node_project_root toneAmber
class node_build_run,node_build_artifact,node_gitmeta,node_release,node_clean,node_server toneMint
class node_deploy_transaction,node_remote_scripts,node_ssh_transport,node_doctor,node_observe,node_manage,node_images,node_redaction,node_terminal toneRose
class node_developer toneIndigo
```

## Components

### Command interface

- [Command dispatch](https://github.com/littledrongo/deployctl/blob/main/internal/cli/cli.go): `internal/cli/cli.go`
- [Remote commands](https://github.com/littledrongo/deployctl/blob/main/internal/cli/remote.go): `internal/cli/remote.go`
- [Bash completion](https://github.com/littledrongo/deployctl/blob/main/internal/completion/completion.go): `internal/completion/completion.go`

### Project preparation

- [Project initialization](https://github.com/littledrongo/deployctl/blob/main/internal/setup/setup.go): `internal/setup/setup.go`
- [Configuration](https://github.com/littledrongo/deployctl/blob/main/internal/config/config.go): `internal/config/config.go`
- [Module discovery](https://github.com/littledrongo/deployctl/blob/main/internal/project/project.go): `internal/project/project.go`

### Build and metadata

- [Cross-platform build](https://github.com/littledrongo/deployctl/blob/main/internal/build/build.go): `internal/build/build.go`
- [Artifact handling](https://github.com/littledrongo/deployctl/blob/main/internal/build/artifact.go): `internal/build/artifact.go`
- [Git metadata](https://github.com/littledrongo/deployctl/blob/main/internal/gitmeta/git.go): `internal/gitmeta/git.go`
- [Git release](https://github.com/littledrongo/deployctl/blob/main/internal/release/release.go): `internal/release/release.go`
- [Artifact cleanup](https://github.com/littledrongo/deployctl/blob/main/internal/clean/clean.go): `internal/clean/clean.go`

### Remote operations

- [Deployment transaction](https://github.com/littledrongo/deployctl/blob/main/internal/deploy/deploy.go): `internal/deploy/deploy.go`
- [Remote Docker scripts](https://github.com/littledrongo/deployctl/blob/main/internal/deploy/scripts.go): `internal/deploy/scripts.go`
- [SSH and SCP](https://github.com/littledrongo/deployctl/blob/main/internal/deploy/ssh.go): `internal/deploy/ssh.go`
- [Server checks](https://github.com/littledrongo/deployctl/blob/main/internal/deploy/doctor.go): `internal/deploy/doctor.go`
- [Status and logs](https://github.com/littledrongo/deployctl/blob/main/internal/deploy/observe.go): `internal/deploy/observe.go`
- [Container controls](https://github.com/littledrongo/deployctl/blob/main/internal/deploy/manage.go): `internal/deploy/manage.go`
- [Image versioning](https://github.com/littledrongo/deployctl/blob/main/internal/deploy/images.go): `internal/deploy/images.go`
- [Diagnostic redaction](https://github.com/littledrongo/deployctl/blob/main/internal/deploy/redact.go): `internal/deploy/redact.go`
- [Remote output](https://github.com/littledrongo/deployctl/blob/main/internal/terminal/remote.go): `internal/terminal/remote.go`

### Other components

- **Developer**
- **Deployment server**

## Connections

- Developer → Command dispatch: runs commands (evidence: `README.md`)
- Command dispatch → Remote commands: dispatches remote (evidence: `internal/cli/cli.go`)
- Command dispatch → Project initialization: initializes project (evidence: `internal/cli/cli.go`)
- Command dispatch → Cross-platform build: runs build (evidence: `internal/cli/cli.go`)
- Command dispatch → Git release: creates release (evidence: `internal/cli/cli.go`)
- Command dispatch → Artifact cleanup: cleans artifacts (evidence: `internal/cli/cli.go`)
- Command dispatch → Bash completion: dispatches completion (evidence: `internal/cli/cli.go`)
- Command dispatch → Configuration: checks config (evidence: `internal/cli/cli.go`)
- Command dispatch → Git metadata: reads Git metadata (evidence: `internal/cli/cli.go`)
- Project initialization → Configuration: generates config (evidence: `internal/setup/setup.go`)
- Remote commands → Module discovery: finds module (evidence: `internal/cli/remote.go`)
- Remote commands → Configuration: loads targets (evidence: `internal/cli/remote.go`)
- Remote commands → Cross-platform build: builds target (evidence: `internal/cli/remote.go`)
- Remote commands → Deployment transaction: starts deployment (evidence: `internal/cli/remote.go`)
- Remote commands → Server checks: checks target (evidence: `internal/cli/remote.go`)
- Remote commands → Status and logs: queries status/logs (evidence: `internal/cli/remote.go`)
- Remote commands → Container controls: manages container (evidence: `internal/cli/remote.go`)
- Cross-platform build → Artifact handling: writes artifact
- Cross-platform build → Git metadata: uses repository metadata
- Remote commands → Image versioning: versions image
- Deployment transaction → SSH and SCP: uploads and executes (evidence: `internal/deploy/deploy.go`)
- Deployment transaction → Remote Docker scripts: runs transaction script
- Deployment transaction → Deployment server: deploys remotely (evidence: `README.md`)
- Server checks → SSH and SCP: runs remote checks (evidence: `internal/deploy/doctor.go`)
- Status and logs → SSH and SCP: requests remote state (evidence: `internal/deploy/observe.go`)
- Container controls → SSH and SCP: runs container action
- SSH and SCP → Diagnostic redaction: redacts diagnostics (evidence: `internal/deploy/ssh.go`)
- SSH and SCP → Remote output: formats remote output (evidence: `internal/deploy/ssh.go`)
- Artifact cleanup → Artifact handling: removes artifact directory
- Bash completion → Configuration: loads target names (evidence: `internal/completion/completion.go`)
- Bash completion → Module discovery: finds module (evidence: `internal/completion/completion.go`)
