GitHub - samiahraf/study-dost-ai: 🧠 Study Dost AI - Your AI study buddy that explains STEM concepts 3 ways, helps you practice, and rewards your curiosity

🎯 The Problem

"Textbooks explain things one way. But every student's brain learns differently."

💡 The Solution

Study Dost AI explains any STEM concept in 3 different ways simultaneously — step-by-step, real-world analogy, and visual cue — so the explanation that clicks with YOU is always one click away.

3 Explanation Styles
_{Step-by-step • Analogy • Visual}

Gamified Learning
_{XP • Levels • Badges • Streaks}

Country-Aware
_{Bangladesh • India • Global}

📑 Table of Contents

🗂 Click to expand

✨ Features
🎬 Live Demo
🏗 Architecture
⚡ Quick Start
📦 Deployment
⚙️ Configuration
🧩 Tech Stack
🛡 Security
🎯 Roadmap
🤝 Contributing
📜 License
📬 Contact

✨ Features

🎓 Core Learning Engine

🔢 Triple Explanation Engine

Get any concept explained 3 different ways at once:

📝 Step-by-Step — methodical walkthrough
🌍 Real-World Analogy — relatable comparisons
🎨 Visual Cue — sketchable diagrams

🎯 Smart Practice Problems

AI-generated practice with adaptive difficulty:

🟢 Easy — concept reinforcement
🟡 Medium — applied thinking
🔴 Hard — JEE/NEET/HSC level

👶 ELI10 Mode

"Explain Like I'm 10" — ultra-simple breakdowns when something just isn't clicking. Perfect for breaking through learning blocks.

🌍 Country-Aware Curriculum

Tailored to your education system:

🇧🇩 NCTB / SSC / HSC / Creative Questions
🇮🇳 NCERT / CBSE / JEE / NEET
🌐 International standards

🎮 Gamification System

🏆 XP & Levels _{Level up as you learn}	🔥 Daily Streaks _{Build consistency}	🎖️ Achievement Badges _{Unlock milestones}	🎉 Confetti Rewards _{Celebrate wins}
🐾 Pet Mascot _{Animated companion}	🎨 5 Themes _{Midnight, Cosmic+}	💾 Favorites _{Save explanations}	📝 History _{Auto-saved sessions}

🚀 Advanced Features

🎤 Click to see all power features

Feature	Description
🎤 Voice Input	Ask questions using speech recognition
🗣️ Text-to-Speech	Listen to explanations hands-free
📐 LaTeX Math	Beautiful equation rendering with KaTeX
💻 Code Highlighting	Syntax-highlighted code blocks
📱 Mobile-First	Drawer navigation, touch-optimized
⚡ Offline-Capable	localStorage for instant load
🔄 API Failover	Multi-key rotation for 99.9% uptime
🛡️ CORS Protected	Locked to your domain
🎯 Suggestion Chips	Quick-start prompts
♿ Accessible	Screen-reader friendly

🎬 Live Demo

🌐 Try it now → samiahrafnirob.com/study-dost

_{Best for full experience}

_{Optimized drawer UI}

_{Easy on the eyes}

🏗 Architecture

graph LR
    A[👨‍🎓 Student] -->|HTTPS| B[🌐 Frontend<br/>InfinityFree]
    B -->|API Call| C[🚀 Cloudflare Tunnel]
    C -->|Proxy| D[🐍 FastAPI Backend<br/>RDP Server]
    D -->|LLM Request| E[🤖 Featherless.ai<br/>DeepSeek-V3]
    E -->|Response| D
    D -->|JSON| C
    C -->|HTTPS| B
    B -->|Rendered| A
    
    style A fill:#FFD93D,stroke:#333,color:#000
    style B fill:#4ECDC4,stroke:#333,color:#000
    style C fill:#F38BA8,stroke:#333,color:#000
    style D fill:#A8DADC,stroke:#333,color:#000
    style E fill:#C9ADA7,stroke:#333,color:#000

🧱 Why Split Architecture?

Component	Where It Lives	Why
🎨 Frontend _HTML/CSS/JS	InfinityFree, Netlify, GitHub Pages, any static host	Fast CDN delivery, zero server cost, no build step
⚙️ Backend _{FastAPI + Python}	RDP / VPS / Cloud VM	Hides API keys, full Python ecosystem, scalable
🔌 Connection	Cloudflare Tunnel (HTTPS)	Free HTTPS, no port forwarding, DDoS protected

📁 Project Structure

📂 Click to view full directory tree

