Production delivery baseline: official Docker assets, health-check conventions, and a frontend performance budget

[webup]

Migrated from issue #116, originally opened by @Thalia325. Moved to a discussion for broader design conversation.

Related capability

Other / Infrastructure

Problem or motivation

ClawMaster is reasonably friendly for local single-user use today, but from an enterprise-delivery, production-ops, and sustainable-scale perspective, it still lacks a set of foundational capabilities.

Three main gaps:

1. No official service-deployment assets. The primary install paths today are npm install -g clawmaster and the desktop installer. The repo does not ship first-class production assets like a Dockerfile, docker-compose.yml, Helm chart, or Terraform / IaC reference. That makes environments non-reproducible, configuration drift hard to control, the standard rollback path unclear, and forces every enterprise PoC or rollout to build its own ops scaffolding.

2. No standardized runtime conventions. CI and basic smoke tests exist, but the runtime contract is thin: containerized deployment shape, config mount and data persistence paths, health / readiness endpoints, log collection and triage guidance, startup/stop graceful-shutdown behavior, and resource-teardown policy under SIGTERM / SIGINT.

3. The frontend build is already signaling a performance debt. npm run build succeeds, but Vite already warns about the main bundle size. Locally the entry artifact measures roughly assets/index-*.js ≈ 794.47 kB. That means the first-paint entry carries too much code, route-level code splitting isn't aggressive enough, stacking more features will compound the debt, and both the web browser and the desktop WebView suffer.

For a production-grade project, these shouldn't be "we'll optimize later" — they should become explicit delivery and budget constraints.

Proposed solution

Establish a unified "production delivery & runtime baseline" across three layers: deployment assets, runtime conventions, and performance budget.

Layer 1 — Official Docker baseline

1. Ship an official Dockerfile.
2. Ship an official docker-compose.yml.
3. Document explicitly: service listen port, auth-related env vars, config file path, data directory mount, log output location, upgrade and rollback guidance.

Layer 2 — Runtime & observability conventions

1. Define liveness / readiness probes: backend liveness, backend readiness, frontend availability, runtime-mode status.
2. Specify graceful-shutdown behavior: how we stop on SIGTERM / SIGINT, how in-flight async work is drained, how child processes and resource handles are cleaned up.
3. Add production-ops docs: containerized deployment, common startup-failure triage, log and diagnostic paths, Windows / Linux / Web mode differences.

Layer 3 — Frontend performance budget governance

1. Establish bundle budgets: main entry bundle, per-route chunk, large-dependency adoption threshold.
2. Split code by module, starting with: Settings, Memory, Channels, Skills, Models, Docs.
3. Emit a build-size summary in CI: at minimum a chunk-size report, and warn-or-fail on over-budget artifacts.
4. Define performance acceptance criteria: the first paint loads only first-paint logic, heavy pages lazy-load by route and module, new heavyweight dependencies justify benefit vs cost.

Alternatives considered

1. Keep only the npm / desktop install paths — sufficient for individual users, not enough for standardized enterprise deployment and ops.
2. Start directly from Helm or Terraform — valuable, but higher rollout cost. A Docker baseline is a better first-phase official asset.
3. Just note "we'll optimize performance later" — too vague to become an engineering constraint, and can't support production-grade quality goals.