Skip to content

addityaasharma/Bobo

BranchesTags

Repository files navigation

🤖 Bobo — AI Study Planner & Personal Tutor

An intelligent AI-powered study companion that helps students score better marks through smart timetables, concept explanation, note-making, question practice, streak tracking, collaborative sketch pads, and a personal AI tutor — all in one platform.

🚀 Tech Stack

Backend & API

Technology Purpose
Flask Python web framework
Flask-SocketIO Real-time collaboration (SketchPad)
Flask-JWT-Extended Authentication
Flask-Limiter Rate limiting
Flask-Mail Email delivery
Resend Transactional emails
Gunicorn + Eventlet Production server

Database & Storage

Technology Purpose
PostgreSQL Primary database
SQLAlchemy + Flask-Migrate ORM & migrations
Cloudinary Profile pictures & file storage
Redis Real-time pub/sub & caching

AI Stack

Technology Purpose
Hugging Face Hub AI tutor, concept explainer, Q&A

📁 Project Structure

bobo-backend/
│
├── migrations/                # Alembic DB migrations
│
├── utils/
│   └── connection.py          # DB connection (SQLAlchemy init)
│
├── .env                       # Environment variables
├── models.py                  # All SQLAlchemy models
├── server.py                  # Flask app entry point
├── requirements.txt
└── README.md

🗃️ Database Schema

User
  ├── Subject (many)
  │     └── Topic (many)
  │           ├── SubTopic (many)
  │           └── SavedAnswers (many-to-many)
  │                 └── savedanswer_topic / savedanswer_subtopic
  │
  ├── Todo (many)                  ← task checklist
  ├── TimeTable (many)             ← JSON grid schedule
  ├── SavedAnswers (many)          ← AI-generated notes/answers
  ├── UserStreak (one)             ← daily study streak
  ├── ConceptExplainer (many)      ← AI Q&A threads (threaded)
  ├── SketchPad (many)             ← collaborative whiteboards
  │     └── SketchPadCollaboration (many)
  │           └── Permission: view | edit
  │
  └── FeedBack                     ← platform reviews

⚙️ Environment Setup

.env

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/bobo_db

# JWT
SECRET_KEY=your_jwt_secret_key
JWT_EXPIRY_DAYS=7

# Cloudinary
CLOUDINARY_CLOUD_NAME=your_cloud_name
CLOUDINARY_API_KEY=your_api_key
CLOUDINARY_API_SECRET=your_api_secret

# Hugging Face
HUGGINGFACE_API_TOKEN=hf_your_token_here
HUGGINGFACE_MODEL=mistralai/Mistral-7B-Instruct-v0.2

# Email
MAIL_SERVER=smtp.gmail.com
MAIL_PORT=587
MAIL_USERNAME=your_email@gmail.com
MAIL_PASSWORD=your_app_password

# Resend (transactional emails)
RESEND_API_KEY=re_your_resend_key

# Redis
REDIS_URL=redis://localhost:6379/0

# App
FLASK_ENV=development
FLASK_DEBUG=1

🛠️ Installation & Running

# 1. Clone the repository
git clone <repo-url>
cd bobo-backend

# 2. Create virtual environment
python -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate

# 3. Install dependencies
pip install -r requirements.txt

# 4. Set up environment variables
cp .env.example .env
# Edit .env with your credentials

# 5. Start Redis
redis-server

# 6. Initialize database
flask db init
flask db migrate -m "initial migration"
flask db upgrade

# 7. Run the server
python server.py

👤 User Profile

Each student has:

Field Description
username Display name
user_class Grade / class (e.g. "10th", "12th", "B.Tech")
user_location City / region
date_of_birth For age-appropriate content
gender Optional
profile_picture Cloudinary URL
email Unique login identifier
created_at Account creation timestamp

📡 API Overview

🔐 Authentication — /auth

Method Endpoint Description
POST /auth/register Register new student
POST /auth/login Login
POST /auth/send-otp Send OTP via email
POST /auth/verify-otp Verify OTP
POST /auth/reset-password Reset password
POST /auth/logout Logout
GET /auth/profile Get own profile
PUT /auth/profile Update profile & picture

