Dashboard Reference

apps/dashboard-reference is a self-hostable Next.js server that ingests httpSink events from gecx-chat and renders the five pre-built dashboard widgets (DeflectionTrend, CsatDistribution, AhtHistogram, AgentAssistRate, GmvBreakdown) plus the composite <MetricsDashboard> against a live event stream.

Use it when you want a visible health surface without standing up GA4, Segment, Mixpanel, or a full analytics warehouse. Use it as a reference implementation when you do.

For the integration walkthrough, deploy guidance, and "when to outgrow this" pointers, see the Hosted Dashboard guide.

Run it

From the repo root:

cd apps/dashboard-reference
cp .env.local.example .env.local
# Set DASHBOARD_INGEST_TOKEN to a random string when running outside localhost.
pnpm install
pnpm dev

Then point your SDK at it:

import { createChatClient, httpSink } from 'gecx-chat';

createChatClient({
  // ...
  analytics: {
    sink: httpSink({
      url: 'http://localhost:3003/api/events',
      headers: { authorization: 'Bearer <your-token>' },
    }),
  },
});

The dashboard polls /api/events every 5 seconds; new events appear within one poll cycle.

What's in the box

The default store is an in-memory ring buffer of 10k events pinned to globalThis (so dev-server hot reloads preserve events). The store interface in apps/dashboard-reference/src/lib/store.ts documents the SQLite extension hook for persistent deployments.

When to use this vs. a warehouse

• Use it when you're prototyping, piloting, or want a single source of truth for the five canonical metrics before deciding which warehouse to commit to.
• Outgrow it when event volume exceeds ~10M / day, when you need real auth (OIDC, RBAC, multi-tenant), or when you need backfill / replay / alerting.

When you outgrow it, keep httpSink pointed at your warehouse's ingest endpoint instead. The aggregation primitives (computeDeflectionRate, computeCsat, computeAverageHandleTime, computeAgentAssistRate, computeGmv) are pure functions over ProductAnalyticsEvent[] and run anywhere; the widget components accept any event source.

See also

• Hosted Dashboard guide — full deploy and configuration walkthrough.
• Analytics — the event surface and built-in sinks.
• Showcase /dashboards — the same widgets rendered against seeded events for first-load population.