Library App Architecture

Last verified: 2026-03-02 Target: apps/library Companion: packages/app-library

The Library app (apps/library, port 3000) is the main HappyClient dashboard. It is the primary interface where authenticated users manage their video interview flows, browse respondents, watch videos, and export content. It runs on Vercel (Next.js 15 App Router) and talks to Redis-backed registries and Vercel Blob for storage.

1. Component/Module Overview

2. Primary Data Flow — Viewing a Respondent's Videos

3. Integration Map

Route Architecture

apps/library/app/
├── layout.tsx                          # Root: ClerkProvider, ClientProviders, font
├── _providers/
│   ├── client-providers.tsx            # PostHog, QueryClient, Sentry registration
│   └── server/
│       └── clients.ts                  # getClients() singleton — all server clients
├── (main)/                             # Auth-required routes with sidebar
│   ├── layout.tsx                      # LibraryLayoutShell + AppSidebar
│   ├── page.tsx                        # / — Unified InterviewsView (all tiers)
│   ├── dashboard/
│   │   └── [videoFlowId]/
│   │       ├── page.tsx                # Flow detail — respondent grid
│   │       └── [respondentId]/
│   │           └── page.tsx           # Respondent detail — videos + export
│   ├── review/
│   │   └── [id]/
│   │       ├── layout.tsx              # Minimal header with back button
│   │       └── page.tsx               # ReviewVideoFlowView (in-progress)
│   └── (free)/
│       └── onboarding/
│           ├── page.tsx               # Legacy — redirects to /
│           └── flow/[flowId]/page.tsx # Legacy flow management UI
├── (fullscreen)/
│   └── edit/[flowId]/                 # Flow editor — Hello UI embedded in library
│       ├── layout.tsx
│       └── page.tsx
├── api/                               # External-caller API routes
│   ├── blob/upload/route.ts           # Image upload to Vercel Blob
│   ├── download-video/route.ts        # Video download proxy
│   ├── download-all-videos/route.ts   # Bulk video download (ZIP)
│   ├── download-srt/route.ts          # SRT subtitle download
│   ├── export-raw-clips/route.ts      # Raw clips export
│   ├── correlation/route.ts           # Sentry correlation header
│   └── info/route.ts                  # App version info
├── sign-in/[[...sign-in]]/page.tsx    # Clerk catch-all sign-in
├── select-organization/page.tsx       # Org picker (Clerk)
├── switch-org/page.tsx               # Cross-org redirect helper
└── sso-callback/page.tsx             # Clerk SSO callback

Server Clients (`getClients()`)

The apps/library/app/_providers/server/clients.ts exports a lazy module-scope singleton getClients() that initializes all server-side clients once per worker:

Client	Type	Purpose
`organization`	`OrganizationClient`	Auth checks, org membership
`videoFlow`	`VideoFlowClient`	Flow CRUD operations
`videoProcessingRegistry`	`VideoProcessingRegistry`	Respondent data, video metadata
`videoAnalyticsRegistry`	`VideoAnalyticsRegistry`	View analytics
`recentVideosCacheService`	`RecentVideosCacheService`	Homepage recent videos cache
`organizationRegistry`	`OrganizationRegistry`	Org-level data
`contentIntelligenceRegistry`	`ContentIntelligenceRegistry`	AI evaluation results
`assetRegistry`	`AssetRegistry`	Uploaded asset tracking
`brandAssetsClient`	`BrandAssetsClient`	Logo/image uploads to Blob
`unsplashClient`	`UnsplashApiClient \| null`	Background image search (opt-in)

Convenience re-exports: getVideoProcessingRegistry(), getRecentVideosCache().

Tier Architecture

Plan-gating is enforced server-side at the respondent detail page only. All other pages are open to all authenticated users:

Route	Free plan	Paid plan
`/` (InterviewsView)	✅ Full access	✅ Full access
`/dashboard/[flowId]`	✅ Full access	✅ Full access
`/dashboard/[flowId]/[respondentId]`	✅ Own videos only	✅ All respondents
`/edit/[flowId]`	✅ Full access	✅ Full access
`/review/[id]`	✅ Full access (in-progress)	✅ Full access

See Demo App and Tier Architecture for the @repo/app-library package structure.

Client-Side Providers

ClientProviders wraps the entire app client tree:

PostHogUserProvider — PostHog analytics (identifies user after Clerk auth)
QueryProvider — TanStack Query for client-side data fetching
Sentry registration (useEffect) — wires breadcrumb/error/message capture providers to the client logger

The root layout also includes:

ClerkProvider — Clerk auth context (with localization for password setup)
SentryCorrelation — injects Sentry correlation headers
Toaster — global toast notifications
VercelAnalytics — Vercel web analytics