{"id":29064579,"url":"https://github.com/waynesutton/learnconvex","last_synced_at":"2025-06-27T09:30:43.171Z","repository":{"id":298189636,"uuid":"998946572","full_name":"waynesutton/learnconvex","owner":"waynesutton","description":"A comprehensive interactive learning platform for mastering Convex.dev fundamentals and practical application development.","archived":false,"fork":false,"pushed_at":"2025-06-17T00:01:54.000Z","size":346,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-24T14:04:39.614Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://learnconvex.previews.convex.dev","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/waynesutton.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}},"created_at":"2025-06-09T13:58:40.000Z","updated_at":"2025-06-22T17:33:50.000Z","dependencies_parsed_at":"2025-06-09T22:19:12.577Z","dependency_job_id":"e97c4466-12c8-4d7e-bf66-6bd3f23fb8e2","html_url":"https://github.com/waynesutton/learnconvex","commit_stats":null,"previous_names":["waynesutton/learnconvex"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/waynesutton/learnconvex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/waynesutton%2Flearnconvex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/waynesutton%2Flearnconvex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/waynesutton%2Flearnconvex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/waynesutton%2Flearnconvex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/waynesutton","download_url":"https://codeload.github.com/waynesutton/learnconvex/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/waynesutton%2Flearnconvex/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262231276,"owners_count":23278921,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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-06-27T09:30:37.109Z","updated_at":"2025-06-27T09:30:43.122Z","avatar_url":"https://github.com/waynesutton.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ConvexCourse: Interactive Learning Platform\n\nAn AI-powered learning platform designed to teach developers how to build applications with Convex.dev through interactive lessons, voice integration, and comprehensive admin management tools.\n\n## What ConvexCourse Does\n\nConvexCourse is a production-ready learning platform that makes Convex development accessible through two distinct learning modes:\n\n### 🎯 Core Learning Experience\n\n**Chat Mode**: Interactive AI conversations that guide you through building real Convex applications\n\n- Real-time Q\u0026A with AI instructor powered by OpenAI GPT-4o-mini\n- Documentation-enhanced responses using current Convex docs\n- Voice interaction with speech-to-text and text-to-speech capabilities\n- Progressive learning from basic setup to advanced patterns\n\n**Cards Mode**: Flashcard-style learning for quick concept reinforcement\n\n- Swipe-to-answer flashcards with immediate feedback\n- Bite-sized lessons perfect for mobile learning\n- Progress tracking with celebration animations\n- Admin-configurable question sets\n\n### 🚀 Key Features\n\n#### **AI-Powered Instruction**\n\n- **Documentation-Enhanced AI**: Responses powered by current Convex documentation for accuracy\n- **Context-Aware Learning**: AI understands your progress and adapts instruction accordingly\n- **Voice Integration**: Full speech-to-text input and text-to-speech output using ElevenLabs\n- **AgentFlow Support**: Enhanced AI with persistent conversation context and workflow management\n\n#### **Dynamic Course Management**\n\n- **Real-time Configuration**: Admin-adjustable question counts, scoring, and difficulty levels\n- **Live Documentation Updates**: AI instruction updated with latest Convex best practices\n- **Session Persistence**: Automatic resume across browser sessions\n- **Progress Celebration**: Confetti animations and achievement badges\n\n#### **Comprehensive Admin Tools**\n\n- **Real-time Monitoring**: Live session tracking with message-level visibility\n- **Session Intervention**: Insert contextual hints or take over sessions manually\n- **Analytics Dashboard**: Usage statistics, completion rates, and cost tracking\n- **Bulk Operations**: Efficient management of multiple learning sessions\n- **Documentation Management**: Update AI knowledge base through admin interface\n\n#### **Voice-Enabled Learning**\n\n- **Speech Recognition**: Speak your answers instead of typing\n- **Audio Responses**: Listen to AI explanations with natural voice synthesis\n- **Voice Commands**: Use \"skip\", \"end\", and navigation commands\n- **Accessibility**: Enhanced learning for diverse accessibility needs\n\n#### **Advanced Features**\n\n- **Document Search**: Upload and search through learning materials\n- **Token Analytics**: Track AI usage and costs\n- **Clerk Authentication**: Secure admin access with role-based permissions\n- **Mobile Optimized**: Responsive design works perfectly on all devices\n\n## Learning Content\n\nThe platform teaches practical Convex development through hands-on examples:\n\n- **Project Setup**: `npx create-convex@latest` and initial configuration\n- **Schema Design**: Database table definitions and validation\n- **Query Functions**: Reading data with real-time subscriptions\n- **Mutation Functions**: Writing data with type safety\n- **Action Functions**: External API integration and serverless workflows\n- **Frontend Integration**: React hooks (`useQuery`, `useMutation`, `useAction`)\n- **Deployment**: Production deployment and environment management\n- **Best Practices**: Performance optimization and code organization\n\n## Quick Start\n\n### Prerequisites\n\n- Node.js 18+\n- OpenAI API key for AI instruction\n- ElevenLabs API key for voice features (optional)\n\n### Installation\n\n1. **Clone and install**\n\n   ```bash\n   git clone \u003crepository-url\u003e\n   cd convex-course\n   npm install\n   ```\n\n2. **Set up Convex**\n\n   ```bash\n   npx convex dev\n   ```\n\n3. **Configure environment variables**\n\n   ```bash\n   # Required\n   VITE_CONVEX_URL=your_convex_deployment_url\n   CONVEX_OPENAI_API_KEY=your_openai_api_key\n\n   # Optional - Voice features\n   ELEVENLABS_API_KEY=your_elevenlabs_api_key\n\n   # Optional - Admin authentication\n   VITE_CLERK_PUBLISHABLE_KEY=your_clerk_publishable_key\n   CLERK_SECRET_KEY=your_clerk_secret_key\n   ```\n\n4. **Start learning**\n\n   ```bash\n   npm run dev\n   ```\n\n   Visit `http://localhost:5173` and choose your learning mode!\n\n## Usage Guide\n\n### For Learners\n\n1. **Choose Your Mode**\n\n   - **Chat Mode**: Conversational learning with AI instructor\n   - **Cards Mode**: Quick flashcard-style review\n\n2. **Interactive Learning**\n\n   - Type responses or use voice input (click microphone icon)\n   - Get immediate feedback and explanations\n   - Progress through adaptive questioning\n\n3. **Voice Features**\n\n   - Click microphone to speak answers\n   - Click speaker icon to hear AI responses\n   - Use voice commands: \"skip\", \"end\", navigation\n\n4. **Track Progress**\n   - View real-time scores and completion progress\n   - Celebrate achievements with animations\n   - Resume sessions automatically\n\n### For Administrators\n\nAccess the admin playground at `/playground` to:\n\n#### **Monitor Learning Sessions**\n\n- View all active and completed sessions in real-time\n- See live message exchanges and user progress\n- Track completion rates and learning outcomes\n\n#### **Session Intervention**\n\n- Insert contextual hints for struggling learners\n- Take over sessions for manual instruction\n- Edit or delete messages for content moderation\n\n#### **Configure Courses**\n\n- Adjust question counts and scoring systems\n- Update documentation links for AI accuracy\n- Manage course difficulty and content focus\n\n#### **Analytics \u0026 Insights**\n\n- Track usage patterns and popular features\n- Monitor AI token consumption and costs\n- Export data for reporting and analysis\n\n#### **Bulk Operations**\n\n- Archive completed sessions\n- Delete inactive or test sessions\n- Clear message history for privacy\n\n## Technical Architecture\n\n### Backend (Convex)\n\n- **Reactive Database**: Real-time synchronization across all components\n- **Type-Safe Functions**: Full TypeScript coverage with Convex validators\n- **AgentFlow Integration**: Enhanced AI with persistent context and workflows\n- **Serverless Architecture**: Automatic scaling and global edge distribution\n\n### Frontend (React + TypeScript)\n\n- **Modern React**: Hooks, suspense, and real-time updates\n- **Voice Integration**: Web Speech API + ElevenLabs synthesis\n- **Responsive Design**: Mobile-first with TailwindCSS\n- **Real-time UI**: Live updates via Convex reactive queries\n\n### AI \u0026 Voice\n\n- **OpenAI GPT-4o-mini**: Primary AI instruction engine\n- **ElevenLabs**: High-quality text-to-speech synthesis\n- **Documentation Context**: AI responses enhanced with current Convex docs\n- **AgentFlow**: Persistent conversation context and workflow management\n\n### Authentication \u0026 Security\n\n- **Clerk**: Production-ready authentication with admin roles\n- **Anonymous Learning**: No auth required for core learning experience\n- **Role-based Access**: Admin tools protected behind authentication\n- **Session Security**: Secure session management with intervention controls\n\n## API Configuration\n\n### Environment Variables\n\n**Required:**\n\n```env\nVITE_CONVEX_URL=https://your-deployment.convex.cloud\nCONVEX_OPENAI_API_KEY=sk-your-openai-key\n```\n\n**Optional:**\n\n```env\n# Voice Features\nELEVENLABS_API_KEY=your-elevenlabs-key\n\n# Admin Authentication\nVITE_CLERK_PUBLISHABLE_KEY=pk_your-clerk-key\nCLERK_SECRET_KEY=sk_your-clerk-secret\n\n# AgentFlow (automatically detected)\n# No additional configuration needed\n```\n\n### Database Initialization\n\nThe platform automatically initializes required data on first run:\n\n- Default course settings\n- Convex documentation links\n- Question banks\n- Admin configurations\n\n## Development\n\n### Local Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Start Convex backend\nnpx convex dev\n\n# Start frontend (in another terminal)\nnpm run dev:frontend\n\n# Or start both together\nnpm run dev\n```\n\n### Building for Production\n\n```bash\n# Build frontend\nnpm run build\n\n# Deploy Convex functions\nnpx convex deploy\n```\n\n### Testing\n\n```bash\n# Type checking\nnpm run lint\n\n# Build verification\nnpm run build\n```\n\n## Deployment\n\n### Vercel (Frontend)\n\n1. Connect your GitHub repository to Vercel\n2. Set environment variables in Vercel dashboard\n3. Deploy automatically on push to main branch\n\n### Convex (Backend)\n\n1. Set up Convex production deployment:\n\n   ```bash\n   npx convex deploy --prod\n   ```\n\n2. Configure environment variables:\n   ```bash\n   npx convex env set CONVEX_OPENAI_API_KEY sk-your-key --prod\n   npx convex env set ELEVENLABS_API_KEY your-key --prod\n   ```\n\n## Key Differentiators\n\n- **No Auth Required**: Anonymous learning experience with optional admin authentication\n- **Voice-First Design**: Complete voice interaction capabilities for accessibility\n- **Real-time Admin Tools**: Live session monitoring and intervention capabilities\n- **Documentation-Enhanced AI**: Always current with latest Convex best practices\n- **Dual Learning Modes**: Chat conversations and flashcard-style learning\n- **AgentFlow Integration**: Persistent AI context and advanced workflow management\n- **Production Ready**: Comprehensive analytics, cost tracking, and scalable architecture\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Test thoroughly\n5. Submit a pull request\n\nPlease see `files.md` for detailed architecture documentation.\n\n## Support\n\n- **Documentation**: See `files.md` for comprehensive technical details\n- **Issues**: Report bugs via GitHub issues\n- **Questions**: Join the Convex Discord community\n- **Updates**: Follow [@convex_dev](https://twitter.com/convex_dev) for latest features\n\n## License\n\nThis project is open source. See LICENSE file for details.\n\n---\n\n**Built with ❤️ using Convex.dev** • Make something awesome!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwaynesutton%2Flearnconvex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwaynesutton%2Flearnconvex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwaynesutton%2Flearnconvex/lists"}