My Repositories
++ A collection of repositories showcasing various technologies and projects +
+diff --git a/CLAUDE.md b/CLAUDE.md index 2b51254..783a84f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,482 +1,64 @@ -# CLAUDE.md - CodeGuide Starter Kit Lite v2 +# Claude Code Task Management Guide -This file contains essential context about the project structure, technologies, and conventions to help Claude understand and work effectively within this codebase. +## Documentation Available -## Project Overview +📚 **Project Documentation**: Check the documentation files in this directory for project-specific setup instructions and guides. +**Project Tasks**: Check the tasks directory in documentation/tasks for the list of tasks to be completed. Use the CLI commands below to interact with them. -**CodeGuide Starter Kit Lite v2** is a modern Next.js starter template featuring authentication, database integration, AI capabilities, and a comprehensive UI component system. +## MANDATORY Task Management Workflow -### 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: +🚨 **YOU MUST FOLLOW THIS EXACT WORKFLOW - NO EXCEPTIONS** 🚨 +### **STEP 1: DISCOVER TASKS (MANDATORY)** +You MUST start by running this command to see all available tasks: ```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-... +task-manager list-tasks ``` -## 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 -
+ A collection of repositories showcasing various technologies and projects +
+