1 line
11 KiB
JSON
1 line
11 KiB
JSON
{"repo": "9jadevo/astroquiz", "files": {"README.md": {"007681b5c42d506b9b4e22db500303407f33b7c9": {"t": 1785596413.2515984, "n": 10266, "h": "54efefd9df8c25f8", "c": "# 🌟 AstroQuiz - Learn the Universe\n\nA modern, interactive astronomy learning platform built with React, TypeScript, and Supabase. Test your knowledge of the cosmos through engaging quizzes, compete on leaderboards, and learn with an AI-powered astronomy tutor.\n\n\n\n## ✨ Features\n\n### 🎯 Interactive Quiz System\n- **Dynamic Questions**: Randomized astronomy questions with multiple difficulty levels\n- **Real-time Scoring**: Instant feedback with streak tracking\n- **Timed Challenges**: 30-second timer per question for added excitement\n- **Visual Learning**: Image-based questions for enhanced engagement\n- **Progress Tracking**: Detailed statistics and performance analytics\n\n### 🌍 Multi-language Support\n- **AI-Powered Translation**: Questions available in 10+ languages\n- **Real-time Translation**: Instant question translation during quizzes\n- **Fallback Support**: Multiple AI providers ensure reliable translation\n- **Language Selection**: Easy language switching with flag indicators\n\n### 🏆 Competitive Features\n- **Live Leaderboards**: Real-time rankings with automatic updates\n- **Achievement System**: Unlock badges and milestones\n- **Streak Challenges**: Build impressive answer streaks\n- **Performance Analytics**: Detailed accuracy and speed metrics\n\n### 🤖 AI Astronomy Tutor\n- **Interactive Chat**: Ask questions about astronomy and space science\n- **Expert Knowledge**: Specialized in astronomy, planets, stars, and space missions\n- **Conversation History**: Maintains context for natural conversations\n- **Multiple AI Providers**: OpenAI, Hugging Face, and custom endpoints\n\n### 🛡️ Integrity Detection\n- **Automated Monitoring**: AI-powered cheating detection\n- **Anomaly Analysis**: Speed and pattern analysis\n- **Confidence Scoring**: Detailed suspicion assessment\n- **Visual Indicators**: Subtle warnings on leaderboards\n\n### 👨💼 Admin Panel\n- **Question Management**: Create, edit, and organize quiz questions\n- **AI Question Generation**: Bulk generate questions on any astronomy topic\n- **User Management**: Monitor users and suspicious activities\n- **Analytics Dashboard**: Comprehensive platform statistics\n\n## 🚀 Tech Stack\n\n### Frontend\n- **React 18** with TypeScript\n- **Tailwind CSS** for styling\n- **React Router** for navigation\n- **Lucide React** for icons\n- **Vite** for development and building\n\n### Backend\n- **Supabase** for database and authentication\n- **PostgreSQL** with Row Level Security (RLS)\n- **Supabase Edge Functions** for serverless computing\n- **Real-time subscriptions** for live updates\n\n### AI Integration\n- **OpenAI GPT-3.5** for question generation and tutoring\n- **Hugging Face** models as fallback\n- **Custom AI endpoints** for additional reliability\n- **Multi-provider architecture** for maximum uptime\n\n## 📋 Prerequisites\n\n- Node.js 18+ and npm\n- Supabase account\n- OpenAI API key (recommended)\n- Hugging Face API key (optional fallback)\n\n## 🛠️ Installation\n\n### 1. Clone the Repository\n```bash\ngit clone <repository-url>\ncd astroquiz-learning-app\nnpm install\n```\n\n### 2. Environment Setup\nCreate a `.env` file in the root directory:\n\n```env\n# Supabase Configuration\nVITE_SUPABASE_URL=your_supabase_url_here\nVITE_SUPABASE_ANON_KEY=your_supabase_anon_key_here\n\n# AI Provider Configuration\nAI_PROVIDER=openai\n\n# OpenAI API Configuration (recommended)\nOPENAI_API_KEY=your_openai_api_key_here\n\n# Hugging Face API Configuration (optional fallback)\nHF_API_KEY=your_huggingface_api_key_here\n```\n\n### 3. Database Setup\n\n#### Option A: Using Supabase Dashboard\n1. Create a new Supabase project\n2. Run the migration files in order from `supabase/migrations/`\n3. Enable Row Level Security on all tables\n\n#### Option B: Using Supabase CLI\n```bash\n# Install Supabase CLI\nnpm install -g supabase\n\n# Initialize and link project\nsupabase init\nsupabase link --project-ref your-project-ref\n\n# Run migrations\nsupabase db push\n```\n\n### 4. Deploy Edge Functions\n```bash\n# Deploy all edge functions\nsupabase functions deploy ai-tutor-chat\nsupabase functions deploy generate-questions\nsupabase functions deploy translate-text\nsupabase functions deploy detect-cheating\n\n# Set environment variables for functions\nsupabase secrets set OPENAI_API_KEY=your_openai_api_key\nsupabase secrets set HF_API_KEY=your_huggingface_api_key\nsupabase secrets set AI_PROVIDER=openai\n```\n\n### 5. Start Development Server\n```bash\nnpm run dev\n```\n\n## 📊 Database Schema\n\n### Core Tables\n\n#### `user_profiles`\n- User information and statistics\n- Admin privileges and suspicion flags\n- Performance metrics (total score, best streak, games played)\n\n#### `questions`\n- Quiz questions with multiple choice options\n- Categories, difficulty levels, and images\n- Creator tracking and timestamps\n\n#### `quiz_sessions`\n- Individual quiz attempt records\n- Scoring, timing, and streak data\n- Integrity flags and suspicion reasons\n\n### Key Features\n- **Row Level Security (RLS)** on all tables\n- **Real-time subscriptions** for live updates\n- **Automatic triggers** for data consistency\n- **Performance indexes** for fast queries\n\n## 🎮 Usage Guide\n\n### For Students\n1. **Sign Up**: Create an account with email and username\n2. **Choose Language**: Select your preferred language for questions\n3. **Take Quizzes**: Answer astronomy questions within the time limit\n4. **Track Progress**: Monitor your scores, streaks, and achievements\n5. **Ask the AI Tutor**: Get help with astronomy concepts\n6. **Compete**: Climb the leaderboards and unlock achievements\n\n### For Administrators\n1. **Access Admin Panel**: Available to users with admin privileges\n2. **Manage Questions**: Create, edit, and organize quiz content\n3. **Generate Questions**: Use AI to bulk create questions on any topic\n4. **Monitor Users**: Track user activity and suspicious behavior\n5. **View Analytics**: Access platform-wide statistics and insights\n\n## 🔧 Configuration\n\n### AI Providers\nThe app supports multiple AI providers with automatic fallback:\n\n1. **OpenAI** (Recommended)\n - Most reliable and accurate\n - Best for question generation and tutoring\n - Requires paid API key\n\n2. **Hugging Face**\n - Free tier available\n - Good fallback option\n - May have occasional downtime\n\n3. **Custom Endpoints**\n - Additional reliability\n - Configurable endpoints\n - Custom model support\n\n### Environment Variables\n```env\n# AI Provider Selection\nAI_PROVIDER=openai # Options: openai, huggingface\n\n# API Keys\nOPENAI_API_KEY=sk-...\nHF_API_KEY=hf_...\n\n# Supabase Configuration\nVITE_SUPABASE_URL=https://your-project.supabase.co\nVITE_SUPABASE_ANON_KEY=eyJ...\n```\n\n## 🛡️ Security Features\n\n### Authentication\n- Supabase Auth with email/password\n- Row Level Security (RLS) policies\n- Secure session management\n- Admin role protection\n\n### Data Protection\n- Encrypted data transmission\n- Secure API endpoints\n- Input validation and sanitization\n- Rate limiting on AI endpoints\n\n### Integrity Monitoring\n- Automated cheating detection\n- Anomaly analysis algorithms\n- Confidence scoring system\n- Non-intrusive monitoring\n\n## 🚀 Deployment\n\n### Frontend Deployment\nThe app can be deployed to any static hosting service:\n\n```bash\n# Build for production\nnpm run build\n\n# Deploy to your preferred platform\n# (Vercel, Netlify, GitHub Pages, etc.)\n```\n\n### Backend Deployment\nSupabase handles all backend infrastructure:\n- Database hosting and backups\n- Edge Functions deployment\n- Real-time subscriptions\n- Authentication services\n\n## 🤝 Contributing\n\nWe welcome contributions! Please follow these steps:\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n### Development Guidelines\n- Follow TypeScript best practices\n- Use Tailwind CSS for styling\n- Maintain component modularity\n- Add proper error handling\n- Include comprehensive logging\n\n## 📝 API Documentation\n\n### Edge Functions\n\n#### `/functions/v1/ai-tutor-chat`\nChat with the AI astronomy tutor\n```typescript\nPOST /functions/v1/ai-tutor-chat\n{\n \"message\": \"What is a black hole?\",\n \"conversation_history\": [...]\n}\n```\n\n#### `/functions/v1/generate-questions`\nGenerate quiz questions using AI\n```typescript\nPOST /functions/v1/generate-questions\n{\n \"topic\": \"Solar System\",\n \"count\": 5,\n \"difficulty\": \"medium\"\n}\n```\n\n#### `/functions/v1/translate-text`\nTranslate text to different languages\n```typescript\nPOST /functions/v1/translate-text\n{\n \"text\": \"What is the largest planet?\",\n \"targetLang\": \"es\"\n}\n```\n\n#### `/functions/v1/detect-cheating`\nAnalyze quiz sessions for suspicious behavior\n```typescript\nPOST /functions/v1/detect-cheating\n{\n \"session_id\": \"uuid\",\n \"user_id\": \"uuid\",\n \"score\": 8,\n \"total_questions\": 10,\n \"time_taken\": 45,\n \"streak\": 5\n}\n```\n\n## 🐛 Troubleshooting\n\n### Common Issues\n\n#### CORS Errors\n- Ensure Supabase Edge Functions are properly deployed\n- Check environment variables are set correctly\n- Verify API endpoints are accessible\n\n#### Translation Not Working\n- Confirm AI provider API keys are configured\n- Check Edge Function logs in Supabase dashboard\n- Verify language codes are supported\n\n#### Database Connection Issues\n- Verify Supabase URL and keys in `.env`\n- Check RLS policies are properly configured\n- Ensure migrations have been applied\n\n#### Performance Issues\n- Monitor database query performance\n- Check for proper indexing\n- Optimize real-time subscriptions\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- **Supabase** for the excellent backend-as-a-service platform\n- **OpenAI** for powerful AI capabilities\n- **Pexels** for beautiful astronomy images\n- **Lucide** for the comprehensive icon library\n- **Tailwind CSS** for the utility-first CSS framework\n\n## 📞 Support\n\nFor support, please:\n1. Check the troubleshooting section above\n2. Search existing GitHub issues\n3. Create a new issue with detailed information\n4. Contact the development team\n\n---\n\n**Built with ❤️ for astronomy enthusiasts and learners everywhere**\n\n*Explore the universe, one question at a time* 🌌"}}}} |