{"id":34756130,"url":"https://github.com/e-roy/ai-math-tutor","last_synced_at":"2026-05-25T17:01:54.347Z","repository":{"id":322888801,"uuid":"1089163172","full_name":"e-roy/ai-math-tutor","owner":"e-roy","description":null,"archived":false,"fork":false,"pushed_at":"2025-11-06T21:14:36.000Z","size":608,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-06T23:24:03.390Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://ai-math-tutor-lake.vercel.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/e-roy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-04T01:08:01.000Z","updated_at":"2025-11-06T21:14:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/e-roy/ai-math-tutor","commit_stats":null,"previous_names":["e-roy/ai-math-tutor"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/e-roy/ai-math-tutor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/e-roy%2Fai-math-tutor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/e-roy%2Fai-math-tutor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/e-roy%2Fai-math-tutor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/e-roy%2Fai-math-tutor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/e-roy","download_url":"https://codeload.github.com/e-roy/ai-math-tutor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/e-roy%2Fai-math-tutor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33484522,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-25T14:31:05.219Z","status":"ssl_error","status_checked_at":"2026-05-25T14:31:02.878Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-25T05:40:48.203Z","updated_at":"2026-05-25T17:01:54.341Z","avatar_url":"https://github.com/e-roy.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AI Math Tutor\n\nA Socratic-style AI tutoring web application that guides students (ages 4-18) through math problems using multi-turn conversations, visual problem solving, and persistent progress tracking.\n\n## Features\n\n- **Socratic Dialogue**: Multi-turn conversations that guide students to discover solutions through questions, never direct answers\n- **Problem Input**: Text entry and image upload with OCR/Vision parsing\n- **Math Rendering**: Beautiful LaTeX rendering using KaTeX\n- **Interactive Whiteboard**: Collaborative canvas with Excalidraw for visual explanations and diagrams\n- **Progress Tracking**: Persistent skill mastery tracking with evidence-based assessment\n- **Versioned Snapshots**: Automatic board snapshots and conversation history\n\n## Tech Stack\n\n- **Framework**: Next.js 16 (App Router) + TypeScript\n- **State Management**: Zustand (UI) + TanStack Query (server state)\n- **API**: tRPC v11 (App Router handlers)\n- **Authentication**: NextAuth.js (Auth.js) v5 with Postgres adapter\n- **Database**: Neon Postgres + Drizzle ORM\n- **UI**: Tailwind CSS + shadcn/ui components\n- **AI/LLM**: Vercel AI SDK with OpenAI (text + vision)\n- **Whiteboard**: Excalidraw\n- **Storage**: Vercel Blob\n- **Math**: KaTeX (rendering) + mathjs (validation)\n\n## Prerequisites\n\n- Node.js 18+\n- pnpm (package manager)\n- Neon Postgres database (or compatible PostgreSQL)\n- OpenAI API key\n- Vercel Blob account (for file storage)\n\n## Getting Started\n\n### 1. Clone the repository\n\n```bash\ngit clone \u003crepository-url\u003e\ncd ai-math-tutor\n```\n\n### 2. Install dependencies\n\n```bash\npnpm install\n```\n\n### 3. Set up environment variables\n\nCreate a `.env` file in the root directory:\n\n```env\n# Database\nDATABASE_URL=\"postgresql://user:password@host:port/database\"\n\n# OpenAI\nOPENAI_API_KEY=\"your-openai-api-key\"\n\n# Storage\nBLOB_READ_WRITE_TOKEN=\"your-vercel-blob-token\"\n\n# NextAuth\nNEXTAUTH_SECRET=\"generate-a-random-secret-here\"\nNEXTAUTH_URL=\"http://localhost:3000\"\n\n# Environment\nNODE_ENV=\"development\"\n```\n\nGenerate a secure `NEXTAUTH_SECRET`:\n\n```bash\nopenssl rand -base64 32\n```\n\n### 4. Set up the database\n\nGenerate and run migrations:\n\n```bash\n# Generate migration files\npnpm db:generate\n\n# Push schema to database\npnpm db:push\n\n# Or run migrations\npnpm db:migrate\n```\n\nOptional: Open Drizzle Studio to view your database:\n\n```bash\npnpm db:studio\n```\n\n### 5. Run the development server\n\n```bash\npnpm dev\n```\n\nOpen [http://localhost:3000](http://localhost:3000) in your browser.\n\n## Available Scripts\n\n- `pnpm dev` - Start development server with Turbopack\n- `pnpm build` - Build for production\n- `pnpm start` - Start production server\n- `pnpm lint` - Run ESLint\n- `pnpm lint:fix` - Fix ESLint errors\n- `pnpm typecheck` - Run TypeScript type checking\n- `pnpm check` - Run linting and type checking\n- `pnpm format:write` - Format code with Prettier\n- `pnpm format:check` - Check code formatting\n- `pnpm db:generate` - Generate Drizzle migration files\n- `pnpm db:push` - Push schema changes to database\n- `pnpm db:migrate` - Run database migrations\n- `pnpm db:studio` - Open Drizzle Studio\n\n## Project Structure\n\n```\n/src\n  /app                 # Next.js App Router pages\n    /(auth)            # Authentication routes\n    /tutor             # Main tutoring interface\n    /progress          # Progress tracking\n  /components           # React components\n    /ui                # shadcn/ui components\n  /lib                 # Utility functions and helpers\n    /ai                # AI prompts and logic\n    /math              # Math validation and helpers\n    /whiteboard        # Whiteboard utilities\n  /server              # Server-side code\n    /api               # tRPC routers\n    /db                # Database schema and client\n    /auth              # NextAuth configuration\n  /store               # Zustand stores\n  /types               # TypeScript type definitions\n  /styles              # Global styles\n```\n\n## Key Features in Detail\n\n### Socratic Tutoring\n\nThe AI tutor uses a Socratic approach:\n\n- Never gives direct answers\n- Asks guiding questions to help students discover solutions\n- Provides hints after 2+ turns of being stuck\n- Adapts to student understanding level\n\n### Problem Input\n\n- **Text**: Direct text entry for math problems\n- **Image Upload**: Screenshot or photo upload with Vision API OCR\n- **LaTeX Support**: Automatic LaTeX parsing and rendering\n\n### Progress Tracking\n\n- Skill-based mastery tracking aligned with educational standards\n- Evidence collection (conversation turns, board snapshots)\n- Persistent progress across sessions\n\n### Whiteboard\n\n- Interactive Excalidraw canvas\n- AI annotations and visual explanations\n- Auto-save with versioned snapshots\n- Single-user with AI collaboration\n\n## Development Notes\n\n- All server code runs on Node.js runtime\n- Strict TypeScript (no `any` types)\n- Files kept under 350 lines of code\n- All inputs validated with Zod\n- All mutations are auth-guarded\n- Board autosave is throttled for performance\n\n## Deployment\n\nThis project is configured for deployment on Vercel:\n\n1. Push your code to GitHub\n2. Import your repository in Vercel\n3. Add environment variables in Vercel dashboard\n4. Deploy\n\nThe app will automatically:\n\n- Build on Vercel's infrastructure\n- Connect to your Neon database\n- Use Vercel Blob for file storage\n\n## License\n\n[Add your license here]\n\n## Contributing\n\n[Add contribution guidelines here]\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fe-roy%2Fai-math-tutor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fe-roy%2Fai-math-tutor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fe-roy%2Fai-math-tutor/lists"}