🎓 AcadHub

Your Smart Academic Companion

---

⚡ What is AcadHub?

Track attendance. Manage schedules. Stay organized. All in one place.

AcadHub is a full-stack academic management platform built for college students to effortlessly track their attendance, manage timetables, monitor skills, and stay on top of their academic life.

---

🎯 Features at a Glance

📊 Attendance Tracking Real-time percentage calculations Bunk Calculator - Know when you can skip Medical leave tracking Multi-semester isolation Beautiful calendar heatmaps	📅 Smart Timetable Customizable periods & breaks Quick attendance from schedule Today's classes highlighted Subject color coding
📈 Analytics Dashboard Weekly attendance trends Subject-wise breakdowns Streak tracking Performance insights	🎓 Results Management SGPA/CGPA calculator Grade tracking per subject Credit-weighted calculations Grading key reference
🎯 Skills Tracker Track skill development Progress visualization Multiple categories Level badges	⌨️ Keyboard Shortcuts Ctrl+N → Notifications Ctrl+D → Dashboard Ctrl+T → Timetable Esc → Close modals Arrow keys → Scroll modals

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         AcadHub                                  │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐   │
│  │   Frontend   │  │    Mobile    │  │       Backend        │   │
│  │   (React)    │  │  (RN/Expo)   │  │      (Flask)         │   │
│  │              │  │              │  │                      │   │
│  │ • TypeScript │  │ • JavaScript │  │ • Python 3.8+        │   │
│  │ • Tailwind   │  │ • Native UI  │  │ • MongoDB Atlas      │   │
│  │ • Framer     │  │ • MMKV Cache │  │ • Google OAuth       │   │
│  │ • PWA Ready  │  │ • 120fps     │  │ • Socket.IO          │   │
│  └──────┬───────┘  └──────┬───────┘  └──────────┬───────────┘   │
│         │                 │                      │               │
│         └─────────────────┴──────────────────────┘               │
│                           │                                      │
│                    ┌──────┴──────┐                               │
│                    │  MongoDB    │                               │
│                    │   Atlas     │                               │
│                    └─────────────┘                               │
└─────────────────────────────────────────────────────────────────┘

---

🚀 Quick Start

Prerequisites

Node.js 18+  │  Python 3.8+  │  MongoDB URI  │  Google OAuth Credentials

🖥️ Web Development

# Clone & Setup
git clone https://github.com/kuberbassi/acadhub.git
cd acadhub

# Backend
python -m venv venv
.\venv\Scripts\Activate.ps1  # Windows
pip install -r requirements.txt
python run.py

# Frontend (new terminal)
cd frontend
npm install
npm run dev

Access: http://localhost:5173

📱 Mobile Development

cd mobile
npm install
npx expo start

🐳 Docker (Full Stack)

docker-compose up --build

Service	URL
Frontend	http://localhost:3000
Backend	http://localhost:5000
MongoDB	localhost:27017

---

⚙️ Configuration

Environment Variables

Backend (.env)

MONGO_URI=mongodb+srv://user:pass@cluster.mongodb.net/acadhub
FLASK_SECRET_KEY=your-super-secret-key
FLASK_ENV=development
GOOGLE_CLIENT_ID=xxxxx.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-xxxxx
GOOGLE_REDIRECT_URI=http://localhost:5000/api/auth/callback

Frontend (.env)

VITE_API_BASE_URL=http://localhost:5000
VITE_GOOGLE_CLIENT_ID=xxxxx.apps.googleusercontent.com

---

📁 Project Structure

acadhub/
├── 🌐 frontend/              # React + TypeScript + Tailwind
│   ├── src/
│   │   ├── components/       # Reusable UI components
│   │   ├── pages/            # Route pages
│   │   ├── hooks/            # Custom React hooks
│   │   ├── services/         # API service layer
│   │   └── contexts/         # React contexts
│   └── public/               # Static assets
│
├── 📱 mobile/                # React Native + Expo
│   ├── src/
│   │   ├── screens/          # Navigation screens
│   │   ├── components/       # Native components
│   │   ├── services/         # API + caching
│   │   └── contexts/         # Theme, Auth contexts
│   └── android/              # Android build files
│
├── 🔧 api/                   # Flask + MongoDB
│   ├── routes/               # API route handlers
│   ├── middleware/           # Security, logging
│   └── utils/                # Helper functions
│
├── 📄 vercel.json            # Deployment config
├── 🐳 docker-compose.yml     # Container orchestration
└── 📖 README.md              # You are here!

---

🔑 API Endpoints

Authentication

Method	Endpoint	Description
GET	/api/auth/google	Initiate Google OAuth
GET	/api/auth/callback	OAuth callback
POST	/api/auth/logout	End session
GET	/api/current_user	Get logged-in user

Subjects & Attendance

Method	Endpoint	Description
GET	/api/subjects	List all subjects
POST	/api/subjects	Create subject
PUT	/api/subjects/:id	Update subject
DELETE	/api/subjects/:id	Delete subject
POST	/api/mark_attendance	Mark attendance
GET	/api/attendance_logs	Get logs by date

Dashboard & Analytics

Method	Endpoint	Description
GET	/api/dashboard_data	Dashboard overview
GET	/api/reports_data	Analytics data
GET	/api/calendar_data	Calendar heatmap

---

🎨 Theming

AcadHub supports 12 accent colors with automatic dark/light mode:

Color	Hex
🔵 Blue	#0A84FF
💜 Purple	#BF5AF2
🟢 Green	#30D158
🟠 Orange	#FF9F0A
🔴 Red	#FF453A
🌸 Pink	#FF375F
🟡 Yellow	#FFD60A
🩵 Teal	#64D2FF
🟤 Brown	#AC8E68
🟣 Indigo	#5E5CE6
⚪ Mint	#66D4CF
🩶 Graphite	#8E8E93

---

⌨️ Keyboard Shortcuts

Shortcut	Action
Ctrl + N	Open Notifications
Ctrl + D	Go to Dashboard
Ctrl + T	Open Timetable
Ctrl + A	Open Analytics
Ctrl + Shift + C	Open Calendar
Ctrl + Shift + S	Open Settings
Escape	Close any modal
↑ / ↓	Scroll in modals
Page Up/Down	Fast scroll

---

🚢 Deployment

Vercel (Recommended)

1. Connect GitHub repo to Vercel
2. Configure environment variables
3. Deploy automatically on push

Live at: acadhub.kuberbassi.com

Mobile Release

# Build APK
cd mobile
npx expo prebuild --platform android --clean
cd android && ./gradlew assembleRelease

# APK location: android/app/build/outputs/apk/release/

---

📊 Performance

Metric	Score
Lighthouse	95+
Mobile FPS	120fps (ProMotion)
API Response	<100ms
Bundle Size	~250KB gzipped

---

🛡️ Security

• ✅ Google OAuth 2.0 authentication
• ✅ JWT token validation
• ✅ Rate limiting on API endpoints
• ✅ CORS protection
• ✅ XSS protection headers
• ✅ Secure session management

---

🤝 Contributing

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing)
5. Open Pull Request

---

📄 License

MIT License - see LICENSE for details.

---

👨‍💻 Author

Kuber Bassi

---

_{Built with ❤️ and ☕ using Agentic AI}

_{© 2024-2026 AcadHub. All rights reserved.}