🧠 TWS AI – Cognitive Learning Platform

An Intelligent AI-Powered Learning Assistant

Final Year Project | 5th Semester | Computer Science
Developed by: Muhammad Abdullah

---

📌 Overview

TWS AI (The Wise Student AI) is a modern cognitive learning platform designed to enhance student learning using artificial intelligence.
It integrates real-time voice interaction, intelligent tutoring, adaptive assessments, and visual learning tools into one unified system.

This project demonstrates real-world usage of AI systems, algorithms, real-time processing, and full-stack development, developed as part of academic coursework.

---

📋 Table of Contents

• ✨ Features
• 🛠️ Tech Stack
• 🏗️ System Architecture
• 📁 Project Structure
• 🚀 Getting Started
• 🎯 Algorithms Implemented
• 📊 Complexity Analysis
• 📸 Screenshots
• 🎓 Learning Outcomes
• 📝 License

---

✨ Features

🤖 AI-Powered Learning

• Real-Time AI Voice Calls
  Practice speaking and explanation skills using live AI voice interaction.

• Intelligent Chat Assistant
  Get instant help with concepts, coding, summaries, and explanations.

• Diagram-Based Learning
  Generate technical diagrams to visualize complex topics.

• Adaptive Quiz System
  AI-generated quizzes based on topic, difficulty, and user progress.

---

💻 Interactive Learning Tools

• Coding Helper – Real-time code assistance with voice monitoring
• Learning Paths – 3-month structured roadmaps
• Mock Interviews – Practice technical and HR interviews
• Progress Analytics – Track goals, study time, and achievements

---

🔐 User Management & Gamification

• Secure authentication with OAuth
• Cloud-synced notes and progress
• Personalized dashboards
• XP, badges, and achievement system

---

🛠️ Tech Stack

-------Layer------	Technology	Purpose
Frontend	React 19 + TypeScript	UI & State Management
Styling	Tailwind CSS	Responsive UI
Backend	Supabase (PostgreSQL)	Database & Auth
AI Engine	Gemini API	Text, Vision & Audio
Authentication	Firebase Auth	Google OAuth
Email	EmailJS	OTP & Notifications
Audio	Web Audio API	Live voice streaming
Diagrams	Mermaid.js	Visual learning

---

🏗️ System Architecture

┌─────────────────────────────────────────────────────────┐ │ React Frontend │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ Dashboard│ │ AI Chat │ │Voice Call│ │ Coding │ │ │ │ │ │ │ │ │ │ Helper │ │ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ └─────────────────┬────────────┬────────────┬─────────────┘ │ | | ┌───────────▼──┐ ┌───────▼──────┐ ┌───▼───────────┐ │ Supabase │ │ Gemini API │ │ Firebase │ │ • Database │ │ • AI Logic │ │ • OAuth │ │ • Auth │ │ • Live Audio │ │ • Auth │ └──────────────┘ └──────────────┘ └───────────────┘

---

📁 Project Structure

src/ ├── components/ │ ├── AICall.tsx │ ├── AIChat.tsx │ ├── CodingHelper.tsx │ ├── LearningPaths.tsx │ ├── Quiz.tsx │ ├── LearnByDiagrams.tsx │ ├── Dashboard.tsx │ ├── Analytics.tsx │ ├── Achievements.tsx │ └── Settings.tsx ├── services/ │ ├── geminiService.ts │ ├── supabaseClient.ts │ ├── firebaseConfig.ts │ └── emailService.ts ├── contexts/ │ └── AuthContext.tsx ├── utils/ │ ├── audioUtils.ts │ └── base64Utils.ts ├── types/ │ └── index.ts └── constants.ts

---

🚀 Getting Started

Prerequisites

• Node.js 18+
• Gemini API Key
• Supabase Account
• Firebase Project

Installation

git clone https://github.com/your-username/tws-ai.git
cd tws-ai
npm install
Environment Setup
cp .env.example .env.local
GEMINI_API_KEY=your_api_key
VITE_SUPABASE_URL=your_supabase_url
VITE_SUPABASE_ANON_KEY=your_supabase_key
VITE_EMAILJS_SERVICE_ID=your_service_id
VITE_EMAILJS_TEMPLATE_ID=your_template_id
VITE_EMAILJS_PUBLIC_KEY=your_public_key
Run Application
npm run dev
Open http://localhost:5173

🎯 Algorithms Implemented
1. Real-Time Audio Streaming
Time Complexity: O(n)

Space Complexity: O(k)

PCM encoding with buffered streaming

2. Exponential Backoff Retry
Handles API rate limits

Worst-Case Delay: O(2ᵏ)

3. Adaptive Quiz Generation
Topic → AI → JSON → UI

Time Complexity: O(1)

4. State Synchronization
Centralized auth state management

Time Complexity: O(1)

📊 Complexity Analysis
Component	Time	Space
Audio Processing	O(n)	O(k)
Chat Rendering	O(m)	O(m)
Database Queries	O(log N)	O(1)
Quiz Generation	O(1)	O(1)
UI Updates	O(c)	O(c)
📸 Screenshots
Dashboard Interface

Real-Time AI Voice Call

Coding Helper

Learning Analytics

(Add screenshots in /assets folder)

🎓 Learning Outcomes
Technical Skills
Full-stack web development

AI & API integration

Real-time audio systems

Advanced TypeScript usage

Algorithmic Skills
Big-O complexity analysis

Optimization strategies

Error handling & retries

Async & concurrency management

Software Engineering
Modular architecture

Clean & maintainable code

Secure authentication

Performance optimization

📝 License
This project was developed for academic purposes.
All rights reserved by [Your Name].

<div align="center">
Built with passion during 5th Semester – Computer Science
Submitted to: [Professor's Name]
Department of Computer Science
[Your University Name]

⭐ If you find this project helpful, please give it a star ⭐

</div> ```