# Architecture

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

## System Overview

```mermaid
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

## Further Reading

Per-module diagrams, the `up` sequence diagram, and the state machine live in [doc/architecture.md](https://github.com/pardnchiu/PodRun/blob/master/doc/architecture.md).