study-dost-ai/
│
├── 🎨 frontend/                    # Static web app (deploy anywhere)
│   ├── index.html                  # Main app shell
│   ├── styles.css                  # Themes + responsive design
│   ├── app.js                      # Application logic
│   ├── config.js                   # Backend URL configuration
│   └── README.md                   # Frontend docs
│
├── ⚙️  backend/                    # FastAPI service
│   ├── main.py                     # API endpoints + CORS
│   ├── utils.py                    # LLM client + response parser
│   ├── prompts.py                  # Prompt templates
│   ├── requirements.txt            # Python dependencies
│   ├── install.bat                 # Windows installer
│   ├── start.bat                   # Windows launcher
│   ├── .env.example                # Config template
│   └── README.md                   # Backend docs
│
├── 🌐 infinityfree/                # InfinityFree-ready bundle
│   └── (same as frontend/)
│
├── 🖥️  rdp/                        # RDP deployment bundle
│   └── (same as backend/)
│
├── 📜 LICENSE                      # MIT License
├── 📖 README.md                    # You are here ✨
├── 📘 GIT_SETUP_GUIDE.md           # Git + GitHub walkthrough
└── 🚫 .gitignore                   # Protects your secrets

⚡ Quick Start

Get running in 5 minutes ⏱️

📋 Prerequisites

🐍	Python 3.10+
🔑	Featherless.ai API Key (free tier available)
🌐	Any web browser

🚀 Installation

🔧 Step 1: Clone the repository

git clone https://github.com/samiahrafnirob/study-dost-ai.git
cd study-dost-ai

⚙️ Step 2: Set up the backend

cd backend

# Create virtual environment
python -m venv .venv
.\.venv\Scripts\Activate.ps1     # Windows PowerShell
# source .venv/bin/activate       # macOS/Linux

# Install dependencies
pip install -r requirements.txt

# Configure environment
copy .env.example .env
# Edit .env → paste your FEATHERLESS_API_KEY

# Launch server 🚀
python main.py

✅ Backend running at http://localhost:8000
📖 Swagger docs at http://localhost:8000/docs

🎨 Step 3: Launch the frontend

cd ../frontend

# Edit config.js
# window.CC_CONFIG = {
#   API_BASE: "http://localhost:8000",
#   API_KEY: ""
# };

# Serve locally
python -m http.server 5500

✅ Open http://localhost:5500 in your browser 🎉

📦 Deployment

Choose your deployment combo:

🎨 Frontend Host	⚙️ Backend Host	🔗 HTTPS Bridge
✅ InfinityFree ✅ Netlify ✅ Vercel ✅ GitHub Pages ✅ Cloudflare Pages	✅ Windows RDP ✅ Linux VPS ✅ AWS EC2 ✅ DigitalOcean ✅ Railway / Render	✅ Cloudflare Tunnel ✅ Caddy (auto-HTTPS) ✅ Nginx + Certbot ✅ ngrok ✅ Tailscale Funnel

🖥️ Deploy Backend on Windows RDP

📝 Click for full RDP deployment guide

# 1. Copy the rdp/ folder to your RDP
# 2. Install dependencies
.\install.bat

# 3. Configure .env
notepad .env

# 4. Launch the server
.\start.bat

# 5. Expose with Cloudflare Tunnel (free HTTPS)
Invoke-WebRequest `
  -Uri "https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-windows-amd64.exe" `
  -OutFile "$env:USERPROFILE\cloudflared.exe"

& "$env:USERPROFILE\cloudflared.exe" tunnel --url http://localhost:8000
# → Copy the https://xxxxx.trycloudflare.com URL

Then paste that URL into frontend/config.js as your API_BASE. Done! 🎉

🌐 Deploy Frontend on InfinityFree

📝 Click for full InfinityFree deployment guide

Sign up at infinityfree.net
Create site: samiahrafnirob.com/study-dost/
Upload all files from infinityfree/ to htdocs/study-dost/ via FTP
Edit config.js on the server to point to your backend HTTPS URL
Visit your live site → 🎊

// infinityfree/config.js
window.CC_CONFIG = {
  API_BASE: "https://your-cloudflare-tunnel-url.trycloudflare.com",
  API_KEY: ""  // optional, must match backend APP_API_KEY
};

⚙️ Configuration

🔐 Backend .env file

# 🔑 REQUIRED: Featherless.ai API key
FEATHERLESS_API_KEY=rc_your_api_key_here

# 🔄 OPTIONAL: Backup keys for failover
FEATHERLESS_API_KEY_BACKUP=rc_backup_key_1
FEATHERLESS_API_KEY_BACKUP_2=rc_backup_key_2

# 🛡️ OPTIONAL: App-level authentication
APP_API_KEY=your_optional_shared_secret

# 🌐 CORS: Comma-separated allowed origins
ALLOWED_ORIGINS=https://samiahrafnirob.com,http://localhost:5500

# 🚀 Server settings
PORT=8000
HOST=0.0.0.0

🎨 Frontend config.js file

window.CC_CONFIG = {
  // Your backend's HTTPS URL
  API_BASE: "https://your-backend-url.com",
  
  // Must match backend's APP_API_KEY (if set)
  API_KEY: "",
  
  // Default country: "default" | "bangladesh" | "india"
  DEFAULT_COUNTRY: "default",
  
  // Default theme: "midnight" | "cosmic" | "sunset" | "forest" | "light"
  DEFAULT_THEME: "midnight"
};

🧩 Tech Stack

🛠️ Built With

