Feature/activity 2 kids tutor quiz

.cursor/rules/general-rule.mdc

@@ -5,7 +5,9 @@ alwaysApply: true
 ---
 ## Rules to Follow
 
+- You must not analyze entire project unless absolutely needed. If I ask remind me this rule.  
 - You must always commit your changes whenever you update code. 
 - You must always try and write code that is well documented. (self or commented is fine)
 - You must only work on a single feature at a time.
-- You must explain your decisions thouroughly to the user.
+- You must explain your decisions thouroughly to the user.
+- You always prefer to use branch development. Before writing any code - you create a feature branch to hold those changes. After you are done - provide instructions in a "MERGE.md" file that explains how to merge the changes back to main with both a GitHub PR route and a GitHub CLI route.

.gitignore

@@ -17,7 +17,7 @@ dist/
 downloads/
 eggs/
 .eggs/
-lib/
+# lib/ - commented out to allow frontend/lib/ to be tracked
 lib64/
 parts/
 sdist/
@@ -65,6 +65,9 @@ local_settings.py
 db.sqlite3
 db.sqlite3-journal
 
+# Kids Tutor Database (local development only)
+/data/kids_tutor.db
+
 # Flask stuff:
 instance/
 .webassets-cache

.vercelignore

@@ -0,0 +1,2 @@
+# Vercel ignore file - FastAPI backend has been removed
+# Only Next.js frontend is deployed

MERGE.md

@@ -0,0 +1,161 @@
+# MERGE Instructions - Kids Science Tutor with Persistent RAG
+
+## Branch Information
+- **Feature Branch**: `feature/activity-2-kids-tutor-quiz`
+- **Target Branch**: `main`
+- **Purpose**: Complete Kids Science Tutor MVP with persistent SQLite embeddings and RAG integration
+
+## Changes Summary
+This branch transforms the application into a comprehensive Kids Science Tutor with persistent RAG functionality:
+
+### Database & Backend Changes
+- ✅ **SQLite Integration**: Complete database system with `better-sqlite3` 
+- ✅ **Persistent Embeddings**: `pdf_embeddings` table with integer foreign keys to `pdf_metadata`
+- ✅ **Database Schema**: Kids, sessions, conversations, quiz_questions, pdf_metadata, completed_topics
+- ✅ **RAG System**: Moved from temporary JSON to persistent SQLite storage
+- ✅ **Auto-Initialization**: Automatically embeds Grade-3 PDFs on startup if OpenAI key exists
+
+### Kids Science Tutor Features
+- ✅ **Kid Login System**: Name + PIN authentication (`/login`)
+- ✅ **Reading Sessions**: Dynamic content from vector search, 30-line chunks, 5-minute timer
+- ✅ **Adaptive Quizzing**: OpenAI-generated questions from PDF content, tracks previous questions
+- ✅ **Progress Tracking**: Topics completed, quiz scores, session history
+- ✅ **Parent Reports**: Comprehensive progress dashboard (`/report/[kidId]`)
+- ✅ **10 Grade-3 Science PDFs**: Auto-generated content (Planets, Constellations, Rocks, etc.)
+
+### Admin & RAG Features  
+- ✅ **PDF Upload System**: Parents can upload PDFs with metadata tracking
+- ✅ **Vector Database**: Semantic search with cosine similarity, FTS5 full-text search
+- ✅ **Reindex Endpoint**: `/api/reindex` to rebuild embeddings from scratch
+- ✅ **Health Monitoring**: `/api/health` shows database and embeddings status
+- ✅ **Enhanced Landing Page**: Admin tools, system health, Kids Tutor navigation
+
+### Technical Improvements
+- ✅ **File Organization**: Moved `lib/db.ts` to `frontend/lib/db.ts` for better Next.js integration
+- ✅ **Import Path Fixes**: Corrected all relative imports across API routes
+- ✅ **Error Handling**: Comprehensive logging and error recovery
+- ✅ **UI Fixes**: Quiz option text visibility, responsive design improvements
+
+## Merge Options
+
+### Option 1: GitHub Pull Request (Recommended)
+
+#### Step 1: Push the feature branch
+```bash
+git push origin feature/activity-2-kids-tutor-quiz
+```
+
+#### Step 2: Create Pull Request
+1. Go to your GitHub repository
+2. Click "Compare & pull request" for the `feature/activity-2-kids-tutor-quiz` branch
+3. Fill in the PR details:
+   - **Title**: "Complete Kids Science Tutor MVP with Persistent RAG System"
+   - **Description**: Copy the changes summary from above
+4. Assign reviewers if needed
+5. Click "Create pull request"
+
+#### Step 3: Review and Merge
+1. Review the changes in the GitHub interface
+2. Run any automated tests/checks
+3. Click "Merge pull request" 
+4. Choose merge type:
+   - **"Create a merge commit"** - Preserves branch history
+   - **"Squash and merge"** - Combines all commits into one clean commit
+   - **"Rebase and merge"** - Replays commits without merge commit
+5. Confirm the merge
+6. Delete the feature branch after successful merge
+
+### Option 2: GitHub CLI (Command Line)
+
+#### Prerequisites
+```bash
+# Install GitHub CLI if not already installed
+# https://cli.github.com/
+
+# Authenticate with GitHub
+gh auth login
+```
+
+#### Step 1: Push and create PR
+```bash
+# Push the feature branch
+git push origin feature/activity-2-kids-tutor-quiz
+
+# Create pull request via CLI
+gh pr create \
+  --title "Complete Kids Science Tutor MVP with Persistent RAG System" \
+  --body "Full Kids Science Tutor implementation with persistent SQLite embeddings, adaptive quizzing, progress tracking, and admin tools. Includes database schema, vector search, auto-initialization, and comprehensive error handling." \
+  --base main \
+  --head feature/activity-2-kids-tutor-quiz
+```
+
+#### Step 2: Review and merge via CLI
+```bash
+# View the PR
+gh pr view
+
+# Merge the PR (choose one option):
+# Option A: Merge commit
+gh pr merge --merge
+
+# Option B: Squash merge (recommended for feature branches)
+gh pr merge --squash
+
+# Option C: Rebase merge
+gh pr merge --rebase
+```
+
+#### Step 3: Cleanup
+```bash
+# Delete the feature branch locally
+git branch -d feature/activity-2-kids-tutor-quiz
+
+# Delete the remote feature branch
+git push origin --delete feature/activity-2-kids-tutor-quiz
+```
+
+## Post-Merge Verification
+
+After merging, verify the deployment works correctly:
+
+1. **Check Vercel Deployment**: Ensure the app redeploys automatically
+2. **Test Core Functionality**:
+   ```bash
+   curl -s https://your-app.vercel.app/api/health
+   curl -s https://your-app.vercel.app/api/kids/login -d '{"name":"Test","pin":"1234"}'
+   ```
+3. **Test Kids Tutor Flow**: 
+   - Visit `/login` and create a test kid
+   - Start a reading session at `/read/[kidId]`
+   - Complete quiz and check progress at `/report/[kidId]`
+4. **Test Admin Features**:
+   - Upload a PDF via the landing page
+   - Use "Rebuild Vector DB" button
+   - Check system health endpoint
+
+## Rollback Plan (If Issues Occur)
+
+If problems arise after merging:
+
+```bash
+# Find the merge commit hash
+git log --oneline -10
+
+# Revert the merge commit
+git revert -m 1 <merge-commit-hash>
+
+# Push the revert
+git push origin main
+```
+
+## Notes
+- **Persistent Storage**: All data now stored in SQLite (`data/kids_tutor.db`) - survives deployments
+- **Auto-Initialization**: Grade-3 PDFs automatically embedded on first startup with OpenAI key
+- **Node.js Version**: Requires Node.js 20+ for `better-sqlite3` compatibility
+- **Environment Variables**: `OPENAI_API_KEY` required for embeddings and quiz generation
+- **Database Migration**: Automatically handles schema updates and data migration
+
+---
+**Created**: September 23, 2025  
+**Author**: AI Assistant  
+**Branch**: feature/activity-2-kids-tutor-quiz → main