78 lines
3.5 KiB
Markdown
78 lines
3.5 KiB
Markdown
# 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
|
|
|
|
```text
|
|
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
|
|
|
|
1. Bootstrap-only environment or secret files: listen address, database/data root, agent endpoint/token file, master-key file and allowed bind roots.
|
|
2. Global administrator settings in SQLite: public game address, defaults, audit retention, notification channels, upload limits and safety policies.
|
|
3. Template defaults.
|
|
4. 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.
|