Digital Twin Dashboard

Digital Twin Dashboard — Implementation Reference

MetaForge’s web dashboard for 3D digital twin viewing, real-time agent monitoring, and product lifecycle tracking.

Table of contents

  1. Overview
  2. Tech Stack
  3. Project Structure
  4. Quick Start
    1. Prerequisites
    2. Install and Run
    3. Build for Production
  5. Documentation Files
  6. Pages Overview
  7. Integration Notes
    1. Gateway API
    2. WebSocket
    3. Mock Mode

Overview

The MetaForge Dashboard is a single-page application that serves as the primary visual interface for the MetaForge platform. It provides engineers with real-time visibility into agent orchestration sessions, a 3D digital twin viewer for inspecting hardware artifacts, bill-of-materials management with supply chain risk analysis, compliance tracking across regulatory markets, and approval workflows for human-in-the-loop decisions.

The dashboard communicates with the MetaForge Gateway Service over HTTP REST endpoints and WebSocket connections. A built-in mock mode (powered by MSW) enables standalone frontend development without a running backend.

Tech Stack

Layer Technology Version Purpose
Build Tool Vite 6.x Dev server, HMR, production bundling
UI Framework React 18.3 Component model and rendering
Language TypeScript 5.6 Static typing across the entire codebase
3D Rendering React Three Fiber + drei 8.17 / 9.114 Three.js integration for digital twin viewer
State Management Zustand 5.x Lightweight global stores
Server State TanStack Query v5.62 Data fetching, caching, and synchronization
Styling Tailwind CSS v4 + shadcn/ui 4.x Utility-first CSS with accessible component primitives
Charts Recharts 2.15 Data visualization (risk charts, progress, trends)
Tables TanStack Table v8.20 Headless table logic for BOM, test results, etc.
Routing React Router v7.1 Client-side routing with lazy-loaded pages
API Mocking MSW 2.7 Service worker interception for mock mode
Icons Lucide React 0.468 Consistent icon set across the UI

Project Structure

