SilasAggrey/studyai-ghana

AI-powered study assistant for Ghanaian students — Telegram bot with quizzes, flashcards, mock exams, and study plans # StudyAI Ghana 🤖🎓 An AI-powered personal study assistant that lives inside Telegram. **ChatGPT + Quizlet + Exam Practice + Personal Tutor** — for university and senior high school students, built for Ghana first and designed to expand worldwide. > This repository contains **Phase 1 (MVP)**: onboarding, AI tutor, quiz > generation/taking/scoring, progress tracking, referral attribution, > premium gating, admin commands, and the full database schema. --- ## ✨ What it does | Feature | Status | |---|---| | `/start` onboarding & student profile (school, level, program, subjects) | ✅ Phase 1 | | `/ask` — AI tutor with beginner/intermediate/advanced modes | ✅ Phase 1 | | `/quiz` — generate quizzes (subject → topic → difficulty → count) | ✅ Phase 1 | | Quiz taking with instant ✅/❌ feedback + explanations | ✅ Phase 1 | | Quiz scoring, strong/weak topics, recommendations | ✅ Phase 1 | | `/progress` — dashboard: streak, accuracy, subjects, recommended topic | ✅ Phase 1 | | XP / levels / daily streaks (gamification foundations) | ✅ Phase 1 | | `/premium` plan gating + free-plan daily limits | ✅ Phase 1 | | Referral system with rewards + anti-abuse checks | ✅ Phase 1 | | `/stats`, `/grant`, `/revoke` admin commands (role-gated) | ✅ Phase 1 | | `/notes` — upload PDF/TXT/DOCX/MD → summarize, quiz from material, ask, study guide | ✅ Phase 2 (partial) | | Mock exams, photo/OCR notes, flashcards, study plans | 🔜 Phase 2 | | Leaderboard, payments (Telegram Stars), admin web panel | 🔜 Phase 3 | | Telegram Mini App dashboard | 🔜 Phase 4 | ## 🏗 Architecture ``` studyai-ghana/ ├── app/ │ ├── main.py # bot entry point (polling or webhook) │ ├── config.py # pydantic-settings env config │ ├── logging_setup.py │ ├── bot/ # aiogram 3 │ │ ├── dispatcher.py # middlewares + routers + error handling │ │ ├── states.py # FSM states │ │ ├── keyboards.py # inline keyboard builders │ │ ├── tex …