🧠 TWS AI — The Wise Student

An AI-powered cognitive learning platform built to make studying smarter, more interactive, and personalized.

🚀 Learn. Practice. Build. Level Up.

---

🌟 Overview

TWS AI (The Wise Student) is an AI-powered learning platform designed to transform the traditional study experience into an interactive, personalized, and engaging learning journey.

Instead of relying on disconnected tools for studying, coding, quizzes, diagrams, and learning plans, TWS AI brings them together into a unified platform powered by Google Gemini AI.

Whether you're learning a programming concept, having a real-time voice conversation with an AI tutor, visualizing a complex topic, practicing MCQs, or following a structured learning roadmap, TWS AI is designed to act as your intelligent study companion.

---

✨ Why TWS AI?

Traditional learning often means switching between multiple platforms:

📚 Notes → 🎥 Videos → 🤖 AI Chat → 🧑‍💻 Coding Environment → 📝 Quizzes → 📊 Progress Tracking

TWS AI brings these experiences together.

🎯 One Platform. Multiple Learning Experiences.

Feature	What it provides
🤖 AI Chat	Context-aware AI tutoring with persistent conversations
🎙️ AI Voice Call	Real-time voice-based learning with interactive conversations
💻 Coding IDE	Analyze and execute code while receiving AI assistance
🧠 Neural Canvas	Convert natural language into visual Mermaid diagrams
🗺️ Learning Paths	Structured 3-month learning roadmaps
📝 Quiz Vault	Dynamically generated MCQs with XP rewards
🏆 Achievements	Unlock milestones as you progress
⚡ XP & Levels	Gamified progression across learning activities
📊 Dashboard	Track learning activity, XP, achievements, and progress

---

🚀 Core Features

🤖 AI Chat

A context-aware AI tutor designed for interactive learning.

• Persistent chat history
• Context-aware conversations
• AI-powered explanations
• Programming assistance
• Concept clarification
• Personalized learning interaction

The goal is not simply to provide answers, but to create an interactive tutoring experience.

---

🎙️ AI Voice Call

Have a real-time conversation with your AI tutor.

Powered by Gemini's live audio capabilities, the voice experience allows students to interact naturally instead of relying entirely on text.

Highlights

• Real-time voice interaction
• Conversational AI tutoring
• Live learning discussions
• Interactive explanations
• Live diagram generation during conversations

---

💻 Coding IDE

A dedicated environment for learning and experimenting with code.

Features

• Code editing
• AI-assisted code analysis
• Code execution
• Voice-monitored coding interaction
• Programming-focused AI assistance

TWS AI combines the learning experience with a development environment so students can learn → write → test → understand in one workflow.

---

🧠 Neural Canvas

Turn ideas and explanations into visual diagrams.

Users can describe a concept naturally, and TWS AI can generate Mermaid-based diagrams to visualize it.

Example

Prompt:

"Explain how a client communicates with a backend API"

Generated Diagram:

flowchart LR
    A[Client] --> B[API]
    B --> C[Backend]
    C --> D[Database]
    D --> C
    C --> B
    B --> A

Loading

This makes complex technical concepts easier to understand visually.

---

🗺️ Learning Paths

Follow structured learning roadmaps instead of randomly jumping between resources.

Learning paths provide:

• Structured progression
• Curated topics
• 3-month learning roadmaps
• Video resource integration
• Progressive skill development

The objective is to give learners a clear answer to:

"What should I learn next?"

---

📝 Quiz Vault

Test your understanding with dynamically generated quizzes.

Features

• AI-generated MCQs
• Multiple difficulty levels
• XP rewards
• Learning-focused questions
• Instant progression feedback

Quizzes transform passive learning into active recall and practice.

---

🎮 Gamification System

Learning becomes more engaging through a built-in progression system.

🏆 Achievement System

Unlock milestones as you interact with the platform.

The system includes 6+ unlockable achievements covering different learning activities.

⚡ XP & Levels

Earn XP through activities such as:

• Completing quizzes
• AI voice sessions
• Learning challenges
• Other platform activities

Your progress is reflected throughout the dashboard.

📊 Dashboard

A centralized dashboard provides real-time learning statistics and animated progress indicators.

---

🔐 Authentication & Data

TWS AI uses a hybrid authentication architecture.

Authentication

• 📧 Email & Password
• 🔵 Google OAuth

Cloud Data

User data is synchronized using Supabase and PostgreSQL.

This enables persistent storage for platform data and user activity.

---

🛠️ Technology Stack

Technology	Role
⚛️ React 19	Frontend application
🔷 TypeScript	Type-safe development
⚡ Vite	Development & build tooling
🎨 Tailwind CSS	UI styling
🤖 Google Gemini AI	AI, live audio & image capabilities
🗄️ Supabase	PostgreSQL database & authentication
📊 Mermaid.js	Dynamic diagram generation

---

🏗️ Platform Architecture

