Architecture

Last updated 2026-10-06

This page uses a single overview diagram to show how the PodRun CLI, the remote host, and the API server relate.

System Overview

graph LR
    subgraph Local Host
        CLI[podrun CLI<br/>cmd/cli]
        API[API Server<br/>cmd/api :8080]
        DB[(SQLite)]
    end
    subgraph Remote Host
        Dir[/home/podrun/name_hash/]
        Compose[Podman Compose]
        K3s[k3s unfinished]
    end
    CLI -->|rsync over sshpass| Dir
    CLI -->|ssh commands| Compose
    CLI -.->|unfinished| K3s
    Compose --> Dir
    CLI -->|HTTP POST| API
    API --> DB

Layers

Layer	Package	Responsibility
Entry	`cmd/cli`	Load `.env`, check dependencies and env vars, test SSH, dispatch the command
Entry	`cmd/api`	Resolve `DB_PATH`, open SQLite, start the HTTP server
Command	`internal/command`	Parse arguments, derive local and remote paths, run `up` / `clear` / passthrough commands, report to the API
Utilities	`internal/utils`	`sshpass` wrappers (`SSHRun`, `SSEOutput`, `SSHTest`), dependency install, local MAC / IP / hostname
HTTP	`internal/handler`	Gin routes and JSON binding
Storage	`internal/database`	Upsert, update, insert, and list for `pods` / `records`
Model	`internal/model`	`Pod`, `Record`, `User` structs

Cross-Cutting Principles

Nothing installed remotely: the remote host needs only SSH and Podman; all logic runs in the local CLI through SSH commands
Original files untouched: the local compose file is never modified; rewriting happens only in the remote copy docker-compose.podrun.yml
Record failures never block deploys: errors from removePod() and recordPod() are ignored; only the final upsertPod() in up returns an error

Architecture

System Overview

Layers

Cross-Cutting Principles

Further Reading