@derwinjs/dashboard-fallback

Tier-3 hosted Next.js subapp for consumers without a packages/ui/ workspace to embed Derwin's Tier-1/Tier-2 components into. Per ADR-0004, this is the last-resort tier: if your team can embed Derwin's React components directly (Tier 1) or build a thin custom dashboard against @derwinjs/sdk (Tier 2), prefer those. The fallback exists for consumers whose admin stack can't host Derwin's UI directly — Side Piece's Brain-tRPC-coupled admin is the load- bearing example (per ADR-005).

Install

pnpm add @derwinjs/dashboard-fallback
# or:
npm i @derwinjs/dashboard-fallback

Wiring (instrumentation.ts)

The package exports configuration helpers consumers call once at boot, before any route handlers fire. Typical setup in your Next.js app's instrumentation.ts:

import { createClerkAuthAdapter } from '@derwinjs/adapters';
import { configureDashboardApiClient, setDashboardAuthAdapter } from '@derwinjs/dashboard-fallback';

export function register() {
  // 1. Wire the Derwin API client (where the dashboard reads QA tickets from).
  configureDashboardApiClient({
    baseUrl: process.env.DERWIN_API_URL!,
    bearerToken: process.env.DERWIN_API_TOKEN!,
  });

  // 2. Wire the auth adapter (matches QAAuthAdapter SDK contract).
  setDashboardAuthAdapter(
    createClerkAuthAdapter({
      // ...your Clerk config; see packages/adapters/src/auth/clerk.ts
    }),
  );
}

Routes

The Next.js App Router tree lives at app/. Routes are documented in their respective page.tsx files; the load-bearing ones:

| Route | Purpose | | ------------------------------------------ | ------------------------------------------------------ | | / | Project picker (the dashboard's landing) | | /projects/[projectId] | Project overview — open tickets, mode, recent activity | | /projects/[projectId]/tickets/[ticketId] | Single-ticket deep view with audit trail | | /projects/[projectId]/mode | OBSERVE / TICKET_ONLY / AUTHOR / AUTO mode controls | | /projects/[projectId]/policy | Policy editor (risk tiers, classification overrides) | | /projects/[projectId]/profile | ProjectProfile editor (ontology, glossary, surfaces) | | /projects/[projectId]/health | Trust scores + kill-switch states |

Deployment patterns

The Tier-3 fallback supports three distribution shapes:

A — Standalone Next.js deploy (recommended for first-time consumers)

Run the dashboard as its own Next.js app on Vercel/Cloudflare/Fly.io. The package ships its complete Next.js tree (app/, next.config.mjs, tsconfig.json); you wire it via instrumentation.ts and deploy.

# Boot a new Next.js app and use the fallback as the entry tree:
npx create-next-app@latest my-derwin-dashboard --typescript --app
cd my-derwin-dashboard
pnpm add @derwinjs/dashboard-fallback @derwinjs/adapters @derwinjs/sdk
# Replace the generated app/ with re-exports from @derwinjs/dashboard-fallback/app,
# add your instrumentation.ts, deploy.

B — Re-export from your existing Next.js admin app

If you already run a Next.js admin and want to mount Derwin's dashboard at a sub-route (e.g., /qa), import the routes from @derwinjs/dashboard-fallback into a corresponding directory in your app/ tree.

// app/qa/page.tsx
export { default } from '@derwinjs/dashboard-fallback/app/page';

This is Side Piece's pattern — the admin lives at side-piece-admin.vercel.app and Derwin's dashboard mounts at /qa inside it.

C — Hosted service (Sprint 19+ roadmap)

A Vercel-template variant where Derwin runs the dashboard for the consumer at https://qa.<consumer-domain> is on the Sprint 19+ roadmap. Operator-deployed, consumer points DNS at it, no install needed. Out of scope for this version.

Theming

Each consumer gets per-project theming via PROJECT_THEMES. Side Piece is the first registered theme (luxury food / chef-curated palette). To add a theme for a new consumer, edit src/lib/theming/project-themes.ts and contribute the entry back upstream.

import { PROJECT_THEMES } from '@derwinjs/dashboard-fallback';
const sidePieceTheme = PROJECT_THEMES['side-piece'];

For programmatic theming at the route boundary, wrap children in <ProjectThemeProvider>:

import { ProjectThemeProvider } from '@derwinjs/dashboard-fallback';

<ProjectThemeProvider projectId="side-piece">
  {children}
</ProjectThemeProvider>

Required peer packages

The dashboard depends on:

• @derwinjs/sdk — Derwin's contracts (QAAuthAdapter, etc.)
• @derwinjs/adapters — concrete auth/ticket/runner/repo implementations
• @derwinjs/ui — Derwin's shared React components
• @clerk/nextjs — current default auth provider (swap via the auth adapter)
• next — ^15.5.18 (App Router conventions)
• react / react-dom — ^19.2.6

All are listed as dependencies in package.json so a single pnpm add @derwinjs/dashboard-fallback brings the full set.

Versioning

The package follows Derwin's sprint cadence — minor bumps each sprint that touches the dashboard. Sprint 18 (v0.18.0) is the first published version.

See also

• @derwinjs/sdk — contracts
• @derwinjs/adapters — Clerk + Lifeline + GitHub + Anthropic + etc.
• @derwinjs/ui — React component library
• Derwin platform docs: TBD (Sprint 19+ documentation site)