┌─────────────────────────────────────────────┐
│                 TWS AI                      │
│        The Wise Student Platform            │
└──────────────────────┬──────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────┐
│              React 19 + TypeScript          │
│                                             │
│  AI Chat │ Voice │ IDE │ Canvas │ Quizzes  │
│  Paths   │ Dashboard │ Achievements         │
└───────────────┬─────────────────┬───────────┘
                │                 │
                ▼                 ▼
      ┌─────────────────┐   ┌─────────────────┐
      │  Google Gemini  │   │    Supabase     │
      │       AI        │   │                 │
      │                 │   │  PostgreSQL     │
      │ • Chat          │   │  Authentication │
      │ • Live Audio    │   │  Cloud Sync     │
      │ • Flash         │   │  User Data      │
      │ • Image         │   │                 │
      └─────────────────┘   └─────────────────┘
                │
                ▼
      ┌─────────────────┐
      │   Mermaid.js    │
      │                 │
      │ Visual Learning │
      │   & Diagrams    │
      └─────────────────┘

---

📸 Screenshots

Screenshots of the major platform features will be added here.

🤖 AI Chat

🎙️ AI Voice Call

💻 Coding IDE

🧠 Neural Canvas

📝 Quiz Vault

📊 Learning Dashboard

---

🌐 Live Demo

🚀 Try TWS AI

https://twsai.netlify.app/

---

📦 Installation

Prerequisites

Make sure you have the following installed:

• Node.js
• npm
• A Google Gemini API key
• A Supabase project

---

1. Clone the Repository

git clone https://github.com/AbdullahSoftDev/The-Wise-Student-Ai-Learning-Platform.git

cd The-Wise-Student-Ai-Learning-Platform

---

2. Install Dependencies

npm install

---

3. Configure Environment Variables

Create a local environment file:

cp .env.example .env.local

Add your Gemini API key:

GEMINI_API_KEY=your_gemini_api_key

Configure the required Supabase variables according to your project setup.

---

4. Database Setup

The database schema is included in:

schema.sql

Open your Supabase project and execute the schema through the Supabase SQL Editor.

---

5. Start the Development Server

npm run dev

Vite will start the development server and provide the local URL.

---

🔧 Environment Variables

Variable	Description
GEMINI_API_KEY	Google Gemini API key
Supabase variables	Supabase project configuration

⚠️ Never commit .env.local or expose private API keys in your repository.

---

📜 Available Scripts

# Start development server
npm run dev

# Build production version
npm run build

# Preview production build
npm run preview

# TypeScript validation
npm run lint

---

📁 Project Structure

The-Wise-Student-Ai-Learning-Platform/
│
├── public/
│
├── src/
│   ├── components/
│   ├── pages/
│   ├── services/
│   ├── hooks/
│   ├── utils/
│   └── ...
│
├── schema.sql
├── .env.example
├── package.json
├── tsconfig.json
├── vite.config.ts
└── README.md

The exact structure may evolve as the platform continues to develop.

---

🗺️ Roadmap

✅ v1.0.0

• AI Chat
• AI Voice Call
• Coding IDE
• Neural Canvas
• Learning Paths
• Quiz Vault
• XP system
• Achievement system
• Dashboard
• Hybrid authentication
• Supabase integration

🔮 Future Improvements

Potential future development areas include:

• Expanded AI tutoring modes
• More programming languages
• Advanced learning analytics
• More achievement categories
• Expanded learning path library
• Collaborative learning features
• Additional AI-powered study tools

---

🤝 Contributing

Contributions, suggestions, and feedback are welcome.

Before contributing, please review the project's contribution guidelines in:

CONTRIBUTING.md

Contribution Workflow

# Fork the repository

# Create a feature branch
git checkout -b feature/your-feature

# Commit your changes
git commit -m "Add: your feature"

# Push the branch
git push origin feature/your-feature

# Open a Pull Request

---

🐛 Issues & Feedback

Found a bug or have an idea?

Please open an issue in the GitHub repository:

The Wise Student — GitHub Repository

When reporting an issue, include:

• Description of the problem
• Steps to reproduce
• Expected behavior
• Actual behavior
• Screenshots or logs when applicable

---

📄 License

Private — All Rights Reserved.

This project is not currently licensed for redistribution, modification, or commercial use without permission from the project owner.

---

📌 Version History

v1.0.0 — Initial Release

• AI Chat
• AI Voice Call
• Coding IDE
• Neural Canvas
• Learning Paths
• Quiz Vault
• XP & Level progression
• Achievement system
• Learning dashboard
• Hybrid authentication
• Google OAuth
• Supabase cloud synchronization
• Personal API key management

---

🧠 TWS AI

The Wise Student

Learn Smarter. Build Faster. Grow Further.

🌐 Live Platform • 💻 GitHub Repository

Built with ❤️ using React, TypeScript, Google Gemini AI, and Supabase