dashboard/
├── index.html
├── package.json
├── tsconfig.json
├── tsconfig.node.json
├── vite.config.ts
├── public/
│   └── favicon.svg
└── src/
    ├── main.tsx
    ├── App.tsx
    ├── index.css
    ├── vite-env.d.ts
    ├── types/
    │   ├── common.ts
    │   ├── session.ts
    │   ├── agent.ts
    │   ├── artifact.ts
    │   ├── bom.ts
    │   ├── compliance.ts
    │   ├── digital-thread.ts
    │   ├── supply-chain.ts
    │   ├── approval.ts
    │   ├── health.ts
    │   ├── websocket.ts
    │   ├── gate.ts
    │   └── testing.ts
    ├── lib/
    │   ├── utils.ts
    │   ├── constants.ts
    │   └── format.ts
    ├── api/
    │   ├── client.ts
    │   ├── sessions.ts
    │   ├── agents.ts
    │   ├── artifacts.ts
    │   ├── bom.ts
    │   ├── compliance.ts
    │   ├── supply-chain.ts
    │   ├── approvals.ts
    │   ├── health.ts
    │   └── websocket.ts
    ├── stores/
    │   ├── theme-store.ts
    │   ├── session-store.ts
    │   ├── notification-store.ts
    │   └── websocket-store.ts
    ├── hooks/
    │   ├── use-sessions.ts
    │   ├── use-agents.ts
    │   ├── use-bom.ts
    │   ├── use-compliance.ts
    │   ├── use-approvals.ts
    │   ├── use-websocket.ts
    │   ├── use-health.ts
    │   └── use-debounce.ts
    ├── mocks/
    │   ├── mock-server.ts
    │   ├── handlers/
    │   │   ├── session-handlers.ts
    │   │   ├── agent-handlers.ts
    │   │   ├── bom-handlers.ts
    │   │   ├── compliance-handlers.ts
    │   │   ├── approval-handlers.ts
    │   │   └── health-handlers.ts
    │   └── data/
    │       ├── mock-sessions.ts
    │       ├── mock-agents.ts
    │       ├── mock-bom.ts
    │       ├── mock-compliance.ts
    │       ├── mock-approvals.ts
    │       └── mock-digital-thread.ts
    ├── components/
    │   ├── ui/
    │   │   ├── badge.tsx
    │   │   ├── button.tsx
    │   │   ├── card.tsx
    │   │   ├── command.tsx
    │   │   ├── dialog.tsx
    │   │   ├── dropdown-menu.tsx
    │   │   ├── input.tsx
    │   │   ├── label.tsx
    │   │   ├── progress.tsx
    │   │   ├── scroll-area.tsx
    │   │   ├── select.tsx
    │   │   ├── separator.tsx
    │   │   ├── skeleton.tsx
    │   │   ├── table.tsx
    │   │   ├── tabs.tsx
    │   │   └── tooltip.tsx
    │   ├── layout/
    │   │   ├── root-layout.tsx
    │   │   ├── sidebar.tsx
    │   │   ├── header.tsx
    │   │   ├── breadcrumbs.tsx
    │   │   └── notification-toaster.tsx
    │   └── shared/
    │       ├── status-badge.tsx
    │       ├── risk-indicator.tsx
    │       ├── progress-ring.tsx
    │       ├── data-table.tsx
    │       ├── empty-state.tsx
    │       ├── error-boundary.tsx
    │       ├── loading-spinner.tsx
    │       ├── search-input.tsx
    │       ├── metric-card.tsx
    │       └── confirmation-dialog.tsx
    └── pages/
        ├── overview/
        │   ├── overview-page.tsx
        │   ├── gate-readiness-card.tsx
        │   ├── session-activity-chart.tsx
        │   └── agent-status-grid.tsx
        ├── sessions/
        │   ├── sessions-page.tsx
        │   ├── session-detail-page.tsx
        │   ├── session-list.tsx
        │   ├── session-trace-viewer.tsx
        │   └── session-filters.tsx
        ├── agents/
        │   ├── agents-page.tsx
        │   ├── agent-card.tsx
        │   └── agent-detail-panel.tsx
        ├── digital-twin/
        │   ├── digital-twin-page.tsx
        │   ├── model-viewer.tsx
        │   ├── thread-graph.tsx
        │   └── layer-controls.tsx
        ├── bom/
        │   ├── bom-page.tsx
        │   ├── bom-table.tsx
        │   ├── bom-risk-panel.tsx
        │   └── alternate-parts-dialog.tsx
        ├── compliance/
        │   ├── compliance-page.tsx
        │   ├── market-tab.tsx
        │   ├── regime-card.tsx
        │   └── evidence-checklist.tsx
        ├── testing/
        │   ├── testing-page.tsx
        │   ├── test-coverage-chart.tsx
        │   ├── fmea-table.tsx
        │   └── test-run-history.tsx
        ├── supply-chain/
        │   ├── supply-chain-page.tsx
        │   ├── risk-heatmap.tsx
        │   ├── eol-warnings.tsx
        │   └── price-trend-chart.tsx
        ├── approvals/
        │   ├── approvals-page.tsx
        │   ├── approval-card.tsx
        │   └── diff-viewer.tsx
        └── settings/
            ├── settings-page.tsx
            ├── workspace-settings.tsx
            └── connection-status.tsx

Quick Start

Prerequisites

  • Node.js 20+ and npm 10+
  • A running MetaForge Gateway Service (or use mock mode)

Install and Run

cd dashboard
npm install

Development with mock data (no backend required):

VITE_MOCK_API=true npm run dev

Development against a live Gateway:

VITE_API_URL=http://localhost:3000 npm run dev

The dashboard will start at http://localhost:5173.

Build for Production

npm run build
npm run preview   # preview the production build locally

Documentation Files

Each page below contains complete, production-ready source code for its section of the dashboard.

