Next.js WebUI
Relevant source files
The following files were used as context for generating this wiki page:
The Next.js WebUI is the primary web-based client for the tldw_server ecosystem. It is designed as a thin wrapper around a shared UI package, providing a responsive and interactive interface for media ingestion, AI-powered research, and content management. It serves as the browser-based counterpart to the project's browser extension, maintaining feature parity through a monorepo architecture that shares core logic and components.
The WebUI supports dual operating modes: a single-user mode utilizing static API keys and a multi-user mode featuring JWT-based authentication and profile management. It integrates deeply with the FastAPI backend to provide real-time streaming for chat, RAG (Retrieval-Augmented Generation) search, and media processing workflows.
Sources: apps/tldw-frontend/CLAUDE.md:5-10, Docs/Architecture.md:12-18, apps/tldw-frontend/README.md:118-124
Architecture and Monorepo Integration
The WebUI is part of a Bun workspace monorepo. It acts as a specialized consumer of the shared UI library located in packages/ui/src/. This architecture ensures that complex business logic, state management, and UI components are written once and used across both the web application and the browser extension.
Core Structure
The frontend is organized to separate web-specific concerns from shared domain logic:
apps/tldw-frontend/pages/: Contains Next.js routes. These are typically "thin wrappers" that dynamically import shared route components.packages/ui/src/: The core repository for shared components, hooks, services, and Zustand stores.apps/tldw-frontend/extension/shims/: Provides compatibility layers that allow shared code (originally designed for browser extensions) to run in a standard web environment.
Sources: apps/tldw-frontend/CLAUDE.md:12-25, apps/DEVELOPMENT.md:31-60
Dependency and Data Flow
The WebUI follows a specific flow where Next.js pages act as entry points that initialize shared services and stores.
Explanation: This diagram shows how the Next.js frontend wraps shared UI logic and uses shims to bridge the gap between extension-style APIs and standard web APIs before communicating with the backend.
Sources: apps/tldw-frontend/CLAUDE.md:27-44, apps/DEVELOPMENT.md:115-135
Key Implementation Patterns
SSR Disablement
A critical architectural constraint of the WebUI is the disablement of Server-Side Rendering (SSR) for most shared components. Because the shared UI code utilizes browser-specific APIs (such as window, localStorage, and IndexedDB/Dexie), pages must be loaded dynamically on the client side.
// Example of a typical WebUI page wrapper
import dynamic from "next/dynamic"
export default dynamic(() => import("@/routes/my-feature-page"), { ssr: false })
Sources: apps/tldw-frontend/CLAUDE.md:65-72, apps/tldw-frontend/AGENTS.md:71-78
Browser API Shimming
To maintain a single codebase for the extension and web, the project utilizes shims to redirect extension-specific calls to web equivalents:
wxt-browser.ts: Mapsbrowser.storage.localcalls to standardlocalStorage.react-router-dom.tsx: Maps React Router components (Link,useNavigate) to Next.js routing (next/link,useRouter).
Sources: apps/tldw-frontend/CLAUDE.md:74-90, apps/DEVELOPMENT.md:162-180
Authentication and Configuration
The WebUI supports flexible environment-based configuration and two primary authentication strategies.
Environment Variables
| Variable | Description | Default |
|---|---|---|
NEXT_PUBLIC_API_URL | The base URL of the FastAPI backend. | http://127.0.0.1:8000 |
NEXT_PUBLIC_X_API_KEY | API key for single-user mode. | (Optional) |
NEXT_PUBLIC_API_VERSION | Backend API version. | v1 |
NEXT_PUBLIC_DEPLOYMENT_MODE | Set to advanced for custom-host networking. | quickstart |
Sources: apps/tldw-frontend/README.md:32-48, apps/tldw-frontend/CLAUDE.md:166-175
Auth Modes
- Single-User Mode: Utilizes the
NEXT_PUBLIC_X_API_KEY. The frontend sends this in theX-API-KEYheader for all requests, bypassing traditional login flows. - Multi-User Mode: Implements a standard JWT flow. Users authenticate via
/login, tokens are managed inlib/auth.ts, and user state is fetched from the/api/v1/users/meendpoint.
Sources: apps/tldw-frontend/README.md:118-124, apps/tldw-frontend/CLAUDE.md:92-108
Navigation and Feature Surfaces
The WebUI exposes several specialized routes and integrated tools:
- Main Dashboard (
/): Central hub for chat and activity. - Media Workspace (
/media): Interface for managing, searching, and inspecting ingested content. - Presentation Studio (
/presentation-studio): Surface for generating and editing slides/video presentations. - Repo2txt (
/repo2txt): Specialized tool for converting code repositories into text formats for LLM ingestion. - Profile (
/profile): Displays user identity, usage counters, and permissions.
Sources: apps/tldw-frontend/README.md:78-100, apps/tldw-frontend/Release_Checklist.md:105-110
Tutorial and Help System
The WebUI includes a contextual tutorial system built with React Joyride and a unified Help Modal.
The tutorial system is route-aware, meaning it only displays guides relevant to the user's current page. Completion status is persisted in a Zustand store (store/tutorials.ts) and backed by localStorage under the key tldw-tutorials.
Sources: Docs/Published/Code_Documentation/Tutorial_System_Developer_Guide.md:65-80
Development and Testing
Build Profiles
The WebUI uses branch-aware build profiles to optimize for different environments:
- Production (
mainbranch): Forces the "quickstart" path, optimized for the standard Docker deployment. - Development (other branches): Forces the "advanced" path to allow for custom API host configurations during local feature development.
Sources: apps/tldw-frontend/README.md:60-72
Verification Gates
Before release, the frontend must pass a series of Playwright-based "UX Gate" tests:
- Interaction Gate: Validates theme-toggle discoverability and template leak guards.
- Audio Gate: Checks runtime budgets for TTS/STT and ElevenLabs metadata recovery.
- Smoke Gate: Ensures zero uncaught page errors across all primary routes.
Sources: apps/tldw-frontend/README.md:148-165
Summary
The Next.js WebUI provides a robust, professional-grade interface for the tldw_server platform. By leveraging a monorepo architecture and sophisticated shimming techniques, it maintains high feature parity with the browser extension while providing web-specific optimizations like JWT authentication and responsive layouts. Its integration of contextual tutorials and strict automated UX testing ensures a reliable experience for researchers and power users.
Sources: apps/tldw-frontend/CLAUDE.md:5-15, apps/tldw-frontend/README.md:148-155