📚 Subjects & Topics — /subjects

Bobo organises study material in a 3-level hierarchy:

Subject → Topic → SubTopic
Method Endpoint Description
POST /subjects Add a subject
GET /subjects List all subjects
PUT /subjects/:id Rename subject
DELETE /subjects/:id Delete subject
POST /subjects/:id/topics Add topic to subject
GET /subjects/:id/topics List topics
PUT /topics/:id Update topic (name, status, progress)
DELETE /topics/:id Delete topic
POST /topics/:id/subtopics Add subtopic
GET /topics/:id/subtopics List subtopics
PUT /subtopics/:id Update subtopic
DELETE /subtopics/:id Delete subtopic

Topic / SubTopic Status values:

not_started → in_progress → completed

Progress: 0.0 to 100.0 (float) — auto-calculated based on subtopics completed.

🗓️ Timetable — /timetable

AI-assisted timetable builder stored as a JSON grid.

Method Endpoint Description
POST /timetable Create timetable
GET /timetable Get all timetables
GET /timetable/:id Get single timetable
PUT /timetable/:id Update grid
DELETE /timetable/:id Delete timetable
POST /timetable/generate AI-generate timetable from subjects

Grid format (JSON):

{
  "Monday": {
    "08:00": "Mathematics",
    "10:00": "Physics",
    "14:00": "Revision"
  },
  "Tuesday": { ... }
}

✅ Todo / Task List — /todo

Method Endpoint Description
POST /todo Create task
GET /todo List all tasks
PUT /todo/:id Update task
PUT /todo/:id/complete Mark as completed
DELETE /todo/:id Delete task

🧠 AI Concept Explainer — /concept

Threaded AI conversations — students ask follow-up questions in a chain.

Question 1 (parent_id: null)
  └── Follow-up (parent_id: 1)
        └── Deeper follow-up (parent_id: 2)
Method Endpoint Description
POST /concept/ask Ask AI a concept question
POST /concept/followup/:id Ask follow-up to existing answer
GET /concept/history All concept Q&A history
GET /concept/:id Single concept thread
DELETE /concept/:id Delete concept thread

How it works:

Student asks: "What is photosynthesis?"
  → Context built from subject + topic + subtopic (if provided)
  → Sent to Hugging Face model
  → Response saved with parent_id = null

Student asks: "Can you explain the light reaction in simpler terms?"
  → Previous Q&A included as context
  → Response saved with parent_id = previous answer id

📝 Saved Answers / Notes — /answers

Students save AI-generated answers and tag them to topics/subtopics for future reference.

Method Endpoint Description
POST /answers Save an answer/note
GET /answers List all saved answers
GET /answers/:id Single saved answer
PUT /answers/:id Update note
DELETE /answers/:id Delete note
POST /answers/:id/tag/topic Tag answer to a topic
POST /answers/:id/tag/subtopic Tag answer to a subtopic
DELETE /answers/:id/untag/topic/:topic_id Remove topic tag
GET /topics/:id/answers All answers tagged to a topic

🎨 SketchPad (Collaborative Whiteboard) — /sketchpad

Real-time collaborative whiteboard powered by Flask-SocketIO.
Each pad has a unique shareable code.

Method Endpoint Description
POST /sketchpad Create new sketch pad
GET /sketchpad List own sketch pads
GET /sketchpad/:id Get pad content
PUT /sketchpad/:id Save/update pad content
DELETE /sketchpad/:id Delete pad
POST /sketchpad/join/:code Join pad via unique code
GET /sketchpad/:id/collaborators List collaborators
PUT /sketchpad/:id/permission/:user_id Change collaborator permission
DELETE /sketchpad/:id/collaborator/:user_id Remove collaborator

Permissions:

Role Can View Can Edit
Owner ✅ ✅
edit collaborator ✅ ✅
view collaborator ✅ ❌

Real-time SocketIO events:

