PR #8332 - decocms/studio

What is this contribution about?

A redesign of the Monitor. UI only: the diff against main touches nothing but apps/web. Everything the UI reads that the API doesn't serve yet is listed under Migration Notes, with the contract file it is typed against. This PR is meant to be picked up by a developer who connects it to the API.

Tabs: Overview · Performance · Logs · Deploys · Experiments · Analytics · Heatmap.

Overview:
- an "ask the agent" bar with the model picker and three suggested questions;
- then what needs attention: the order monitor's alerts, worst first. When there are none: "Nothing needs attention", plus what is being watched;
- then up to four number cards (figure, change against the prior period, chart);
- then "Connect more sources", listing only the sources still missing.
Performance:
- CDN cards, charts and tables for a deco CDN site, plus Web Vitals when the site is on Deco Analytics;
- a Blocks 8 site shows its own telemetry (Site / Upstreams / Errors) inside the same frame;
- across projects, a comparison per project.
Logs: the site's own logs and spans, built in the design system: level/kind/service filters, search, a histogram by level, and a detail sheet. It replaces the old Errors tab. Tool-call audit logs stay in Settings → Monitor.
Analytics:
- Deco Analytics sections: overview, behaviour, events, segments, currency and configuration. "Right now" in the period select switches the cards to the realtime view;
- for sites still on OneDollarStats, the same overview from that source;
- when a site has both, a "Source" select picks one.
Deploys: as on main: what shipped, what it did to the numbers and what is still being measured, with the repository picker in the top bar.
Experiments: as on main: a project's experiments in their own screen, or every project's in one list across the org.
Heatmap: Deco Analytics' heatmap.
Deco Analytics is not offered yet. It costs deco for every site that sends it, so nothing in the Monitor adds it:
- a site without it shows a "Deco Analytics is coming soon" card in Analytics and Heatmap, instead of a turn-on button;
- the install flow (onboarding, install check, the agent's install button) is in a separate, stacked PR: https://github.com/decocms/studio/pull/8357.
Empty states: every setup state uses the same connect card, with a faded preview behind and a row per source or project. This covers no project, no project picked, Deco Analytics coming soon, and a site that sends no logs.

Versions of a store: what changes, and how to test each

The Monitor draws differently depending on five independent axes. Any project is one point in this matrix. Most "this looks wrong" reports will come from a combination nobody opened.

Axis	Values	Decided by	What changes
Hosting	deco CDN (v7) · Blocks 8 (v8) · not hosted by deco (Deco Analytics registered by domain)	`monitorKind(useMainSchemaV8)` and `storedExternalRegistration(project.metadata)` in `performance-view.tsx`	Performance is three different screens: CDN tables, the v8 telemetry (Site / Upstreams / Errors), or "not on deco's CDN" for a site deco doesn't host. Logs only exist for v8; other sites get "doesn't send logs yet".
Analytics source	Deco Analytics · OneDollarStats · both · none (coming soon)	`analytics/status` (`registered`) and `/monitor/:site/audience` (`available`, `source`)	Analytics: full Deco sections, the OneDollar overview, a Source select, or the coming-soon card. Heatmap and Web Vitals are Deco only. Overview traffic cards: Deco reads a rolling 24 h with the prior period; OneDollar reads today in calendar days, with no comparison.
Orders	VTEX order monitor live · VTEX without the ingest (`partial`) · none	`useLiveBoard` → `board.stores` and `board.sources`	Overview alerts exist only with a monitored store. Orders, cancellations, conversion, errors and latency cards come from the board. Without a store there is no alerts slot, and VTEX shows up in "Connect more sources".
Scope	project route · org with one project · org with several ("All projects") · org with none	`monitorScope` / `ProjectFilter`	Overview sums the projects. Performance and Analytics show a per-project comparison. Logs and Heatmap ask you to pick a project. With no project, every tab shows the connect card.
Control-plane views	`views.monitor` on/off	`useControlPlaneViews`	Off: Performance, Logs, Analytics and Heatmap show the "add your site" card.

How to test between them

Use real projects that cover each row. A minimum set:

a deco CDN site reporting to OneDollarStats only, and a site deco doesn't host with Deco Analytics installed by domain;
a deco CDN site registered in Deco Analytics;
a Blocks 8 site;
a project with the VTEX order monitor live, and one with VTEX connected but no ingest;
an org with two or more projects, and an org with none.

For each one, open all five tabs at the project route and at the org route (with "All projects" and with the project picked in the filter).

I explored all of this on a local scenario stack: compose override, a fake control plane / Deco Analytics / OneDollar server, and a seed that creates one org per row above. It isn't in the repo; ask me for it. The UI here was also checked against local mocks of the endpoints below, and none of those mocks are in this PR.

What may not make sense once it's connected

Treat these as hypotheses to check, not known bugs:

"Connect more sources" on the Overview:
- its "Google Analytics" row is the Google connection, not Deco Analytics or OneDollar. A site with Deco Analytics will still be asked to connect Google Analytics;
- "deco site" opens the New project dialog.
Source select (Deco + OneDollar). It only appears once /audience?source=onedollar answers with source: "onedollar". Until the API honours source, it stays hidden.
OneDollar windows. OneDollar reads whole UTC days, so its "Last 24 hours" is today so far, and the Overview cards show no change for it. That's on purpose, but it differs from a Deco site side by side.

Screens that differ the most between versions

Performance, v7 vs v8 vs not hosted: different content entirely, sharing only the frame.
Analytics, Deco vs OneDollar: Deco has realtime, funnel, events, segments and currency. OneDollar has an overview, top pages, sources, countries and devices.
Org vs project: Overview, Performance and Analytics aggregate or compare across projects. Logs and Heatmap only work on one project.
Overview with vs without a store: alerts and order cards, versus traffic cards plus "Connect more sources".

How did you verify your code works?

bun run fmt, bun run lint and bun run knip are clean. tsc --noEmit in apps/web is clean.
Monitor, order-monitor, main-panel-tabs and i18n tests: 412 pass, 0 fail.
Web and plugin tests, run as bun run test runs them (--parallel):
- this branch: 5045 pass, 356 fail;
- a clean checkout of main: the same 356 failures. They pass file by file and none is in this PR's files, so they predate it.
API tests were not run: they need the local Postgres, and Docker was down. This PR doesn't touch apps/api.
Merged the latest main. Its per-project Analytics fix for sites deco doesn't host (#8351) is carried over to Performance, the tab that now shows the CDN.
Every tab was opened in every scenario of the local stack with Playwright: text and screenshots per org × tab, checked for consistent empty states and controls.

Follow-ups

Settings → Analytics still has main's registration form, so an admin can still register a site from there. Hide it too if nobody should add Deco Analytics yet.
In the install PR, Settings → Analytics' registration form overlaps with the Monitor's onboarding. Moving Settings onto the onboarding would remove the duplicate.

Screenshots/Demonstration

Not attached yet: the local Docker environment went down while recording. The "coming soon" card was rendered with Playwright component testing (real components, design-system CSS) and will be attached here. Screens are best reviewed live against the scenarios above.

How to Test

Check out the branch and run the web app against an environment with the projects listed under How to test between them.
For each project, open Overview, Performance, Logs, Analytics and Heatmap, at the project route and at the org route.
Expected:
- every setup state shows the same connect card;
- every period control is the same select with a calendar;
- sites without Deco Analytics show the coming-soon card, and Deco sites show filters and configuration.

Migration Notes

The UI reads these, which main's API does not serve yet:

Endpoint	Contract	Notes
`GET /api/:org/monitor/:site/audience?view&range&host&trafficSite&source`	`components/monitor/audience-contract.ts`	One normalized shape for Deco Analytics and OneDollarStats. `source` (`deco-analytics` · `onedollar`) forces one source when the site has both; without it, the server picks.
`GET /api/:org/monitor/:site/site/events?range&kinds&levels&services&q&cursor`	`components/monitor/site-events-contract.ts`	The Logs tab: events, total, histogram by level, facets, cursor. `{ available: false }` for a site that sends no telemetry.
`GET /api/:org/hosting/:site/analytics/values`	`useFilterValues` in `components/monitor/analytics/segment.ts`	The values of a dimension, for the segment filter builder.

No database migrations.

Review Checklist

PR title is clear and descriptive
Changes are tested and working
Documentation is updated (if needed)
No breaking changes

🤖 Generated with Claude Code