File Description
setup.md Project configuration: package.json, tsconfig, Vite config, index.html, CSS theme, entry points
types.md All TypeScript type definitions (sessions, agents, BOM, compliance, approvals, etc.)
lib.md Utility functions: cn() helper, constants, color maps, formatting utilities
api-client.md Axios client setup, request/response interceptors, error handling
stores.md Zustand stores for theme, session state, notifications, WebSocket connection
hooks.md TanStack Query hooks for data fetching and WebSocket subscriptions
routing.md React Router v7 route configuration and lazy loading strategy
mock-data.md MSW handlers and mock data factories for standalone development
components-ui.md shadcn/ui primitives: Button, Card, Dialog, Table, Tabs, etc.
components-layout.md Root layout, sidebar navigation, header, breadcrumbs, toaster
components-shared.md Reusable components: StatusBadge, DataTable, MetricCard, ErrorBoundary
page-overview.md Overview dashboard: gate readiness, session activity, agent status grid
page-sessions.md Session list and detail pages with trace viewer
page-agents.md Agent monitoring grid with status indicators and detail panels
page-digital-twin.md 3D model viewer with digital thread graph and layer controls
page-bom.md Bill of Materials table with risk analysis and alternate parts
page-compliance.md Compliance tracking across UKCA, CE, and FCC markets
page-testing.md Test coverage, FMEA table, and test run history
page-supply-chain.md Supply chain risk heatmap, EOL warnings, price trends
page-approvals.md Approval queue with diff viewer and comment threads
page-settings.md Workspace settings and Gateway connection status
chat-channel.md Agent Chat Channel — real-time conversational interface with domain agents

Pages Overview

The dashboard is organized into 10 pages, each mapped to a route:

Page Route Description
Overview / High-level dashboard with gate readiness scores, recent session activity, and agent status grid
Sessions /sessions, /sessions/:id List of orchestration sessions with filters; detail view shows trace timeline and artifacts
Agents /agents Grid of all registered agents with live status, current workload, and capability details
Digital Twin /digital-twin 3D model viewer (React Three Fiber) with digital thread graph overlay and layer toggle controls
BOM /bom Interactive bill of materials table with lifecycle risk scores, alternate parts lookup, and cost roll-up
Compliance /compliance Tabbed view by market (UKCA/CE/FCC) showing regime progress, evidence checklists, and submission status
Testing /testing Test coverage visualization, FMEA risk priority table, and historical test run results
Supply Chain /supply-chain Supply chain risk heatmap, end-of-life warnings, distributor stock levels, and price trend charts
Approvals /approvals Pending approval queue for human-in-the-loop decisions with file diffs and comment threads
Chat (sidebar overlay) Persistent chat sidebar and contextual panels for real-time conversations with domain agents
Settings /settings Workspace configuration, API connection status, theme toggle, and system health indicators

Integration Notes

Gateway API

The dashboard communicates with the MetaForge Gateway Service over REST and WebSocket:

  • Base URL: Configured via VITE_API_URL environment variable (defaults to http://localhost:3000)
  • API prefix: All REST endpoints are under /api/v1/
  • Authentication: Bearer token passed via Authorization header (token management handled by the Gateway)

WebSocket

  • URL: ws://localhost:3000/ws (configurable via VITE_WS_URL)
  • Events: Session progress, agent status changes, BOM updates, test completions
  • Reconnection: Automatic with exponential backoff (1s, 2s, 4s, 8s, max 30s)

Mock Mode

When VITE_MOCK_API=true is set:

  • MSW service worker intercepts all /api/* requests
  • Realistic mock data is returned with configurable delays
  • WebSocket events are simulated on timers
  • No backend services are required

This enables frontend development to proceed independently of backend availability.

flowchart LR
    subgraph Dashboard["Dashboard (Vite + React)"]
        A[React Components] --> B[TanStack Query]
        B --> C{Mock Mode?}
    end

    C -->|Yes| D[MSW Service Worker]
    D --> E[Mock Handlers + Data]

    C -->|No| F[Axios Client]
    F --> G[Gateway Service<br/>HTTP :3000]
    F --> H[WebSocket<br/>WS :3000/ws]

    style Dashboard fill:#f0f4ff,stroke:#4a6fa5
    style D fill:#fff3e0,stroke:#f57c00
    style G fill:#e8f5e9,stroke:#388e3c