Python 3.10+	FastAPI	JavaScript	HTML5	CSS3
Uvicorn	Cloudflare	OpenAI SDK	KaTeX	Marked.js

📊 Full dependency breakdown

Layer	Library	Purpose
Backend	FastAPI	Web framework
Backend	Uvicorn	ASGI server
Backend	OpenAI SDK	Featherless API client
Backend	python-dotenv	Env var loading
Backend	Pydantic	Data validation
Frontend	marked.js	Markdown rendering
Frontend	DOMPurify	XSS protection
Frontend	KaTeX	LaTeX math rendering
Frontend	highlight.js	Code syntax highlighting
AI	DeepSeek-V3-0324	Language model
Hosting	Cloudflare Tunnel	HTTPS exposure

🛡 Security

🔐	API keys never reach the browser — they live only in the backend `.env`
🌐	CORS locked to your domain via `ALLOWED_ORIGINS`
🔑	Optional shared secret (`APP_API_KEY`) for extra auth layer
🔒	HTTPS enforced via Cloudflare Tunnel / Caddy
🧹	Input sanitized with DOMPurify before rendering
🚫	`.env` always gitignored — no leaks ever

🎯 Roadmap

Status	Feature	Target
✅	Triple explanation engine	v1.0
✅	Country-aware curriculum	v1.0
✅	Gamification (XP, badges)	v1.0
✅	Mobile responsive UI	v1.0
✅	Voice input/output	v1.0
🚧	Multi-language UI (Bengali, Hindi)	v1.1
📋	User accounts + cloud sync	v1.2
📋	PDF export for notes	v1.2
📋	Quiz mode with leaderboards	v1.3
📋	Collaborative study rooms	v2.0
📋	Native mobile apps	v2.0

🤝 Contributing

All contributions are welcome! 🎉

🔧 How to contribute

Fork the repository
Create your feature branch
```
git checkout -b feature/AmazingFeature
```

Commit your changes

git commit -m "feat: add AmazingFeature"

Push to the branch
```
git push origin feature/AmazingFeature
```
Open a Pull Request

📝 Commit Convention

We follow Conventional Commits:

feat: New feature
fix: Bug fix
docs: Documentation
style: Formatting
refactor: Code restructure
test: Tests
chore: Maintenance

📜 License

This project is licensed under the MIT License — see LICENSE for details.

Copyright (c) 2026 Sami Ahraf Nirob

You are free to use, modify, and distribute this software. 🎉

📬 Contact

👨‍💻 Sami Ahraf Nirob

🌟 Show Your Support

If this project helped you, please consider:

⭐ Starring this repo
🐦 Sharing on social media
🐛 Reporting bugs
💡 Suggesting features
🤝 Contributing code

**Built with passion for students worldwide**

Navigation Menu

Repository files navigation

🎯 The Problem

💡 The Solution

📑 Table of Contents

✨ Features

🎓 Core Learning Engine

🔢 Triple Explanation Engine

🎯 Smart Practice Problems

👶 ELI10 Mode

🌍 Country-Aware Curriculum

🎮 Gamification System

🚀 Advanced Features

🎬 Live Demo

🌐 Try it now → samiahrafnirob.com/study-dost

🏗 Architecture

🧱 Why Split Architecture?

📁 Project Structure

⚡ Quick Start

Get running in 5 minutes ⏱️

📋 Prerequisites

🚀 Installation

📦 Deployment

🖥️ Deploy Backend on Windows RDP

🌐 Deploy Frontend on InfinityFree

⚙️ Configuration

🧩 Tech Stack

🛠️ Built With

🛡 Security

🎯 Roadmap

🤝 Contributing

📝 Commit Convention

📜 License

📬 Contact

👨‍💻 Sami Ahraf Nirob

🌟 Show Your Support

About

Releases

Packages

Contributors

Name		Name	Last commit message	Last commit date
backend		backend
frontend		frontend
.gitignore		.gitignore
README.md		README.md

Latest commit

History

Folders and files

Repository files navigation

🎯 The Problem

💡 The Solution

📑 Table of Contents

✨ Features

🎓 Core Learning Engine

🔢 Triple Explanation Engine

🎯 Smart Practice Problems

👶 ELI10 Mode

🌍 Country-Aware Curriculum

🎮 Gamification System

🚀 Advanced Features

🎬 Live Demo

🌐 Try it now → samiahrafnirob.com/study-dost

🏗 Architecture

🧱 Why Split Architecture?

📁 Project Structure

⚡ Quick Start

Get running in 5 minutes ⏱️

📋 Prerequisites

🚀 Installation

📦 Deployment

🖥️ Deploy Backend on Windows RDP

🌐 Deploy Frontend on InfinityFree

⚙️ Configuration

🧩 Tech Stack

🛠️ Built With

🛡 Security

🎯 Roadmap

🤝 Contributing

📝 Commit Convention

📜 License

📬 Contact

👨‍💻 Sami Ahraf Nirob

🌟 Show Your Support

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors