πͺ’ Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.
Dashboard Feature
Surface
Dashboards: the project Home page (a read-only dashboard viewer), the self-serve dashboard detail page, and the legacy curated Home cards that render as "preset" placements.
Entry Points
web/src/features/dashboard/ProjectHomePage.tsxβ Home (route shim atpages/.../index.tsx). Controller resolves the v3/v4 read path before anything mounts, then rendersHomeDashboard.web/src/features/dashboard/DashboardDetailPage.tsxβ dashboard detail (route shim atpages/.../dashboards/[dashboardId]/index.tsx). Same controller split (DashboardDetailView).- Both pages create the per-mount scheduler store and provide it via
DashboardQuerySchedulerProvider.
Structure
components/β the legacy curated Home cards (TracesBarListChart, ModelCostTable, β¦) rendered byhome-preset-registry.tsxas preset placements, plus dashboard-scoped dialogs/selectors. Cards receive a requiredmetricsVersionfrom the preset context β they never read the session themselves.hooks/βDashboardQuerySchedulerProvider.tsx: the scheduler controller hook, provider/context, executeQuery cache policy, anduseScheduledDashboardExecuteQuery(the one entry point widgets use to run a dashboard query under the concurrency budget, over tRPC or SSE).stores/βdashboardQuerySchedulerStore.ts: per-mount vanilla Zustand store owning the widget query queue (register/unregister/markDone/ resetQueue/setMaxConcurrent). Created by the page, provided via context, destroyed on unmount.server/βdashboard-router.ts(tRPC).executeQueryrequires an explicitversionand validates v2 against the session's read path.lib/,utils/β pure helpers (table href building, import/export).
Related but outside this folder: web/src/features/widgets/ owns
DashboardGrid / DashboardWidget / WidgetContent and the chart library;
web/src/hooks/useSSEDashboardQuery.ts owns the SSE transport (kept there
because parseSSEBuffer has non-dashboard consumers).
State Ownership
- Server/query state: React Query. Both transports (tRPC fetch and the SSE
stream) cache rows under the same
["dashboard.executeQuery", input, retry]key, so identical widgets share one query/stream and a transport flip reuses cached rows. - Read path (v3/v4): session state, resolved by the page controller and
passed down as a required
readPathprop β never mirrored into a store. - Scheduler queue: the per-mount vanilla store above. Widgets subscribe to
items[queryId]?.status === "running"only. - SSE progress events: high-frequency; deliberately kept OUT of the query cache as local state on the mount that initiated the stream.
- Route state: time range / filters / peeked dashboard live in the URL hooks on the pages.
Performance And Stability Boundaries
- Scheduler slot changes re-render only the widget whose slot changed β never
the page (the store replaced a page-level
useStateversion counter that re-rendered the whole grid on every queue transition). - Progress events re-render one widget's loading state at ClickHouse's progress cadence; they must never enter the query cache or context values.
- The scheduler reset key must contain only query-affecting params β never the
widget set (
DashboardQuerySchedulerProvider.clienttest.tspins this).
Reliability Invariants
- A widget query releases its scheduler slot on every terminal path β success, error, stall (60s no-byte watchdog aborts the stream), or unmount (unregister). A held slot at 90d windows (budget: 2) freezes the dashboard.
- The SSE endpoint sets
cancel_http_readonly_queries_on_client_close, so when the browser disconnects (the handler breaks and the ClickHouse stream socket closes) the server kills the query instead of running the abandoned aggregation to completion;max_execution_timebounds any straggler.
Migration State
- Done: controller split for the read path; scheduler on a per-mount vanilla store; SSE rows/status in the React Query cache; per-widget reactive slot subscriptions.
- Still spread: the dashboard detail page is a single large component (draft
definition state, paste/import handlers, clone-first dialog state all
inline); the legacy preset cards fetch through bespoke
dashboard.chartquery names. Next slice: extract the detail page's paste/import workflows intoactions/*.ts.
Development Context
Read .agents/skills/frontend-large-feature-architecture/SKILL.md (and its
references/local-feature-state.md) before adding state or effects here. For
chart/formatting work, web/src/features/widgets/chart-library/ARCHITECTURE.md
owns the data β preparer β visualiser contract.