# Architecture: Once app management in Ino ## Fit - `src/main.rs` owns the existing Clap CLI and defaults to automatic release when no command is given. Add `ino once` as a new top-level command while preserving that default and every current command. - `src/commands/mod.rs` is the current command-module registry. Add a Once command module there; keep deployment concerns separate from the existing release flow. - The new command implementation is native Rust and communicates with Docker Engine directly. It does not invoke, embed, or require the upstream `once` executable. - The port is organized around namespace/app management, proxy integration, and command operations. The exact Rust module/file boundaries are deferred to Gate 3. - The interactive Once TUI and onboarding screens are out of scope. `ino once` with no subcommand displays CLI help. ## Endpoints None. This is a local CLI application, not a network service. ## Data No new Ino database is proposed. Docker resources and Once-compatible metadata remain the source of truth: - The selected namespace (default `once`) contains the app and proxy containers and the namespace network. Discovery lists and inspects Docker containers in that namespace. - App and proxy settings are read from and written to the metadata/labels used by the pinned Once release. Discovery must handle any older formats supported by that release. - Application data remains in the existing named Docker volumes. Volume metadata, including legacy key storage where applicable, must be read compatibly. - Operation history/state uses Once's existing proxy-backed state mechanism; preserve its format rather than creating a parallel Ino state store. - Backup and restore use Once-compatible archives. Backup reads application settings and persistent volume data; restore validates the archive, checks hostname conflicts, recreates compatible resources, and preserves the data. Key reads/writes are Docker Engine list/inspect operations for containers, networks, and volumes; operations then create, start, stop, exec in, update, or remove the relevant resources. Metadata and state writes must remain compatible with the selected Once baseline. ## Flow 1. Clap parses `ino once [options]`; existing `ino` commands continue through their current paths. With no Once subcommand, print Once CLI help rather than starting a TUI. 2. The Once command layer resolves the requested namespace, connects to Docker Engine, restores namespace state, and discovers applications by reading the same container names and metadata that Once uses. 3. The requested operation uses the restored app model and Docker Engine. Read-only operations report the discovered state. Mutating operations preserve Once's resource names, metadata, and persistent volumes. 4. For `ino once deploy `, ensure the namespace network and proxy are ready, pull the image with registry credentials, prepare compatible settings/keys and the existing volume convention, create and start the new app container, register it with the proxy, and verify health. Remove an old app container only after the replacement succeeds; failure cleanup must not delete existing persistent data. 5. Backup, restore, update, and settings operations use the same volume/archive/state conventions and safety behavior as the pinned Once release. Background commands use an explicit service handoff path when an upstream Once service is already installed, avoiding duplicate schedulers. ## External - Docker Engine API, using the endpoint and credentials/configuration conventions supported by the pinned Once release. - Container image registries for image pulls and updates, using compatible registry authentication behavior. - Application HTTP health checks at `/up`; deployments also depend on the proxy/TLS/hostname setup supported by Once. - The host service manager for Once-compatible background-service commands, following the platforms supported by the pinned release. Detect an existing Once service; never replace it silently. - The compatibility baseline is Basecamp Once v0.3.4, the latest stable release when implementation began on 2026-10-08. - `self-update` updates Ino, not Once: use Cargo installation from Ino's `[package].repository` URL by default, with `INO_SELF_UPDATE_SCRIPT` as an explicit script override. Do not use the unrelated crates.io package named `ino`.