Smart Vocabulary Trainer

This project is an API for a smart vocabulary training application, built with Laravel 12. The system's primary goal is to optimize the vocabulary learning process through adaptive algorithms and personalized exercises.

✨ Key Features

• Spaced Repetition System: Utilizes the SM-2 algorithm to intelligently select words the user is about to forget. The system prioritizes words based on their next review date, mastery level, and difficulty.
• Intelligent Multiple-Choice Question Generation: For each word, a 4-option question is generated, including the correct answer and 3 distractors. Distractors are carefully chosen to match the difficulty level and part of speech of the target word.
• Asynchronous Answer Processing: User answers are processed in the background using Laravel Jobs to ensure a fast and responsive API.
• Clean & Scalable Architecture: The project follows Clean Code principles and a Service-Oriented Architecture for high maintainability and extensibility.
• Comprehensive Test Coverage: All key components, including the exercise generation logic and the API endpoints, are covered by Unit and Feature tests to ensure system correctness.

🛠️ Tech Stack

• Backend: Laravel 12, PHP 8.2
• Database: MySQL / SQLite
• Authentication: Laravel Sanctum
• Testing: PHPUnit

🚀 Setup and Installation

Follow these steps to set up the project locally:

1. Clone the project:

   git clone <repository_url>
   cd <project_directory>

2. Install dependencies:

   composer install

3. Environment Setup: Copy the .env.example file to .env and generate the application key.

   cp .env.example .env
   php artisan key:generate

4. Database Configuration: Enter your database connection details in the .env file.

   DB_CONNECTION=mysql
   DB_HOST=127.0.0.1
   DB_PORT=3306
   DB_DATABASE=oteacher_learning
   DB_USERNAME=root
   DB_PASSWORD=

5. Run Migrations and Seeders: This command creates the database tables and populates them with initial data (a default user and a vocabulary list).

   php artisan migrate --seed

   • Default User: email: user@example.com, password: password

6. Run the local server:

   php artisan serve

   The API is now available at http://127.0.0.1:8000.

🧪 Running Tests

To run the project's test suite, use the following command:

php artisan test

📖 API Usage Guide

The Accept: application/json header is required for all requests.

1. Authentication

To access protected endpoints, you first need to obtain an access token. This project uses a simple token system. After running the seeder, you can use the default user's credentials to get a token. In a real-world project, a login endpoint would handle this.

Grab a token from the personal_access_tokens table for the default user and use it as a Bearer Token in the Authorization header.

2. Get a New Exercise

• Endpoint: GET /api/v1/exercises
• Method: GET
• Protected: Yes

This endpoint creates and returns a new exercise with 10 questions for the authenticated user.

Sample Success Response (200 OK):

{
    "data": {
        "exercise_id": 1,
        "status": "pending",
        "questions": [
            {
                "question_id": 1,
                "word": "Book",
                "options": [
                    "Libro",
                    "Casa",
                    "Mela",
                    "Auto"
                ]
            },
            {
                "question_id": 2,
                "word": "Run",
                "options": [
                    "Mangiare",
                    "Dormire",
                    "Correre",
                    "Leggere"
                ]
            }
            // ... 8 more questions
        ]
    }
}

3. Submit Answers

• Endpoint: POST /api/v1/exercises/{exercise_id}/submit
• Method: POST
• Protected: Yes

This endpoint receives the user's answers for a specific exercise and queues them for processing.

Sample Request Body:

{
    "exercise_id": 1,
    "answers": [
        {
            "question_id": 1,
            "answer": "Libro"
        },
        {
            "question_id": 2,
            "answer": "Dormire"
        }
        // ... 8 more answers
    ]
}

Sample Success Response (202 Accepted):

{
    "message": "Your answers have been submitted and are being processed."
}

This response indicates that the answers have been successfully received and processing has begun in the background.