open-notebook/frontend/src/CLAUDE.md

Frontend Architecture

Next.js React application providing UI for Open Notebook research assistant. Three-layer architecture: pages (Next.js App Router), components (feature-specific UI), and lib (data fetching, state management, utilities).

High-Level Data Flow

Pages (Next.js) → Components (feature-specific) → Hooks (queries/mutations)
                                                       ↓
                          Stores (auth/modal state) → API module → Backend

User interactions trigger mutations/queries via hooks, which communicate with the backend through the API module. Store state (auth, modals) flows back to components via hooks. Child CLAUDE.md files document specific modules in detail:

• lib/api/CLAUDE.md: Axios client, FormData handling, interceptors
• lib/hooks/CLAUDE.md: TanStack Query wrappers, SSE streaming, context building
• lib/stores/CLAUDE.md: Zustand auth/modal state, localStorage persistence
• lib/locales/CLAUDE.md: Internationalization (i18n) system, translation files
• components/ui/CLAUDE.md: Radix UI primitives, CVA styling, accessibility

Architectural Layers

Pages (src/app/) — Next.js App Router

• (auth)/login: Authentication entry point
• (dashboard)/: Protected routes (notebooks, sources, search, models, etc.)
• Directory-based routing; each page.tsx is a route endpoint
• Key pattern: Pages call hooks to fetch data, render components with state
• Router groups (auth), (dashboard) organize routes by feature without affecting URL

Components (src/components/) — Feature-Specific UI

• layout: AppShell.tsx, AppSidebar.tsx — main layout wrapper used by all pages
• providers: ThemeProvider, QueryProvider, ModalProvider — app-wide context setup
• auth: LoginForm.tsx — authentication UI
• common: CommandPalette, ErrorBoundary, ContextToggle, ModelSelector — shared across pages
• ui: Reusable Radix UI building blocks (see child CLAUDE.md)
• source, notebooks, search, podcasts: Feature-specific components consuming hooks

Component composition pattern: Pages → Feature components → UI components. Feature components handle page-level state (loading, error), UI components remain stateless and styled.

Lib (src/lib/) — Data & State Layer

lib/api/ — Backend Communication

• client.ts: Central Axios instance with auth interceptor, FormData handling, 10-min timeout
• query-client.ts: TanStack Query configuration
• Resource modules (sources.ts, chat.ts, notebooks.ts, etc.): Endpoint-specific functions returning typed responses
• Pattern: All requests go through apiClient; auth token auto-added from localStorage

lib/hooks/ — React Query + Custom Logic

• Query hooks: useNotebookSources, useSources, useSource — TanStack Query wrappers with cache keys
• Mutation hooks: useCreateSource, useUpdateSource, useDeleteSource — mutations with toast feedback + cache invalidation
• Complex hooks: useNotebookChat, useSourceChat — session management, message streaming, context building
• SSE streaming: useAsk — parses newline-delimited JSON from backend for multi-stage workflows
• Pattern: Hooks return { data, isLoading, error, refetch } + action functions; cache invalidation on mutations

lib/stores/ — Application State

• auth-store.ts: Authentication state (token, isAuthenticated) with 30-second check caching
• Zustand + persist middleware: Auto-syncs sensitive state to localStorage
• Pattern: Store actions (login(), logout(), checkAuth()) update state; consumed via hooks in components

lib/types/ — TypeScript Definitions

• API request/response shapes, domain models (Notebook, Source, Note, etc.)
• Ensures type safety across API calls and store mutations

lib/locales/ — Internationalization (i18n)

• Locale files (en-US/, pt-BR/, zh-CN/, zh-TW/, ja-JP/): Translation strings organized by feature
• i18n.ts: i18next configuration with language detection
• use-translation.ts: Custom hook with Proxy-based t.section.key access pattern
• Pattern: Components call useTranslation() hook; access strings via t.common.save, t.notebooks.title

Data & Control Flow Walkthrough

Example: Notebook Chat

1. Page (notebooks/[id]/page.tsx) fetches initial data, passes notebookId to ChatColumn component
2. Hook call (useNotebookChat()):
   • Queries sessions for notebook via TanStack Query
   • Sets up message state + context building logic
   • Returns { messages, sendMessage(), setModelOverride() }
3. Component renders: ChatColumn displays messages, text input
4. User sends message: Component calls sendMessage() hook
5. Hook execution:
   • Builds context from selected sources/notes via buildContext() helper
   • Calls chatApi.sendMessage() (from API module)
   • Client-side optimistic update: adds message to local state before response
6. Backend response arrives, TanStack Query updates cache
7. Cache invalidation on other source/note mutations ensures stale UI refreshes

Example: File Upload with Source Creation

1. Component (SourceDialog) renders form with file picker
2. Hook (useFileUpload):
   • Converts file to FormData (JSON fields stringified)
   • Calls sourcesApi.create() with FormData
   • API client interceptor deletes Content-Type header (lets browser set multipart boundary)
3. Toast notifications show progress
4. Cache invalidation on success: queryClient.invalidateQueries(['sources'])
5. Related queries auto-refetch: notebooks, sources list, etc.

Key Patterns & Cross-Layer Coordination

Caching & Invalidation

• Query keys: QUERY_KEYS.notebook(id), QUERY_KEYS.sources(notebookId) — hierarchical structure
• Broad invalidation: ['sources'] invalidates all source queries; trade-off between accuracy + performance
• Auto-refetch: refetchOnWindowFocus: true on frequently-changing data (sources, notebooks)

Auth & Protected Routes

• Proxy (src/proxy.ts): Redirects root / to /notebooks
• Auth store: Validates token via /notebooks API call (actual validation, not JWT decode)
• Interceptor: Adds Bearer {token} to all requests; 401 response clears auth and redirects to login

Modal State Management

• Modal hooks: Components query modal state from stores
• Context: Modals pass data (e.g., notebook ID) to child components
• Pattern: One store per modal type; triggered by button clicks + data passing via hook arguments

Error Handling

• API errors: All request failures propagate to consuming code; components show toast notifications
• Toast feedback: Mutations show success/error toasts (from sonner library)
• Error boundary: App-level error boundary catches React render errors; shows fallback UI

FormData Handling

• JSON fields: Nested objects (arrays, objects) must be JSON stringified before FormData
• Content-Type header: Removed by interceptor for FormData requests (lets browser set boundary)
• Example: sources array converted to string via JSON.stringify() before appending to FormData

Component Organization Within Features

• Feature folders (source/, notebooks/, podcasts/): Group related components
• Composition: Larger components nest smaller ones; no deep prop drilling (state lifted to hooks)
• Dialog patterns: Features define dialog components for inline actions (edit, create, delete)
• Props: Components accept data + action callbacks from parent or hooks

Providers & Context Setup

Root layout (app/layout.tsx) wraps app with (outermost → innermost):

1. ErrorBoundary — React error boundary (catches all render errors)
2. ThemeProvider — next-themes for light/dark mode
3. QueryProvider — TanStack Query client
4. I18nProvider — i18next initialization and language loading overlay
5. ConnectionGuard — checks backend connectivity on startup
6. Toaster — sonner toast notification system (inside ConnectionGuard)

Important Gotchas & Design Decisions

• Token storage: Stored in localStorage under auth-storage key (Zustand persist); consumed by API interceptor
• Base URL discovery: API client fetches base URL from runtime config on first request (async; can be slow on startup)
• Optimistic updates: Chat messages added to state before server confirmation; removed on error
• Modal lifecycle: Dialogs not auto-reset; parent must clear form state after submit
• Focus management: Dialog auto-focuses first input; can cause layout shifts if inputs are conditional
• Cache invalidation breadth: Trade-off between precision + simplicity; broad invalidation simpler but may over-fetch

How to Add a New Feature

1. Create page: app/(dashboard)/feature/page.tsx — calls hooks, renders components
2. Create feature components: components/feature/ — compose UI + business logic
3. Add hooks (if data needed): lib/hooks/useFeature.ts — TanStack Query wrapper
4. Add API module (if backend call needed): lib/api/feature.ts — resource-specific functions
5. Add types: lib/types/api.ts — request/response shapes
6. Use UI components: Import from components/ui/ for consistent styling
7. Handle auth: Middleware redirects unauthenticated users; no special handling needed in component

Testing

• Hooks: Mock API functions, wrap in QueryClientProvider, assert query/mutation behavior
• Components: Mock hooks via vi.fn(), test rendering + user interactions
• API calls: Mock axios interceptors; test request/response shapes
• Stores: Mock store state, test mutations via act(), assert state changes

See child CLAUDE.md files for module-specific testing patterns.