Adaptive Learning Platform

A full-stack English language learning web application with an intelligent adaptive engine that personalizes the learning experience for each user based on their performance, skill level, and progress.

---

Features

• Adaptive Learning Path — lessons are dynamically ordered and prioritized based on each user's strengths and weaknesses
• Placement Test — new users take a pre-test to determine their starting level (A1 to C1)
• Spaced Repetition — SM-2 algorithm schedules lesson reviews at optimal intervals to maximize retention
• Early Promotion Detection — the system automatically suggests a level-up test when a user's mastery exceeds 85%
• Grammar Module — 13 grammar rules with 4 exercises each
• Vocabulary Module — word cards with status progression (New → Learning → Mastered)
• Listening Module — 15 audio tracks with comprehension questions across all CEFR levels
• Speaking Page — dedicated speaking practice interface
• AI Chatbot — conversational English tutor powered by the Bulbul AI API
• Skills Radar Heatmap — visual per-skill mastery dashboard (0–100)
• Progress Analytics — timeline and charts tracking XP, streaks, and lesson history
• Admin Dashboard — full CRUD management for all content (lessons, exercises, grammar, vocabulary, listening tracks)
• User Authentication — secure signup, login, password reset via email
• XP & Streak System — gamification to keep users motivated
• Level Gating — structured progression from A1 → A2 → B1 → B2 → C1

---

Tech Stack

Layer	Technology
Language	Java 21 (LTS)
Framework	Spring Boot 4.0.3
Database	MySQL 8 (production) / H2 (testing)
ORM	JPA / Hibernate
Frontend	Thymeleaf 6 + HTML / CSS / JavaScript
Security	Spring Security 6 + BCrypt
AI Integration	Bulbul API (Hugging Face)
Email	JavaMailSender (Gmail SMTP)
Build Tool	Maven

---

Requirements

Before running the project, make sure you have the following installed:

• Java 21
• Maven 3.8+
• MySQL 8

---

Getting Started

1. Clone the repository

git clone https://github.com/v7-klu9/Bulbul.git
cd adaptive-learning

2. Create the database

Open MySQL and run:

CREATE DATABASE adaptive_learning_db;

3. Configure the application

Open src/main/resources/application.properties and update your MySQL credentials:

spring.datasource.username=your_mysql_username
spring.datasource.password=your_mysql_password

4. Set up environment variables

The following environment variables are required for optional features:

Variable	Description
BULBUL_API_KEY	API key for the Bulbul AI chatbot and podcast features
MAIL_USERNAME	Gmail address used for sending password reset emails
MAIL_PASSWORD	Gmail App Password (not your regular Gmail password)

You can set them in your terminal before running:

# Windows (PowerShell)
$env:BULBUL_API_KEY = "your_key_here"
$env:MAIL_USERNAME  = "your_email@gmail.com"
$env:MAIL_PASSWORD  = "your_app_password"

# macOS / Linux
export BULBUL_API_KEY=your_key_here
export MAIL_USERNAME=your_email@gmail.com
export MAIL_PASSWORD=your_app_password

The app will start normally even if these are not set — the chatbot and email features will simply be disabled.

5. Run the application

./mvnw spring-boot:run

The app will start on http://localhost:8085

---

Admin Access

A default admin account is created automatically on first launch:

Field	Value
Email	admin@gmail.com
Password	@Admin12345

Access the admin dashboard at: http://localhost:8085/admin

It is strongly recommended to change the admin password after first login.

---

Project Structure

src/
├── main/
│   ├── java/com/example/adaptive_learning/
│   │   ├── config/        # Security, admin initializer
│   │   ├── controller/    # HTTP request handlers
│   │   ├── dto/           # Data transfer objects
│   │   ├── model/         # JPA entities
│   │   ├── repository/    # Spring Data repositories
│   │   ├── service/       # Business logic & adaptive engine
│   │   └── util/          # Helper utilities
│   └── resources/
│       ├── static/        # CSS, JS, images, audio files
│       ├── templates/     # Thymeleaf HTML templates
│       └── application.properties
└── test/                  # Unit tests

---

Learning Path Flow

/index → Login / Sign Up
  └→ Onboarding → Level select or Placement test
      └→ Dashboard
          ├→ Lessons       (adaptive path + daily plan)
          ├→ Vocabulary     (word cards + quiz)
          ├→ Grammar        (rules + exercises)
          ├→ Listening      (guided + free tracks)
          ├→ Speaking       (practice page)
          ├→ Progress       (analytics + timeline)
          └→ Skills         (radar heatmap)

---

CEFR Level System

Level	XP Required	Description
A1	400 XP	Beginner
A2	600 XP	Elementary
B1	800 XP	Intermediate
B2	1000 XP	Upper Intermediate
C1	1200 XP	Advanced

---

Running Tests

./mvnw test

---

License

This project is provided as a complete source code package. All rights reserved by the original author.