Architecture
Understand Hikyo's process, storage, API, and trust boundaries.
Hikyo ships as one Go binary. The same binary serves the web app and API, runs migrations, performs host-only recovery, and provides the client CLI.
Runtime shape
browser or CLI
| HTTPS
v
reverse proxy
| private HTTP
v
hikyo server --- datastore
|
`--- encrypted backup archiveOnly the server and local admin role unwrap the data-encryption key. The
browser, network CLI, reverse proxy, datastore, backup exporter, and restore
command never receive the operator root key. The one exception is restore drill, which boots the restored scratch copy with an explicitly supplied root
key file to prove recovery.
One binary, several roles
| Role | Commands | Boundary |
|---|---|---|
| Server | hikyo server | Serves UI, API, health, and readiness. |
| Migration | hikyo migrate, sudo hikyo upgrade | Applies datastore schema changes; the upgrade coordinator drives the verified in-place upgrade. |
| Host operator | hikyo admin, backup, restore, escrow | Runs only beside the datastore. |
| Kubernetes operator | hikyo operator, config-rollout | Separate deployable; reconciles HikyoSecret and the in-cluster rollout authority. |
| Network client | login, hierarchy, values, access, identities | Uses the versioned HTTP API. |
Every role answers --help; see CLI reference.
Host-operator commands do not have network routes. Host access is the authority for bootstrap and recovery, so these commands must run on the server host.
HTTP surfaces
- The separate operational listener serves
/healthz,/readyzand/metrics; these are not routes on the browser/API listener. /healthzproves the operational listener can answer./readyzchecks datastore and applicable HA readiness with a bounded probe./api/v1/*is validated against the OpenAPI contract.- All other browser routes belong to the embedded single-page app.
Health probes are unauthenticated and reveal no tenant data; metrics additionally require a loopback caller. API handlers use one error shape and keep unauthorized resources indistinguishable from missing resources.
Storage and encryption
Hikyo supports SQLite and PostgreSQL. Sensitive values are envelope-encrypted before storage. The datastore carries wrapped key material, but not the root key needed to unwrap it.
An encrypted backup contains the datastore and wrapped hierarchy. Reading its values requires both the backup identity and the separate Hikyo root key.
Startup sequence
Production startup hardens the process, checks or applies migrations, loads the keyring, configures authentication, and only then opens the listener. Any failed boundary check prevents the server from serving.
Next: model resources in the hierarchy or prepare a production instance.