Main application

Responsibilities

Serve the embedded responsive web UI and versioned HTTP API.
Authenticate users and enforce global plus instance-scoped authorization.
Own catalog, immutable template snapshots and module metadata.
Validate configuration and construct canonical deployment plans.
Orchestrate lifecycle, backup, import, restore, export and update workflows.
Persist state and durable jobs in SQLite.
Run sandboxed WebAssembly adapters.
Schedule recurring work.
Deliver notifications and maintain the light audit trail.

It must not call the Docker socket, run arbitrary commands, trust client-side authorization, or let modules handle files and backups.

Proposed Go boundaries

cmd/dogama
internal/
  auth
  catalog
  instance
  backup
  importexport
  update
  module
  notify
  audit
  jobs
  persistence/sqlite
  agentclient
  web
web/                 embedded production assets
migrations/

Package names express business capabilities. Avoid a generic utils package and avoid passing database handles into HTTP handlers.

API rules

Version public routes under /api/v1.
Use opaque stable IDs, explicit request/response structs and consistent problem details.
Require idempotency keys for creation and destructive job submission.
Use optimistic revision numbers for editable instance configuration.
Never return stored secret values. Secret fields return only configured: true|false.
Paginate catalog, audit, backups and operations.
Filter every instance query by the authenticated principal before loading sensitive details.

SQLite rules

Enable foreign keys, WAL mode and a busy timeout.
Keep transactions short; filesystem and network operations happen outside transactions.
Persist workflow intent before external action and result afterward.
Use append-only migrations with a schema-version table.
Back up the SQLite database consistently as part of system backup guidance, separate from game backups.
Keep timestamps in UTC and store IANA timezone names for schedules.

Configuration precedence

Bootstrap-only environment or secret files: listen address, database/data root, agent endpoint/token file, master-key file and allowed bind roots.
Global administrator settings in SQLite: public game address, defaults, audit retention, notification channels, upload limits and safety policies.
Template defaults.
Per-instance administrator settings.

Runtime environment variables must not become a second hidden configuration interface for ordinary product options.

Web UI embedding

V1 uses server-rendered Go html/template views with progressive enhancement, a small bundled JavaScript/TypeScript layer and Server-Sent Events for operation/status updates. This keeps the browser payload and build surface small while preserving accessible forms and a stable JSON API. A large client-side framework is not required for V1.

Production CSS and script assets are compiled before the Go build and embedded. The main binary serves hashed assets with immutable caching and renders application pages without shadowing /api/ routes. Core administration workflows remain usable when optional real-time enhancement is unavailable.

Secret handling

Encrypt secret values with an authenticated encryption algorithm using a master key external to SQLite. Store key version and nonce with ciphertext. Support key rotation as a maintenance workflow. Decrypt only at the last responsible moment, keep plaintext lifetimes short and redact structured errors.

3.5 KiB Raw Permalink Blame History