Demo App Architecture

Last verified: 2026-03-07 Target: apps/demo Companion: packages/demo-flow

The demo app (apps/demo) is a standalone Next.js 15 app that runs all product demonstrations without authentication or backend dependencies. It serves as a sandbox for UI exploration, sales demos, design experiments, and the architecture documentation browser.

Module / Component Overview

Primary Data Flow — Hello Onboarding Demo

The hello demo is the most complex interactive flow in the app.

Integration Map

Route Reference

Demo App Structure

apps/demo/
├── app/
│   ├── layout.tsx               # Plus Jakarta Sans font, DemoProviders
│   ├── page.tsx                 # Landing page — section-grouped demo cards
│   ├── providers.tsx            # DemoStateProvider + DemoControlPanel (client)
│   ├── globals.css              # Tailwind v4 styles
│   │
│   ├── hello/                   # Hello onboarding wizard demo
│   │   └── page.tsx             # Full 7-step wizard (client component)
│   ├── library/                 # Library app states
│   │   ├── page.tsx             # Library index (redesign + deprecated tabs)
│   │   ├── interviews/          # Unified interviews view (active redesign)
│   │   ├── interviews-empty/    # Empty state + onboarding nudges
│   │   ├── recordings/          # Video recordings detail
│   │   ├── dashboard/[flowId]/  # Flow dashboard
│   │   │   └── [respondentId]/  # Respondent detail
│   │   ├── free/                # Pre-redesign free tier views (deprecated)
│   │   └── paid/                # Pre-redesign paid tier views (deprecated)
│   │
│   ├── interview/[flowId]/      # BVF interview experience (Welcome→Tips→Questions→ThankYou)
│   ├── bvf-screens/             # Permission screen design exploration (3 variants)
│   ├── review/                  # Collaborative video review (Frame.io-style)
│   ├── video-intelligence/      # AI analysis dashboard
│   │   └── [sessionId]/         # Session detail
│   ├── video-player/            # Video player component demo
│   ├── question-video/          # Animated title cards (Pancarte) demo
│   │
│   ├── architecture/            # Architecture docs browser
│   │   ├── page.tsx             # Index: all docs grouped by category
│   │   ├── [slug]/page.tsx      # Individual doc (rendered Markdown + Mermaid)
│   │   └── _components/
│   │       ├── MarkdownRenderer.tsx  # react-markdown with GFM
│   │       └── MermaidDiagram.tsx   # Client-side Mermaid rendering
│   │
│   ├── nightly-maintenance/     # Nightly pipeline architecture overview
│   ├── health/                  # Health check
│   └── api/                     # API routes
│
├── public/
│   ├── testimonials/            # Static demo video assets
│   ├── fonts/                   # Local font files
│   ├── icons/                   # App icons
│   └── images/                  # Demo images
├── package.json
└── next.config.mjs

Key Characteristics

No Production Authentication

No Clerk, no auth middleware, no session cookies. Demo runs anonymously for anyone with the URL.

DemoStateProvider — Global Mock State

A lightweight React context (@repo/demo-flow/DemoStateContext) provides cross-page demo state:

Persistence: State is read from localStorage on mount and written back on every change. Key: "demo-app-state". This means demo state survives page reloads, which is intentional for consistent demo sessions.

DemoControlPanel — Floating UI Toggle

A cog button fixed to the bottom-right corner expands to a panel for changing isLoggedIn, userName, and tier in real time. Visible on every demo page.

Mock Data Strategy

Architecture Docs Browser

/architecture reads markdown files from docs/architecture/*.md at build time using getAllDocs() from a local _lib/docs utility. The [slug]/page.tsx renders them with react-markdown + remark-gfm and uses mermaid for diagram rendering (client-side).

Sentry Integration (Optional)

The app includes @sentry/nextjs added 2026-02-25. The Sentry DSN is expected in environment variables but silently fails in local development when the variable is absent. This is the only exception to the "no environment variables" rule.

BVF Interview Demo (/interview/[flowId])

The interview demo renders real BVF components (WelcomeScreen, TipsScreen, ThankYouScreen from @repo/app-video-flow/web) with a mock flow config hydrated into the runtime registry via hydrateFlowConfigAtRuntime. The questions step is simulated — it shows a fake camera circle and "Next Question" button instead of actual video recording.

Known limitation: The flow config is built using an any cast to avoid importing @repo/registries/server which pulls in Redis and other server-side dependencies that break Next.js client builds. The mock config is manually constructed to match the shape the screen components expect.

Dependencies

{
  "@repo/app-admin-library": "workspace:*",
  "@repo/app-hello": "workspace:*",
  "@repo/app-library": "workspace:*",
  "@repo/app-video-flow": "workspace:*",
  "@repo/core": "workspace:*",
  "@repo/demo-flow": "workspace:*",
  "@repo/design-system": "workspace:*",
  "@repo/organization-extraction": "workspace:*",
  "@repo/question-video": "workspace:*",
  "@repo/registries": "workspace:*",
  "@repo/video-player": "workspace:*",
  "@repo/video-review": "workspace:*",
  "@sentry/nextjs": "^10.x",
  "mermaid": "^11.x",
  "react-markdown": "^9.x",
  "remark-gfm": "^4.x"
}

@repo/demo-flow — Companion Package

The companion package provides demo-specific infrastructure shared across all demo pages:

Relationship to Production Apps

The demo app does not import from production apps directly. Instead it imports shared package components with mock data:

apps/demo/app/hello/page.tsx         → @repo/app-hello/web (mirrors apps/hello)
apps/demo/app/library/*              → @repo/app-library (mirrors apps/library)
apps/demo/app/interview/[flowId]/    → @repo/app-video-flow/web (mirrors apps/branded-video-flow)
apps/demo/app/video-intelligence/    → @repo/app-admin-library (mirrors apps/admin)

This mirroring pattern ensures that demo pages stay in sync with production UI automatically — since both use the same package components.