Language Learning App API

Description

This repository contains the backend API for the Language Learning application. It is built using the Laravel framework and provides the core functionalities for managing users, quizzes, results, and interactions with AI language models.

This API is intended to be consumed by a separate frontend application (e.g., a web app or mobile app).

Features

• User Authentication:
  • User Registration
  • User Login (JWT-based)
  • Get Authenticated User Details (/auth/me)
  • Token Refresh
  • User Logout
• Quiz Management:
  • Create new quizzes
  • List all quizzes (index)
  • List quizzes created by the authenticated user
  • Show details of a specific quiz (using MongoDB ID)
  • Delete quizzes
• Favorite Quizzes:
  • Add a quiz to user's favorites
  • List user's favorite quizzes
  • Remove a quiz from user's favorites
• Quiz Results:
  • Record results for completed quizzes
  • List user's quiz results
  • Delete specific quiz results
• AI Integration:
  • Interact with Google Gemini
  • Interact with OpenAI
  • Interact with Llama (placeholder/example)

Technologies Used

• Backend: PHP, Laravel Framework
  • tymon/jwt-auth for JWT Authentication
  • mongodb/mongodb Laravel MongoDB Driver
  • google-gemini-php/client for Gemini AI
  • openai-php/client for OpenAI
  • (Assumed Llama integration via a similar SDK or direct API calls)
• Databases:
  • PostgreSQL: Stores user data, quiz metadata (title, description, user ID), favorite relationships, and result summaries.
  • MongoDB: Stores the detailed quiz content (questions, answers, options, etc.) linked via a reference in the PostgreSQL quizzes table.
• Dependency Management: Composer (PHP), NPM (Node.js for frontend assets, if any, and development tools)

Prerequisites

• PHP (Version specified in composer.json, likely >= 8.1)
• Composer
• Node.js and NPM
• PostgreSQL Server
• MongoDB Server
• A web server like Nginx or Apache (for production), or use php artisan serve for development.

Getting Started

1. Clone the repository:

   git clone <repository-url>
   cd language-app

2. Install PHP dependencies:

   composer install

3. Install Node.js dependencies (if needed for development tools):

   npm install

4. Setup Environment:
   • Copy the example environment file: cp .env.example .env
   • Configure your database credentials (PostgreSQL DB_* variables and MongoDB DB_MONGO_* variables), JWT settings (JWT_SECRET), and AI API keys (GEMINI_API_KEY, OPENAI_API_KEY, etc.) in the .env file.
5. Generate Application Key:

   php artisan key:generate

6. Generate JWT Secret:

   php artisan jwt:secret

   (Ensure this command successfully adds a JWT_SECRET to your .env file or add it manually)
7. Run Database Migrations (PostgreSQL):

   php artisan migrate

8. (Optional) Seed the database:

   php artisan db:seed

9. Run the development server:

   php artisan serve

   The API will typically be available at http://localhost:8000.

Usage / API Testing

The primary way to interact with this API during development is through an API client like Postman.

1. Import the Collection: Import the postman-config.json file (located in the project root) into Postman.
2. Configure Environment: Ensure the {{baseUrl}} variable in your Postman environment points to your running application's API endpoint (e.g., http://localhost:8000/api).
3. Authentication:
   • Use the "Auth > Register" request to create a new user.
   • Use the "Auth > Login" request with the registered user's credentials. The included test script should automatically capture the access_token and store it in the {{authToken}} collection variable.
4. Making Authenticated Requests: Most other endpoints require authentication. Postman is configured to use the {{authToken}} variable as a Bearer Token for requests within the protected folders (Quizzes, Favorite Quizzes, Quiz Results, AI).
5. Explore Endpoints: Use the organized requests in the imported collection to test different API functionalities. Remember to replace placeholder IDs (like {{quizMongoId}}, {{quizId}}, QUIZ_MONGO_ID_HERE) with actual IDs obtained from previous responses.

