Built to be safe in front of strangerssafe in front of strangers

• No user system, SSO or RBAC, and no key issuance or rotation. Key risk stays with the owner.
• No dynamic switching across multiple SigNoz backends: the single upstream is fixed by SIGNOZ_BASE_URL, which prevents SSRF.
• No domain allowlist. The embed is fully public: anyone holding the link can view.
• No dashboard editing, creation, deletion, locking or alert management.
• No dashboard list, playlists or snapshot export.

Phase 1 chrome decision: hide alerts, hide the lock switch and show annotations read-only.

Read-only is not a UI state; it is an allowlist in the backend. The frontend implements no editing entries, and the proxy forwards only dashboard reads, the v3/v4/v5 query_range family, substitute_vars and the two variable-candidate endpoints. Everything else under /api/* returns 403, including every write interface.

This split matters because the embed is public. A hidden button is still one request away; a blocked route is not.

The effective key resolves as x-embed-api-key ?? URL apiKey ?? env.SIGNOZ_API_KEY. The browser keeps the URL key in memory only; it is never written to localStorage, a cookie or serialized back into the URL unless the caller put it there.

Logs and documents may only contain the key source and the first 8 characters of a hash. Query strings are redacted before serialization, so plaintext keys cannot land in logs, bug reports or commits.

The frontend is split into core/ (stable: routing, auth context, data fetching, time and variables, replaceState, empty-state mapping), signoz/ (query semantics), and themes/<name>/.

A theme implements four components: Tokens, Toolbar, WidgetCard and ErrorState. The shadcn theme (default) uses Tailwind and Recharts; the legacy theme uses antd and ECharts. Unknown theme values fall back to shadcn in one registry lookup.

The rule that keeps this honest: a new theme adds a folder and one registry line, and never touches core. Theme branches inside core are treated as bugs and refactored back to the contract.

Any design change (URL params, proxy matrix, trim list, env vars, error codes, deployment shape) updates the design document before the code, and a code change without the document update is invalid. Pitfalls found while developing or debugging are appended as rows to a single bug-track file with fixed columns.

This is deliberately boring: it keeps one source of truth, one TODO list and one pitfall log, so both humans and agents can audit why a decision exists.

SigNoz v0.97.0 query semantics are the target. The proxy passes through the v3/v4/v5 query_range APIs and variable endpoints without validating unknown fields, so upstream payloads evolve safely.

The earlier route of copying the SigNoz frontend verbatim was abandoned: the dependency closure and provider-chain cost were too high and it conflicted with the theme extension goal. The vendor snapshot is read-only comparison material only, never built and never copied into the runtime.

Four dashboards on the test backend anchor the acceptance runs: a System Overview smoke dashboard, a Kubernetes dashboard with QUERY variables, tables and clickhouse panels, a Postgres dashboard with DYNAMIC variables, and an Elasticsearch dashboard with formulas.

The matrix covers: no key with env default, wrong key, wrong id, full params and replaceState, upstream outage with self-healing retry, iframe-resizer wired or not, Chrome 108, read-only enforcement, health and metrics without plaintext keys, dozens of panels, and unknown theme fallback.