Skip to content

technical-spec.md

Latest commit

 

History

History
95 lines (68 loc) · 3.15 KB

technical-spec.md

File metadata and controls

95 lines (68 loc) · 3.15 KB
Raw

Support Operations Dashboard — technical specification

Application type

Desktop-first frontend reference implementation for operational support monitoring. The current application is a single route that documents and renders the operational views in code.

Runtime stack

  • Next.js 16 with App Router
  • React 19
  • JavaScript with JSX
  • CSS custom properties for color, type, spacing, and motion tokens
  • GSAP loaded dynamically by progressive-enhancement components

next.config.mjs uses a local tmp/ build directory so the project can also run from an exFAT drive where package-manager symlinks may be unavailable.

Runtime architecture

src/app/page.jsx composes the project overview and five code-rendered operational views:

  • PulseOverviewPreview — act-now, watch, and contextual signals.
  • QueuePreview — conversations approaching or exceeding SLA.
  • AiHandoffPreview — automation resolution and human handoff by area.
  • DrilldownPreview — conversation-level detail behind a headline signal.
  • PeakStatePreview — the overview hierarchy rendered with elevated volume.

The views use deterministic sample values. There is no network request, persistence layer, or hidden production dataset.

Components

Shared presentation components

  • CaseHero
  • CaseSnapshot
  • CaseSection
  • DecisionsLedger
  • StatesGrid
  • BrowserFrame
  • Reveal
  • Scramble

These components provide consistent project documentation, progressive enhancement, and state presentation.

Operational components

  • MetricCard — renders act-now, watch, and context variants.
  • DenseTable — renders compact queue records with optional row emphasis.
  • HierarchyPreview — applies the same operational hierarchy to baseline and peak data.

State model

  • Empty — no current exception; the system remains explicit rather than showing a blank area.
  • Loading — the operational feed is connecting.
  • Error — the feed is unavailable; the interface retains the last known state and timestamp.
  • Peak — volume is elevated; the information hierarchy remains unchanged.

Sample-data boundary

All ticket IDs, counters, percentages, durations, and queue values are demonstration data. They exist to exercise component behavior and should not be interpreted as measured support performance.

A production adapter should normalize external data into a contract similar to:

{
  generatedAt: "ISO-8601 timestamp",
  queue: {
    actNow: [],
    watch: [],
    context: []
  },
  handoffs: [],
  feedStatus: "connected | stale | disconnected"
}

Reliability requirements for integration

  • Timestamp every operational snapshot.
  • Define when data becomes stale.
  • Preserve the last known state during reconnect attempts.
  • Validate external payloads before rendering.
  • Restrict queue and conversation access by role.
  • Avoid logging conversation content or personal data in the browser.

Verification

The current repository must pass:

npm run lint
npm run build
npm audit

Future integration work should add contract tests for the normalized event payload and end-to-end tests for connected, stale, disconnected, and recovered states.