Track HiveGrid Cloud planning reference

hivegrid-cloud/docs/configuration.md

@@ -0,0 +1,114 @@
+# Configuration
+
+This project keeps runtime configuration explicit and treats secret diagnostics
+as a
+public surface. Application code should receive configuration through typed
+loaders, provider options, or handler dependencies instead of reading
+`process.env` inside package internals.
+
+## Explicit environment access
+
+Only runtime entrypoints should read from `process.env`. Worker-owned
+environment reads are limited to the worker runtime and health entrypoints.
+Those entrypoints immediately validate values and convert them into explicit
+dependencies for queues, Mailjet, browser runtime integrations, and
+handlers.
+
+Package adapters must accept an environment object or concrete provider options
+from their caller. This keeps hidden environment coupling out of packages such
+as `packages/mail` and `packages/queue`, makes tests deterministic, and lets
+diagnostics report configuration status without exposing raw secret values.
+
+## Worker enablement
+
+The worker is opt-in. Set `WORKER_ENABLED=true` only on deployments that should
+start queue processors. In multi-resource platforms such as Coolify, do not put
+`WORKER_ENABLED=false` into a shared production environment group that is also
+injected into the worker resource; leave it unset for web/API resources and set
+it explicitly to `true` on each worker resource.
+
+When the worker is enabled, provide queue configuration explicitly:
+
+- `WORKER_QUEUE_GROUP` must be one of `general`, `mail`, `import`, `webhook`,
+  or `plugin` for grouped worker resources.
+- `WORKER_HEALTH_PORT` and `WORKER_ADMIN_PORT` should be unique per Coolify
+  worker app when those endpoints are exposed.
+- `BULLMQ_REDIS_URL` is the worker Redis URL.
+- `REDIS_URL` is accepted only as a fallback when `BULLMQ_REDIS_URL` is absent.
+
+If the worker is disabled, queue processors should not start. Health and runtime
+diagnostics may still report enablement and readiness status, but they must not
+include the Redis URL value.
+
+## Mailjet configuration
+
+Mailjet is the transactional mail provider boundary for API and worker
+runtimes. Mail delivery requires the provider key and verified sender domain
+address to be configured together:
+
+- `MAILJET_API_KEY` is the Mailjet API token.
+- `MAILJET_FROM_EMAIL` is the default sender email from a verified Mailjet
+  domain.
+- `MAILJET_FROM_NAME` is an optional sender display name.
+
+Treat `MAILJET_API_KEY` and `MAILJET_FROM_EMAIL` as a required pair
+whenever Mailjet delivery is enabled. Supplying only one of the pair is
+invalid configuration because the provider cannot safely send mail without both
+authentication and an approved sender address.
+
+## Browser runtime configuration
+
+Worker browser runtime settings are explicit worker configuration, not
+package-global state:
+
+- `BROWSER_RUNTIME_URL` identifies the browser runtime service endpoint when
+  that integration is enabled.
+- `BROWSER_RUNTIME_API_KEY` authenticates requests to the browser runtime
+  service.
+- `BROWSER_SESSION_TIMEOUT_MS` configures the session timeout and must parse as
+  a valid millisecond duration.
+
+Browser runtime diagnostics should report key names, parse status, and
+diagnostic codes only. They must never include endpoint secrets, API keys,
+tokens, or raw values.
+
+## Safe diagnostics and redaction
+
+Configuration validation must use the central redacted secret validator for
+required and optional secret-like values. Errors, health JSON, and logs may
+include:
+
+- environment key names;
+- diagnostic codes;
+- parse status;
+- high-level messages;
+- queue readiness or worker enablement status.
+
+They must not include raw secret values. This applies to Redis URLs, database
+URLs, API keys, tokens, Mailjet sender secrets, browser runtime credentials,
+and any future provider secret.
+
+When reporting invalid or missing configuration, prefer messages such as
+`missing required env key MAILJET_API_KEY` or
+`invalid duration for BROWSER_SESSION_TIMEOUT_MS`. Do not interpolate the
+rejected value into thrown errors, logs, or health responses.
+
+## Seed Credentials
+
+Local demo users and demo tenants are opt-in through `SEED_DEMO_DATA=true` and
+are refused in production. Production bootstrap seeding requires
+`SEED_ADMIN_EMAIL` and `SEED_ADMIN_PASSWORD`, creates only the configured admin
+plus roles, permissions, and entitlements, and refuses local default seed emails
+or the default `password`.
+
+## Adding new configuration
+
+When adding a new runtime setting:
+
+1. Decide which runtime entrypoint owns the environment read.
+2. Validate and normalize the value before passing it to packages or handlers.
+3. Use the redacted secret validator for secret-like required or optional values.
+4. Pass normalized values through explicit options or dependencies.
+5. Add tests that assert diagnostics expose keys and codes, not raw values.
+6. Update this document and the environment inventory when the setting is
+   user-facing.