# CLAUDE.md - CodeGuide Starter Kit This file contains essential context about the project structure, technologies, and conventions to help Claude understand and work effectively within this codebase. ## Project Overview **CodeGuide Starter Kit** is a modern Next.js starter template featuring authentication, database integration, AI capabilities, and a comprehensive UI component system. ### Core Technologies - **Framework**: Next.js 15 with App Router (`/src/app` directory structure) - **Language**: TypeScript with strict mode enabled - **Styling**: TailwindCSS v4 with CSS custom properties - **UI Components**: shadcn/ui (New York style) with Lucide icons - **Authentication**: Clerk with middleware protection - **Database**: Supabase with third-party auth integration - **AI Integration**: Vercel AI SDK with support for Anthropic Claude and OpenAI - **Theme System**: next-themes with dark mode support ## Project Structure ``` src/ ├── app/ # Next.js App Router │ ├── api/ # API routes │ │ └── chat/ # AI chat endpoint │ ├── globals.css # Global styles with dark mode │ ├── layout.tsx # Root layout with providers │ └── page.tsx # Home page with status dashboard ├── components/ │ ├── ui/ # shadcn/ui components (40+ components) │ ├── chat.tsx # AI chat interface │ ├── setup-guide.tsx # Configuration guide │ ├── theme-provider.tsx # Theme context provider │ └── theme-toggle.tsx # Dark mode toggle components ├── lib/ │ ├── utils.ts # Utility functions (cn, etc.) │ ├── supabase.ts # Supabase client configurations │ ├── user.ts # User utilities using Clerk │ └── env-check.ts # Environment validation └── middleware.ts # Clerk authentication middleware ``` ## Key Configuration Files - **package.json**: Dependencies and scripts - **components.json**: shadcn/ui configuration (New York style, neutral colors) - **tsconfig.json**: TypeScript configuration with path aliases (`@/`) - **.env.example**: Environment variables template - **SUPABASE_CLERK_SETUP.md**: Integration setup guide ## Authentication & Database ### Clerk Integration - Middleware protects `/dashboard(.*)` and `/profile(.*)` routes - Components: `SignInButton`, `SignedIn`, `SignedOut`, `UserButton` - User utilities in `src/lib/user.ts` use `currentUser()` from Clerk ### Supabase Integration - **Client**: `createSupabaseServerClient()` for server-side with Clerk tokens - **RLS**: Row Level Security uses `auth.jwt() ->> 'sub'` for Clerk user IDs - **Example Migration**: `supabase/migrations/001_example_tables_with_rls.sql` #### Supabase Client Usage Patterns **Server-side (Recommended for data fetching):** ```typescript import { createSupabaseServerClient } from "@/lib/supabase" export async function getServerData() { const supabase = await createSupabaseServerClient() const { data, error } = await supabase .from('posts') .select('*') .order('created_at', { ascending: false }) if (error) { console.error('Database error:', error) return null } return data } ``` **Client-side (For interactive operations):** ```typescript "use client" import { supabase } from "@/lib/supabase" import { useAuth } from "@clerk/nextjs" function ClientComponent() { const { getToken } = useAuth() const fetchData = async () => { const token = await getToken() // Pass token manually for client-side operations const { data, error } = await supabase .from('posts') .select('*') .auth(token) return data } } ``` ## UI & Styling ### TailwindCSS Setup - **Version**: TailwindCSS v4 with PostCSS - **Custom Properties**: CSS variables for theming - **Dark Mode**: Class-based with `next-themes` - **Animations**: `tw-animate-css` package included ### shadcn/ui Components - **Style**: New York variant - **Theme**: Neutral base color with CSS variables - **Icons**: Lucide React - **Components Available**: 40+ UI components (Button, Card, Dialog, etc.) ### Theme System - **Provider**: `ThemeProvider` in layout with system detection - **Toggle Components**: `ThemeToggle` (dropdown) and `SimpleThemeToggle` (button) - **Persistence**: Automatic theme persistence across sessions ## AI Integration ### Vercel AI SDK - **Endpoint**: `/api/chat/route.ts` - **Providers**: Anthropic Claude and OpenAI support - **Chat Component**: Real-time streaming chat interface - **Authentication**: Requires Clerk authentication ## Development Conventions ### File Organization - **Components**: Use PascalCase, place in appropriate directories - **Utilities**: Place reusable functions in `src/lib/` - **Types**: Define alongside components or in dedicated files - **API Routes**: Follow Next.js App Router conventions ### Import Patterns ```typescript // Path aliases (configured in tsconfig.json) import { Button } from "@/components/ui/button" import { getCurrentUser } from "@/lib/user" import { supabase } from "@/lib/supabase" // External libraries import { useTheme } from "next-themes" import { SignedIn, useAuth } from "@clerk/nextjs" ``` ### Component Patterns ```typescript // Client components (when using hooks/state) "use client" // Server components (default, for data fetching) export default async function ServerComponent() { const user = await getCurrentUser() // ... } ``` ## Environment Variables Required for full functionality: ```bash # Clerk Authentication NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_... CLERK_SECRET_KEY=sk_test_... # Supabase Database NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ... # AI Integration (optional) OPENAI_API_KEY=sk-... ANTHROPIC_API_KEY=sk-ant-... ``` ## Common Patterns ### Row Level Security (RLS) Policies All database tables should use RLS policies that reference Clerk user IDs via `auth.jwt() ->> 'sub'`. **Basic User-Owned Data Pattern:** ```sql -- Enable RLS on table ALTER TABLE posts ENABLE ROW LEVEL SECURITY; -- Users can read all posts (public) CREATE POLICY "Anyone can read posts" ON posts FOR SELECT USING (true); -- Users can only insert posts as themselves CREATE POLICY "Users can insert own posts" ON posts FOR INSERT WITH CHECK (auth.jwt() ->> 'sub' = user_id); -- Users can only update their own posts CREATE POLICY "Users can update own posts" ON posts FOR UPDATE USING (auth.jwt() ->> 'sub' = user_id); -- Users can only delete their own posts CREATE POLICY "Users can delete own posts" ON posts FOR DELETE USING (auth.jwt() ->> 'sub' = user_id); ``` **Private Data Pattern:** ```sql -- Completely private to each user CREATE POLICY "Users can only access own data" ON private_notes FOR ALL USING (auth.jwt() ->> 'sub' = user_id); ``` **Conditional Visibility Pattern:** ```sql -- Public profiles or own profile CREATE POLICY "Users can read public profiles or own profile" ON profiles FOR SELECT USING ( is_public = true OR auth.jwt() ->> 'sub' = user_id ); ``` **Collaboration Pattern:** ```sql -- Owner and collaborators can access CREATE POLICY "Owners and collaborators can read" ON collaborations FOR SELECT USING ( auth.jwt() ->> 'sub' = owner_id OR auth.jwt() ->> 'sub' = ANY(collaborators) ); ``` ### Database Operations with Supabase **Complete CRUD Example:** ```typescript import { createSupabaseServerClient } from "@/lib/supabase" import { getCurrentUser } from "@/lib/user" // CREATE - Insert new record export async function createPost(title: string, content: string) { const user = await getCurrentUser() if (!user) return null const supabase = await createSupabaseServerClient() const { data, error } = await supabase .from('posts') .insert({ title, content, user_id: user.id, // Clerk user ID }) .select() .single() if (error) { console.error('Error creating post:', error) return null } return data } // READ - Fetch user's posts export async function getUserPosts() { const supabase = await createSupabaseServerClient() const { data, error } = await supabase .from('posts') .select(` id, title, content, created_at, user_id `) .order('created_at', { ascending: false }) if (error) { console.error('Error fetching posts:', error) return [] } return data } // UPDATE - Modify existing record export async function updatePost(postId: string, updates: { title?: string; content?: string }) { const supabase = await createSupabaseServerClient() const { data, error } = await supabase .from('posts') .update(updates) .eq('id', postId) .select() .single() if (error) { console.error('Error updating post:', error) return null } return data } // DELETE - Remove record export async function deletePost(postId: string) { const supabase = await createSupabaseServerClient() const { error } = await supabase .from('posts') .delete() .eq('id', postId) if (error) { console.error('Error deleting post:', error) return false } return true } ``` **Real-time Subscriptions:** ```typescript "use client" import { useEffect, useState } from "react" import { supabase } from "@/lib/supabase" import { useAuth } from "@clerk/nextjs" function useRealtimePosts() { const [posts, setPosts] = useState([]) const { getToken } = useAuth() useEffect(() => { const fetchPosts = async () => { const token = await getToken() const { data } = await supabase .from('posts') .select('*') .auth(token) setPosts(data || []) } fetchPosts() // Subscribe to changes const subscription = supabase .channel('posts-channel') .on('postgres_changes', { event: '*', schema: 'public', table: 'posts' }, (payload) => { fetchPosts() // Refetch on any change } ) .subscribe() return () => { subscription.unsubscribe() } }, [getToken]) return posts } ``` ### Protected Routes Routes matching `/dashboard(.*)` and `/profile(.*)` are automatically protected by Clerk middleware. ### Theme-Aware Components ```typescript // Automatic dark mode support via CSS custom properties <div className="bg-background text-foreground border-border"> <Button variant="outline">Themed Button</Button> </div> ``` ## Development Commands ```bash npm run dev # Start development server with Turbopack npm run build # Build for production npm run start # Start production server npm run lint # Run ESLint ``` ## Best Practices 1. **Authentication**: Always check user state with Clerk hooks/utilities 2. **Database**: Use RLS policies with Clerk user IDs for security 3. **UI**: Leverage existing shadcn/ui components before creating custom ones 4. **Styling**: Use TailwindCSS classes and CSS custom properties for theming 5. **Types**: Maintain strong TypeScript typing throughout 6. **Performance**: Use server components by default, client components only when needed ## Integration Notes - **Clerk + Supabase**: Uses modern third-party auth (not deprecated JWT templates) - **AI Chat**: Requires authentication and environment variables - **Dark Mode**: Automatically applied to all shadcn components - **Mobile**: Responsive design with TailwindCSS breakpoints This starter kit provides a solid foundation for building modern web applications with authentication, database integration, AI capabilities, and polished UI components.