This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

• npm run dev - Start development server at http://localhost:3000
• npm run build - Build the application for production
• npm run start - Start production server
• npm run lint - Run ESLint checks

This is a collaborative document editor built with Next.js 14, similar to Google Docs, featuring real-time collaboration capabilities.

• Next.js 14 with App Router and TypeScript
• Liveblocks for real-time collaboration, presence, and document synchronization
• Lexical as the rich text editor framework
• Clerk for authentication and user management
• Tailwind CSS with custom design system
• Sentry for error monitoring

• Liveblocks Provider (app/Provider.tsx) wraps the entire app to enable real-time features
• Room-based Architecture: Each document is a Liveblocks "room" with unique roomId
• Presence System: Real-time cursors, active collaborators, and user awareness
• Conflict-free Collaboration: Automatic conflict resolution for simultaneous edits

• Clerk Integration: Handles sign-in/sign-up flows in app/(auth)/ routes
• User-based Access Control: Three permission levels defined in types/index.d.ts:
  • creator: Full document ownership and management rights
  • editor: Can edit document content and title
  • viewer: Read-only access with commenting abilities
• Liveblocks Auth Endpoint: /api/liveblocks-auth/route.ts validates user sessions

• Server Actions in lib/actions/room.actions.ts handle all document CRUD operations
• Room Metadata stores document info (title, creator, email)
• Access Management: Dynamic permission granting/revoking for collaborators
• Notification System: Automated notifications for document sharing and mentions

• CollaborativeRoom (components/CollaborativeRoom.tsx): Main document editing interface
• Editor (components/editor/Editor.tsx): Lexical-based rich text editor with Liveblocks integration
• Header with real-time document title editing and collaborator management
• ShareModal for inviting collaborators with role-based permissions

• ActiveCollaborators: Shows live presence indicators for current users
• Comments System: Threaded commenting with mentions and notifications
• FloatingToolbar: Context-aware toolbar for text selection and commenting
• Notifications: Inbox system for document access and mention alerts

1. Authentication: Clerk handles user auth, Liveblocks validates via auth endpoint
2. Document Access: Server actions check user permissions before room entry
3. Real-time Sync: Liveblocks automatically syncs editor state across all clients
4. Collaboration: Lexical + Liveblocks handle operational transforms for conflict resolution
5. Persistence: Document state auto-saves to Liveblocks cloud storage

Required environment variables:

# Clerk Authentication
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=
CLERK_SECRET_KEY=
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up

# Liveblocks Collaboration
NEXT_PUBLIC_LIVEBLOCKS_PUBLIC_KEY=
LIVEBLOCKS_SECRET_KEY=

• Dark Theme: Primary UI uses custom dark color palette defined in tailwind.config.ts
• Component Overrides: Extensive Liveblocks and Clerk component styling in globals.css
• Responsive Design: Mobile-first approach with custom breakpoints

• app/ - Next.js App Router pages and API routes
• components/ - Reusable UI components organized by feature
• lib/actions/ - Server actions for data mutations
• lib/utils.ts - Shared utility functions and helpers
• types/index.d.ts - TypeScript type definitions
• public/assets/ - Static assets (icons, images)