API Endpoints

All endpoints are prefixed with /api.

Authentication (/auth)

Method	URI	Action	Description	Middleware
POST	/auth/register	AuthController@register	Register a new user.	api
POST	/auth/login	AuthController@login	Log in a user, returns JWT.	api
POST	/auth/logout	AuthController@logout	Log out the authenticated user.	auth:api
POST	/auth/refresh	AuthController@refresh	Refresh the JWT token.	auth:api
GET	/auth/me	AuthController@me	Get authenticated user details.	auth:api

Quizzes

Method	URI	Action	Description	Middleware
POST	/create-quiz	QuizController@create	Create a new quiz.	auth:api
GET	/index-quiz	QuizController@index	List all quizzes (paginated).	auth:api
GET	/show-quiz/{mongo_id}	QuizController@show	Show details of a specific quiz (by Mongo ID).	auth:api
DELETE	/delete-quiz/{id}	QuizController@destroy	Delete a specific quiz (by PostgreSQL ID).	auth:api
GET	/index-quizzes	QuizController@index	Duplicate of /index-quiz?	auth:api
GET	/show-quizzes	QuizController@findByUser	List quizzes created by the auth user.	auth:api

Favorite Quizzes

Method	URI	Action	Description	Middleware
POST	/favorite-quiz-add	FavoriteQuizeController@create	Add a quiz to user's favorites.	auth:api
GET	/favorite-quiz-show	FavoriteQuizeController@index	List user's favorite quizzes.	auth:api
DELETE	/favorite-quiz-delete	FavoriteQuizeController@destroy	Remove a quiz from user's favorites.	auth:api

Quiz Results

Method	URI	Action	Description	Middleware
POST	/quiz-result-add	QuizResultController@create	Record results for a quiz.	auth:api
GET	/quiz-result-show	QuizResultController@index	List user's quiz results.	auth:api
DELETE	/quiz-result-delete	QuizResultController@destroy	Delete specific quiz results.	auth:api

AI Interaction (Public)

Method	URI	Action	Description	Middleware
GET	/ask-gemini	AiController@geminiResponse	Interact with Google Gemini.	api
GET	/ask-openai	AiController@openaiResponse	Interact with OpenAI.	api
GET	/ask-llama	AiController@llamaResponse	Interact with Llama (example).	api

Note: Some routes might be duplicates or require clarification (e.g., /index-quiz vs /index-quizzes). The middleware listed is based on the route group definitions.

Folder Structure (Key Directories)

├── app/                    # Core application code
│   ├── Console/            # Artisan commands
│   ├── Exceptions/         # Exception handling
│   ├── Facades/            # Custom Facades (e.g., AI Utils)
│   ├── Http/               # Controllers, Middleware, Requests
│   ├── Models/             # Eloquent models (User, Quiz, QuizData, etc.)
│   └── Providers/          # Service providers
├── bootstrap/              # App bootstrapping scripts
├── config/                 # Configuration files (app, database, jwt, ai keys, etc.)
├── database/               # Database migrations, factories, seeders
│   ├── factories/
│   ├── migrations/         # PostgreSQL schema migrations
│   └── seeders/
├── public/                 # Web server entry point (index.php), static assets
├── resources/              # Frontend assets (CSS, JS), views (less relevant for API)
├── routes/                 # Route definitions
│   ├── api.php             # API routes (most relevant)
│   └── web.php             # Web routes (if any)
├── storage/                # Compiled templates, logs, file uploads
├── tests/                  # Application tests (Unit, Feature)
├── vendor/                 # Composer dependencies
├── .env                    # Environment configuration (!!! DO NOT COMMIT !!!)
├── artisan                 # Artisan CLI tool
├── composer.json           # PHP dependencies
├── package.json            # Node.js dependencies (if any)
├── phpunit.xml             # PHPUnit configuration
├── postman-config.json     # Postman collection for API testing
└── README.md               # This file