Nexus Dashboard — Next.js 16 BFF for Nexus Core

Open-source web UI that manages Nexus Core (see ../docs/prd/prd-nexus-oss-dashboard.md). Thin Next.js 16 BFF — auth-aware, Core is auth-unaware. Dashboard owns no business tables; all business operations proxy to CORE_API_URL.

• Stack: Next.js 16.3.2 (App Router), React 19, TypeScript, Tailwind 4, server-first
• Contract: ../nexus-contract/nexus-core.yaml is source of truth → src/lib/contracts/types.gen.ts via openapi-typescript
• Auth (PRD F1): single shared password (DASHBOARD_PASSWORD / DASHBOARD_PASSWORD_HASH), httpOnly Secure SameSite=Lax cookie nexus_session with iat/exp sealed by DASHBOARD_SESSION_SECRET (32+ bytes, HS256 via jose), TTL DASHBOARD_SESSION_TTL (12h default), middleware.ts gates all pages + /api/* except /login, /_next/*, /favicon.ico, /api/auth/*
• BFF proxy: CORE_API_URL (e.g. http://core:8080 in compose, http://localhost:8080 locally) — forwards method/path/query/body verbatim via src/lib/core/proxy.ts, streams Core status/body back unchanged with filtered headers (Content-Type, Content-Length, Cache-Control, Content-Encoding); strips Set-Cookie/Authorization/Cookie; maps Core unreachable to 503 { error: { message: "Core unreachable" } }; no business logic duplication

Quick start

cp .env.example .env   # set DASHBOARD_PASSWORD + DASHBOARD_SESSION_SECRET (32+ chars)
npm install
npm run contracts:gen  # generate TS types from ../nexus-contract/nexus-core.yaml
npm run dev            # http://localhost:3000

Preferred config is ~/.nexus/config.yaml (shared with Core, see ../config.example.yaml) — YAML takes precedence over env. DASHBOARD_SESSION_SECRET must also be mirrored to env for Edge middleware.ts (Edge cannot read the filesystem).

Contracts

npm run contracts:lint      # redocly lint ../nexus-contract/nexus-core.yaml
npm run contracts:gen       # openapi-typescript → src/lib/contracts/types.gen.ts
npm run contracts:gen:check # CI drift guard — fails if generated file is stale

• Source: ../nexus-contract/nexus-core.yaml (OpenAPI 3.0.3)
• Generated: src/lib/contracts/types.gen.ts (committed; drift shows in PR diff)
• Never hand-edit types.gen.ts — edit the YAML, then regenerate
• Typed shortcuts: src/lib/contracts/index.ts

Structure

src/
  app/
    layout.tsx, globals.css
    page.tsx                      # root redirect / shell entry
    login/                        # public login (form + server action)
    (shell)/                      # authenticated shell (sidebar + topbar)
      layout.tsx
      api-keys/page.tsx
      sessions/page.tsx
      messaging/
        send/page.tsx
        receive/page.tsx
        media/page.tsx            # placeholder
        delivery/page.tsx         # placeholder
      webhooks/page.tsx
      queue/page.tsx              # placeholder
      developer/
        rest/page.tsx | sdk/page.tsx | cli/page.tsx | examples/page.tsx  # placeholders
      observability/
        metrics/page.tsx          # Prometheus text/plain via BFF → KPI parsing
        logs/page.tsx             # paginated log viewer with filters + drawer
        health/page.tsx           # /api/v1/health checks + status dot grid
    api/
      auth/
        login/route.ts            # sets nexus_session cookie
        logout/route.ts
        me/route.ts
      v1/                         # BFF proxies — each route.ts calls proxyRequest()
        api-keys/… | sessions/… | webhooks/… | observability/… | health | metrics | messages/…
  lib/
    config/
      env.ts                      # backwards-compat wrapper over loader.ts
      loader.ts                   # YAML (~/.nexus/config.yaml) > env precedence
      paths.ts
    auth/
      session.ts | jwt.ts | password.ts  # cookie helpers, HS256 verify, bcrypt
    core/proxy.ts                 # thin proxy — buildForwardHeaders, buildCoreUrl, proxyRequest
    contracts/
      types.gen.ts                # generated — do not edit
      index.ts                    # typed re-exports
    store/                        # client fetch helpers per domain
      api-keys.ts | sessions.ts | messaging.ts | webhooks.ts | observability.ts
  components/
    layout/shell.tsx | sidebar.tsx | topbar.tsx | icons.tsx
    ui/                           # badge, button, card, kpi, health-card, table, drawer, etc.
middleware.ts                     # gates pages + /api/* (PRD F1), Edge-safe HS256 verify

Compose

Dashboard runs alongside Core + Postgres + Redis via docker compose at the repo root (../docker-compose.yml, see ../docs/prd/prd-nexus-oss-dashboard.md#Technical Constraints for target shape).

docker compose up --build        # dashboard http://localhost:3000, core http://localhost:8080
docker compose logs -f dashboard

• Dashboard image builds from ./nexus-dashboard (../docker-compose.yml → dashboard.build); CORE_API_URL=http://core:8080 in compose, http://localhost:8080 locally
• Env/YAML: DASHBOARD_PASSWORD, DASHBOARD_SESSION_SECRET (32+ bytes), DASHBOARD_SESSION_TTL, HOST/PORT — prefer ~/.nexus/config.yaml dashboard.* keys, env is fallback

PRD

• ../docs/prd/prd-nexus-oss-dashboard.md — F1 auth, F2 workspace/api-keys, F3 sessions, F4 messaging, F5 webhooks, F6 queue, F7 dev platform, F8 observability (metrics/health/logs)
• ../design/nexus-oss-dashboard.html — canonical SPA prototype (tokens, shell, sidebar) adapted to Next.js App Router

License

MIT — see LICENSE. Copyright (c) 2026 afikrim.