# basecamp/once architecture

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

- Interactive diagram: https://gitdiagram.com/basecamp/once
- Repository: https://github.com/basecamp/once

## Overview

ONCE manages Docker-hosted web applications through an interactive TUI and CLI: users install an image, configure its hostname and settings, then monitor and operate it. The graph includes deployment, app lifecycle, backups/restores, scheduled updates, service management, and monitoring capabilities documented or visible in the supplied sources. Edges are limited to relationships evidenced by excerpts, the source index, or README; unsampled command and UI internals are represented only where documented.

Main entry points: [`internal/ui/app.go`](https://github.com/basecamp/once/blob/main/internal/ui/app.go) (TUI application), [`internal/docker/application.go`](https://github.com/basecamp/once/blob/main/internal/docker/application.go) (Application runtime), [`internal/background/runner.go`](https://github.com/basecamp/once/blob/main/internal/background/runner.go) (Background runner), [`internal/ui/dashboard.go`](https://github.com/basecamp/once/blob/main/internal/ui/dashboard.go) (Dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_cli["CLI commands"]
  node_tui["TUI application<br/>[app.go]"]
  node_install["Install flow<br/>[install.go]"]
  node_dashboard["Dashboard<br/>[dashboard.go]"]
  node_panels["App panels<br/>[dashboard_panel.go]"]
  node_settings["App settings<br/>[settings.go]"]
end

subgraph group_apps["Application management"]
  node_namespace["Docker namespace<br/>[namespace.go]"]
  node_application["Application runtime<br/>[application.go]"]
  node_deployment["Image deployment<br/>[deploy.go]"]
  node_container["Container control<br/>[container.go]"]
  node_proxy["HTTP proxy<br/>[proxy.go]"]
  node_appsettings["Settings model"]
end

subgraph group_ops["Operations"]
  node_backup["Backup and restore"]
  node_runner["Background runner<br/>[runner.go]"]
  node_service["Background service<br/>[service.go]"]
  node_updater["Self updater<br/>[updater.go]"]
end

subgraph group_monitor["Monitoring"]
  node_metrics["Metrics scraper<br/>[scraper.go]"]
  node_dockerstats["Docker scraper<br/>[scraper.go]"]
  node_systemstats["System scraper<br/>[scraper.go]"]
  node_userstats["Usage statistics<br/>[scraper.go]"]
  node_statsreader["Statistics reader<br/>[reader.go]"]
end

node_operator(("Operator"))
node_docker{{"Docker engine"}}
node_host{{"Host system"}}

node_operator -->|"runs commands"| node_cli
node_operator -->|"operates"| node_tui
node_cli -->|"restores namespace"| node_namespace
node_cli -->|"launches"| node_tui
node_tui -->|"selects screen"| node_install
node_tui -->|"selects screen"| node_dashboard
node_install -->|"installs app"| node_namespace
node_dashboard -->|"builds panels"| node_panels
node_dashboard -->|"starts or stops"| node_application
node_dashboard -->|"opens settings"| node_settings
node_settings -->|"changes settings"| node_appsettings
node_namespace -->|"provides apps"| node_application
node_application -->|"controls"| node_container
node_deployment -->|"deploys image"| node_application
node_application -.->|"configures routing"| node_proxy
node_application -->|"backs up data"| node_backup
node_runner -->|"restores namespace"| node_namespace
node_runner -->|"checks updates"| node_application
node_runner -->|"schedules backups"| node_backup
node_runner -->|"updates binary"| node_updater
node_service -.->|"runs periodically"| node_runner
node_tui -->|"scrapes metrics"| node_metrics
node_tui -->|"scrapes containers"| node_dockerstats
node_tui -->|"scrapes host"| node_systemstats
node_tui -->|"scrapes usage"| node_statsreader
node_statsreader -.->|"reads summaries"| node_userstats
node_userstats -->|"reads proxy logs"| node_docker
node_dockerstats -.->|"collects stats"| node_docker
node_application -.->|"manages containers"| node_docker
node_systemstats -.->|"collects resources"| node_host
node_proxy -.->|"serves web apps"| node_operator

click node_cli "https://github.com/basecamp/once/tree/main/internal/command"
click node_tui "https://github.com/basecamp/once/blob/main/internal/ui/app.go"
click node_install "https://github.com/basecamp/once/blob/main/internal/ui/install.go"
click node_dashboard "https://github.com/basecamp/once/blob/main/internal/ui/dashboard.go"
click node_panels "https://github.com/basecamp/once/blob/main/internal/ui/dashboard_panel.go"
click node_settings "https://github.com/basecamp/once/blob/main/internal/ui/settings.go"
click node_namespace "https://github.com/basecamp/once/blob/main/internal/docker/namespace.go"
click node_application "https://github.com/basecamp/once/blob/main/internal/docker/application.go"
click node_deployment "https://github.com/basecamp/once/blob/main/internal/command/deploy.go"
click node_container "https://github.com/basecamp/once/blob/main/internal/docker/container.go"
click node_proxy "https://github.com/basecamp/once/blob/main/internal/docker/proxy.go"
click node_appsettings "https://github.com/basecamp/once/blob/main/internal/docker/application_settings.go"
click node_backup "https://github.com/basecamp/once/blob/main/internal/docker/application_backup.go"
click node_runner "https://github.com/basecamp/once/blob/main/internal/background/runner.go"
click node_service "https://github.com/basecamp/once/blob/main/internal/service/service.go"
click node_updater "https://github.com/basecamp/once/blob/main/internal/version/updater.go"
click node_metrics "https://github.com/basecamp/once/blob/main/internal/metrics/scraper.go"
click node_dockerstats "https://github.com/basecamp/once/blob/main/internal/docker/scraper.go"
click node_systemstats "https://github.com/basecamp/once/blob/main/internal/system/scraper.go"
click node_userstats "https://github.com/basecamp/once/blob/main/internal/userstats/scraper.go"
click node_statsreader "https://github.com/basecamp/once/blob/main/internal/userstats/reader.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_tui,node_install,node_dashboard,node_panels,node_settings toneBlue
class node_namespace,node_application,node_deployment,node_container,node_proxy,node_appsettings toneAmber
class node_backup,node_runner,node_service,node_updater toneMint
class node_metrics,node_dockerstats,node_systemstats,node_userstats,node_statsreader toneRose
class node_operator,node_docker,node_host toneIndigo
```

## Components

### User interfaces

- [CLI commands](https://github.com/basecamp/once/tree/main/internal/command): `internal/command`
- [TUI application](https://github.com/basecamp/once/blob/main/internal/ui/app.go): `internal/ui/app.go`
- [Install flow](https://github.com/basecamp/once/blob/main/internal/ui/install.go): `internal/ui/install.go`
- [Dashboard](https://github.com/basecamp/once/blob/main/internal/ui/dashboard.go): `internal/ui/dashboard.go`
- [App panels](https://github.com/basecamp/once/blob/main/internal/ui/dashboard_panel.go): `internal/ui/dashboard_panel.go`
- [App settings](https://github.com/basecamp/once/blob/main/internal/ui/settings.go): `internal/ui/settings.go`

### Application management

- [Docker namespace](https://github.com/basecamp/once/blob/main/internal/docker/namespace.go): `internal/docker/namespace.go`
- [Application runtime](https://github.com/basecamp/once/blob/main/internal/docker/application.go): `internal/docker/application.go`
- [Image deployment](https://github.com/basecamp/once/blob/main/internal/command/deploy.go): `internal/command/deploy.go`
- [Container control](https://github.com/basecamp/once/blob/main/internal/docker/container.go): `internal/docker/container.go`
- [HTTP proxy](https://github.com/basecamp/once/blob/main/internal/docker/proxy.go): `internal/docker/proxy.go`
- [Settings model](https://github.com/basecamp/once/blob/main/internal/docker/application_settings.go): `internal/docker/application_settings.go`

### Operations

- [Backup and restore](https://github.com/basecamp/once/blob/main/internal/docker/application_backup.go): `internal/docker/application_backup.go`
- [Background runner](https://github.com/basecamp/once/blob/main/internal/background/runner.go): `internal/background/runner.go`
- [Background service](https://github.com/basecamp/once/blob/main/internal/service/service.go): `internal/service/service.go`
- [Self updater](https://github.com/basecamp/once/blob/main/internal/version/updater.go): `internal/version/updater.go`

### Monitoring

- [Metrics scraper](https://github.com/basecamp/once/blob/main/internal/metrics/scraper.go): `internal/metrics/scraper.go`
- [Docker scraper](https://github.com/basecamp/once/blob/main/internal/docker/scraper.go): `internal/docker/scraper.go`
- [System scraper](https://github.com/basecamp/once/blob/main/internal/system/scraper.go): `internal/system/scraper.go`
- [Usage statistics](https://github.com/basecamp/once/blob/main/internal/userstats/scraper.go): `internal/userstats/scraper.go`
- [Statistics reader](https://github.com/basecamp/once/blob/main/internal/userstats/reader.go): `internal/userstats/reader.go`

### Other components

- **Operator**
- **Docker engine**
- **Host system**

## Connections

- Operator → CLI commands: runs commands (evidence: `internal/command/root.go`)
- Operator → TUI application: operates
- CLI commands → Docker namespace: restores namespace (evidence: `internal/command/root.go`)
- CLI commands → TUI application: launches (evidence: `internal/command/root.go`)
- TUI application → Install flow: selects screen (evidence: `internal/ui/app.go`)
- TUI application → Dashboard: selects screen (evidence: `internal/ui/app.go`)
- Install flow → Docker namespace: installs app (evidence: `internal/ui/install.go`)
- Dashboard → App panels: builds panels (evidence: `internal/ui/dashboard.go`)
- Dashboard → Application runtime: starts or stops (evidence: `internal/ui/dashboard.go`)
- Dashboard → App settings: opens settings
- App settings → Settings model: changes settings
- Docker namespace → Application runtime: provides apps
- Application runtime → Container control: controls
- Image deployment → Application runtime: deploys image (evidence: `internal/command/deploy.go`)
- Application runtime → HTTP proxy: configures routing
- Application runtime → Backup and restore: backs up data (evidence: `internal/docker/application_backup.go`)
- Background runner → Docker namespace: restores namespace (evidence: `internal/background/runner.go`)
- Background runner → Application runtime: checks updates (evidence: `internal/background/runner.go`)
- Background runner → Backup and restore: schedules backups (evidence: `internal/background/runner.go`)
- Background runner → Self updater: updates binary (evidence: `internal/background/runner.go`)
- Background service → Background runner: runs periodically
- TUI application → Metrics scraper: scrapes metrics (evidence: `internal/ui/app.go`)
- TUI application → Docker scraper: scrapes containers (evidence: `internal/ui/app.go`)
- TUI application → System scraper: scrapes host (evidence: `internal/ui/app.go`)
- TUI application → Statistics reader: scrapes usage (evidence: `internal/ui/app.go`)
- Statistics reader → Usage statistics: reads summaries
- Usage statistics → Docker engine: reads proxy logs (evidence: `internal/userstats/scraper.go`)
- Docker scraper → Docker engine: collects stats
- Application runtime → Docker engine: manages containers
- System scraper → Host system: collects resources
- HTTP proxy → Operator: serves web apps
