squadbase · KT83 · Sep 18, 2025
diff --git a/chat/nextjs/CLAUDE.md b/chat/nextjs/CLAUDE.md
@@ -10,6 +10,29 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 - `npm run start` - Start production server
 - `npm run lint` - Run ESLint for code linting
 
+### Database
+- `npx drizzle-kit generate` - Generate migration files from schema changes
+- `npx drizzle-kit migrate` - Apply migrations to database
+- `npx drizzle-kit push` - Push schema changes directly to database (development)
+- `npx drizzle-kit studio` - Open Drizzle Studio for database management
+
+## Application Overview
+
+This is an AI-powered chat application with project management capabilities, built as a Next.js 15.5.0 starter template. The app features:
+
+### Core Features
+- **Multi-Project Chat Management** - Organize conversations within projects with custom instructions
+- **AI-Powered Conversations** - OpenAI GPT-4o-mini integration with streaming responses
+- **Persistent Chat History** - Database-backed message storage and retrieval
+- **Real-time UI Updates** - Live message streaming and sidebar updates
+- **Project Context Management** - Custom instructions and memory modes per project
+
+### User Experience
+- **Sidebar Navigation** - Collapsible project and thread organization
+- **Responsive Design** - Mobile-friendly interface with Tailwind CSS
+- **Thread Management** - Create, delete, and organize conversations
+- **Project Settings** - Configure AI behavior and memory preferences
+
 ## Architecture
 
 This is a Next.js 15.5.0 chat application starter template with:
@@ -21,8 +44,21 @@ This is a Next.js 15.5.0 chat application starter template with:
 
 ### Key Directories
 - `/app` - Next.js App Router pages and layouts
+  - `/api/chat` - Chat API endpoint with OpenAI integration
+  - `/api/projects` - Project CRUD operations
+  - `/api/threads` - Thread management endpoints
+  - `/projects/[projectId]` - Project-specific chat pages
+  - `/threads/[id]` - Global thread chat pages
 - `/components/ai-elements` - Pre-built AI chat UI components (messages, prompt input, conversation, etc.)
 - `/components/ui` - shadcn/ui components (button, avatar, dialog, etc.)
+- `/components/thread-sidebar.tsx` - Main navigation sidebar with project/thread management
+- `/contexts` - React context providers for state management
+  - `project-context.tsx` - Current project state
+  - `projects-context.tsx` - All projects state and operations
+  - `thread-context.tsx` - Current thread state and operations
+- `/src/db` - Database layer with Drizzle ORM
+  - `schema.ts` - Database schema definitions
+  - `queries/` - Organized query functions by domain
 - `/lib` - Utility functions including `cn()` for className merging
 - `/hooks` - Custom React hooks
 - `/public` - Static assets served at root URL
@@ -52,6 +88,55 @@ The `/components/ai-elements` directory contains reusable chat UI components:
 - Component styling uses `cn()` utility from `/lib/utils` for conditional classes
 - Dark mode support built-in with Tailwind's dark: modifier
 
+## Data Model & API Endpoints
+
+### Database Schema
+The application uses PostgreSQL with Drizzle ORM and consists of three main entities:
+
+**Projects Table** (`src/db/schema.ts:3-13`)
+- `id` (text, primary key) - Unique project identifier
+- `name` (text, required) - Project display name
+- `description` (text, optional) - Project description
+- `instructions` (text, optional) - Custom AI instructions for the project
+- `memoryMode` (enum: 'project-only' | 'default') - AI memory behavior
+- `createdAt`, `updatedAt` - Timestamps
+
+**Threads Table** (`src/db/schema.ts:15-25`)
+- `id` (text, primary key) - Unique thread identifier
+- `title` (text, required) - Thread display title (auto-generated from first message)
+- `projectId` (text, optional) - Reference to parent project
+- `createdAt`, `updatedAt`, `lastMessageAt` - Timestamps
+
+**Messages Table** (`src/db/schema.ts:27-36`)
+- `id` (text, primary key) - Unique message identifier
+- `threadId` (text, required) - Reference to parent thread
+- `role` (enum: 'user' | 'assistant' | 'system') - Message sender type
+- `content` (text, required) - Message content
+- `createdAt` - Timestamp
+
+### API Routes
+
+**Chat API** (`/api/chat`)
+- `POST` - Send message and stream AI response
+- Supports project-specific instructions and memory modes
+- Auto-generates thread titles from first message
+- Saves all messages to database on completion
+
+**Projects API** (`/api/projects`)
+- `GET` - List all projects
+- `POST` - Create new project
+- `GET /api/projects/[id]` - Get specific project
+- `PUT /api/projects/[id]` - Update project
+- `DELETE /api/projects/[id]` - Delete project
+- `GET /api/projects/[id]/threads` - Get project threads
+
+**Threads API** (`/api/threads`)
+- `GET` - List all threads (global)
+- `POST` - Create new thread
+- `GET /api/threads/[id]` - Get specific thread with messages
+- `PUT /api/threads/[id]` - Update thread
+- `DELETE /api/threads/[id]` - Delete thread
+
 ## Database Stack
 
 ### Database