sketchpad:join       → join a pad room
sketchpad:update     → broadcast canvas changes
sketchpad:cursor     → broadcast cursor position
sketchpad:leave      → leave pad room

🔥 Study Streak — /streak

Tracks daily study activity to motivate students.

Method Endpoint Description
GET /streak Get current & longest streak
POST /streak/ping Mark today as active (call on login/activity)

Streak logic:

Daily ping received
  → If last_active_date = yesterday → current_streak + 1
  → If last_active_date = today → no change
  → If last_active_date < yesterday → reset to 1
  → Update longest_streak if current > longest

⭐ Feedback — /feedback

Method Endpoint Description
POST /feedback Submit feedback (stars + review)
GET /feedback List all feedback (admin)

🤖 AI Tutor Capabilities

Powered by Hugging Face (Mistral / Llama models):

Feature Description
Concept Explanation Explain any topic in simple terms
Follow-up Q&A Threaded multi-turn conversations
Note Generation Generate study notes for a topic
Question Practice Generate MCQs, short answers, long answers
Timetable Generation Smart schedule based on subjects & exam dates
Answer Saving Save AI answers tagged to topics

Context passed to AI:

- Student's class/grade
- Subject name
- Topic & subtopic (if selected)
- Previous Q&A in thread (for follow-ups)
- Student's question

🔔 Real-time Features (Flask-SocketIO)

Event Description
sketchpad:join Join collaborative whiteboard room
sketchpad:update Broadcast canvas strokes to collaborators
sketchpad:cursor Broadcast live cursor positions
sketchpad:leave Leave room
streak:updated Notify when streak updates

🚦 Rate Limiting

default_limits = ["500 per day", "100 per hour"]

# AI endpoints (model calls are expensive)
limiter.limit("50 per day;10 per hour")   # concept explainer
limiter.limit("20 per day;5 per hour")    # timetable generation

📧 Email System

Flask-Mail + Resend for transactional emails:

Trigger Email Sent
Registration Welcome + verify email
OTP request OTP code email
Password reset Reset link
Streak broken "Come back!" reminder
Weekly report Study summary

🚀 Deployment

Production with Gunicorn

gunicorn --worker-class eventlet -w 1 \
  --bind 0.0.0.0:5000 \
  --timeout 120 \
  server:app

With Nginx

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:5000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
    }
}

🔒 Security

  • JWT tokens with 7-day expiry
  • OTP-based email verification & password reset (via Resend)
  • Rate limiting on all endpoints (stricter on AI routes)
  • Cloudinary signed URLs for profile pictures
  • All credentials in .env (never committed)
  • SketchPad access controlled by unique code + permission enum

📊 Key Dependencies

# Web Framework
Flask==3.1.2
Flask-JWT-Extended==4.7.1
Flask-SocketIO==5.6.0
Flask-Limiter==4.1.1
Flask-Mail==0.10.0
resend==2.30.0

# Database
Flask-SQLAlchemy==3.1.1
Flask-Migrate==4.1.0
psycopg2-binary==2.9.12
alembic==1.18.1

# AI
huggingface_hub==1.7.1

# Storage
cloudinary==1.44.1
pillow==12.1.0

# Real-time & Cache
redis==7.1.1
eventlet==0.40.4

# Production
gunicorn==25.0.3

🎯 Who is Bobo for?

Student Type How Bobo Helps
School students (6th–12th) Subject tracking, timetable, concept explainer
College students Notes, topic progress, collaborative sketch pads
Competitive exam aspirants Topic-wise practice, streak motivation, AI Q&A
Self-learners Concept threads, saved notes, todo management

📄 License & Credits

This project is developed and maintained by Aditya Sharma.
All rights reserved © 2025 Aditya Sharma.

Built with ❤️ for students, by a developer who gets it.

About

An AI study companion for students that combines smart timetable planning, subject-topic-subtopic progress tracking, threaded concept explanations, note saving, daily streak motivation, todo management, and real-time collaborative whiteboards — all powered by Hugging Face AI.

Topics

python ai ai-agents

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages