Dashboard

Dashboard

The Mappers Dashboard (apps/dashboard/) is a single-page application that provides real-time visibility into escrow jobs, oracle health, and aggregate protocol statistics.

---

Tech Stack

Layer	Technology
Build tool	Vite
UI framework	React 19
Data fetching	TanStack Query (React Query)
Component library	shadcn/ui
Styling	Tailwind CSS
Type safety	TypeScript + generated Zod schemas
API client	@workspace/api-client-react (auto-generated hooks)

---

Features

Job Overview

The main view displays all escrow jobs with:

• Job ID and wallet addresses (truncated with copy-to-clipboard)
• Status badges (pending, completed, cancelled) with color coding
• Escrowed amount formatted in SOL
• Creation and last update timestamps

Jobs can be filtered by status and client address.

Job Details

Clicking a job shows full metadata:

• Complete wallet addresses (client, freelancer, oracle)
• Exact lamport amount and SOL equivalent
• Transaction signature (linked to Solana Explorer when available)
• Full description and acceptance criteria
• State transition history via timestamps

Statistics Dashboard

Aggregate view showing:

• Total jobs registered
• Breakdown by status (pending / completed / cancelled)
• Total SOL currently in escrow
• Oracle health status

Oracle Health

Live indicator showing whether the AI oracle middleware is reachable and how many jobs are in its pending queue.

---

Running Locally

Development

cd apps/dashboard
pnpm run dev

Opens at http://localhost:5173. Hot-reloads on file changes.

Production Build

cd apps/dashboard
pnpm run build    # Outputs to dist/
pnpm run serve    # Preview the production build

Configuration

Variable	Default	Description
PORT	5173	Dev server port
BASE_PATH	/	Base path for deployment behind a reverse proxy

---

Architecture

Dashboard (React 19)
    |
    | uses hooks from @workspace/api-client-react
    |   (generated by orval from the OpenAPI spec)
    v
Custom Fetch Layer (lib/api-client-react/src/custom-fetch.ts)
    |
    | setBaseUrl() configures the target
    | setAuthTokenGetter() adds bearer tokens (for mobile/Expo)
    v
API Server (Express 5)

Generated Hooks

The dashboard uses auto-generated TanStack Query hooks. These are created by orval from the OpenAPI spec in lib/api-spec/:

// Available hooks (from @workspace/api-client-react):
useHealthCheck()
useListJobs(params?)
useGetJob(jobId)
useCreateJob()
useUpdateJob(jobId)
useSubmitDeliverable(jobId)
useGetStats()
useGetOracleHealth()

Each hook provides:

• Automatic caching and background refetching
• Loading and error states
• Type-safe request/response types
• Optimistic updates where applicable

Custom Fetch

The customFetch function (in lib/api-client-react/src/custom-fetch.ts) handles:

• Base URL resolution (for cross-origin deployments)
• Bearer token injection (for mobile/Expo apps)
• Response parsing (JSON, text, blob)
• Error normalization (all errors become ApiError instances)

---

Component Structure

src/
|-- App.tsx                    Main app with routing and layout
|-- components/
|   |-- job-card.tsx           Individual job display card
|   |-- status-badge.tsx       Colored status indicator
|   |-- ui/                    shadcn/ui primitive components
|-- lib/
|   |-- format.ts             Formatting utilities (lamports, pubkeys, dates)

Utility Functions

// lib/format.ts

// Format lamports to SOL with locale-aware separators
formatLamports("5000000000")  // "5.00"
formatLamports("123456789012345678")  // "123,456,789.0123"

// Truncate a public key for display
truncatePubkey("7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU")
// "7xKX...AsU"

// Format ISO date to locale string
formatDate("2026-01-15T10:30:00.000Z")
// "1/15/2026, 10:30:00 AM"

---

Development Tips

Adding a new API endpoint to the dashboard:

1. Add the endpoint to the OpenAPI spec in lib/api-spec/
2. Run cd lib/api-spec && pnpm run codegen to regenerate hooks
3. Import and use the new hook in your component:

   import { useMyNewEndpoint } from "@workspace/api-client-react";

Adding a new UI component:

• shadcn/ui components live in src/components/ui/
• Business logic components go in src/components/
• Follow existing patterns for consistency

Connecting to a different API server:

import { setBaseUrl } from "@workspace/api-client-react";
setBaseUrl("https://api.mappers.example.com");

---

See Getting Started to run the full stack, or the API Reference for the endpoints the dashboard consumes.