@@ -139,15 +224,91 @@ The `/components/ai-elements` directory contains reusable chat UI components:
    - Implement proper indexes in your schema
    - Use `select()` with specific columns instead of selecting all
 
-### Dependencies to Install
+### Dependencies Included
+The following packages are already installed for database functionality:
+```json
+{
+  "dependencies": {
+    "@neondatabase/serverless": "^1.0.1",
+    "drizzle-orm": "^0.44.4"
+  },
+  "devDependencies": {
+    "drizzle-kit": "^0.31.4",
+    "dotenv": "^17.2.1"
+  }
+}
+```
+
+## State Management
+
+### Context Providers
+The application uses React Context for state management with three main providers:
+
+**ProjectsProvider** (`contexts/projects-context.tsx`)
+- Manages all projects list and CRUD operations
+- Provides `createProject`, `updateProject`, `deleteProject` functions
+- Handles loading states for project operations
+
+**ProjectProvider** (`contexts/project-context.tsx`)
+- Manages current active project state
+- Handles project-specific routing and navigation
+- Provides current project data to child components
+
+**ThreadProvider** (`contexts/thread-context.tsx`)
+- Manages thread list and current thread state
+- Provides `createNewThread`, `deleteThread` functions
+- Handles both global and project-specific threads
+- Manages message loading and thread navigation
+
+### Component Architecture
+The app follows a hierarchical state management pattern:
+```
+RootLayout
+├── ProjectsProvider (global projects state)
+│   ├── ProjectProvider (current project)
+│   │   ├── ThreadProvider (threads & messages)
+│   │   │   ├── SidebarProvider (UI state)
+│   │   │   │   ├── ThreadSidebar
+│   │   │   │   └── Page Content
+```
+
+## Environment Setup
+
+### Required Environment Variables
+Create a `.env.local` file with:
 ```bash
-npm install drizzle-orm @neondatabase/serverless
-npm install -D drizzle-kit dotenv
+# Neon Database Connection
+DATABASE_URL="postgresql://user:password@ep-hostname.region.aws.neon.tech/neondb?sslmode=require"
+
+# OpenAI API Key
+OPENAI_API_KEY="your-openai-api-key"
 ```
 
-### Common Commands
-- `npx drizzle-kit generate` - Generate migration files
-- `npx drizzle-kit migrate` - Apply migrations
-- `npx drizzle-kit push` - Push schema changes directly (dev)
-- `npx drizzle-kit studio` - Open Drizzle Studio for database management
-- `npx drizzle-kit introspect` - Generate schema from existing database
+### Initial Setup Steps
+1. Clone the repository
+2. Install dependencies: `npm install`
+3. Set up environment variables in `.env.local`
+4. Push database schema: `npx drizzle-kit push`
+5. Start development server: `npm run dev`
+
+## Key Features Implementation
+
+### AI Chat Integration
+- Uses OpenAI GPT-4o-mini model via Vercel AI SDK
+- Supports streaming responses with `streamText`
+- Project-specific system prompts and instructions
+- Memory mode controls (project-only vs default)
+- Automatic message persistence to database
+
+### Project Management
+- Custom instructions per project for AI behavior
+- Memory mode settings (project-only vs default)
+- Project-specific thread organization
+- Settings page for project configuration
+
+### UI Features
+- Collapsible sidebar with project/thread navigation
+- Real-time updates without page refresh
+- Responsive design for mobile and desktop
+- Dark mode support via Tailwind CSS
+- Accessible components via Radix UI primitives
diff --git a/chat/streamlit/.env.example b/chat/streamlit/.env.example
@@ -0,0 +1,7 @@
+# Database Configuration
+# PostgreSQL database URL (e.g., from Neon, Supabase, or local PostgreSQL)
+DATABASE_URL=postgresql://user:password@hostname:port/database_name
+
+# OpenAI Configuration
+# Get your API key from https://platform.openai.com/
+OPENAI_API_KEY=your-openai-api-key-here
diff --git a/chat/streamlit/.gitignore b/chat/streamlit/.gitignore
@@ -0,0 +1,34 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.so
+.venv/
+venv/
+env/
+ENV/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Streamlit
+.streamlit/
+
+# Logs
+*.log
+
+# Environment variables
+.env
+.env.local
+
+# local dir
+local
diff --git a/chat/streamlit/.python-version b/chat/streamlit/.python-version
@@ -0,0 +1 @@
+3.13