userauthenticationservice-mt157i/README.md

Kids Learning Gamification API

A FastAPI-based backend API for a gamified learning platform for kids. The API provides endpoints for managing learning content, tracking user progress, and implementing gamification features like achievements and points.

Features

• User Authentication: Secure JWT-based authentication with registration and login
• Content Management: Manage learning subjects, lessons, quizzes, questions, and answers
• Progress Tracking: Track user progress through lessons and quizzes
• Gamification: Award points for completed lessons and quizzes, implement achievements
• Health Checks: Comprehensive health check endpoint for monitoring
• Documentation: Interactive API documentation via Swagger UI and ReDoc

Technology Stack

• Python: 3.9+
• FastAPI: High-performance web framework
• SQLite: Lightweight database
• SQLAlchemy: SQL toolkit and ORM
• Alembic: Database migration tool
• Pydantic: Data validation and settings management
• JWT: Token-based authentication
• Ruff: Linting tool

Setup and Installation

Prerequisites

• Python 3.9 or higher
• pip package manager

Installation

1. Clone the repository:

   git clone <repository-url>
   cd userauthenticationservice-mt157i
   

2. Create a virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. Set up environment variables (optional):

   export SECRET_KEY="your-secret-key"  # For production, use a secure random key
   export ENVIRONMENT="development"      # Options: development, production
   

Database Setup

The application uses SQLite by default with a database file stored at /app/storage/db/db.sqlite. The directory will be created automatically if it doesn't exist.

To initialize the database with the required tables:

# Initialize Alembic (if you're starting a new project)
alembic init alembic

# Run migrations
alembic upgrade head

Running the Application

Run the development server:

uvicorn main:app --reload

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

API Documentation

Once the application is running, you can access the auto-generated API documentation:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc
• OpenAPI Schema: http://localhost:8000/openapi.json

API Endpoints

The API is organized into several modules:

Authentication

• POST /api/v1/auth/register: Register a new user
• POST /api/v1/auth/login: Login and get access token
• POST /api/v1/auth/test-token: Test authentication token

Users

• GET /api/v1/users/me: Get current user information
• PUT /api/v1/users/me: Update current user information
• GET /api/v1/users/{user_id}: Get user by ID (superusers only)
• PUT /api/v1/users/{user_id}: Update user by ID (superusers only)

Content Management

• Subjects

  • GET /api/v1/content/subjects: List all subjects
  • POST /api/v1/content/subjects: Create a new subject
  • GET /api/v1/content/subjects/{subject_id}: Get a subject by ID
  • PUT /api/v1/content/subjects/{subject_id}: Update a subject
  • DELETE /api/v1/content/subjects/{subject_id}: Delete a subject

• Lessons

  • GET /api/v1/content/subjects/{subject_id}/lessons: List lessons for a subject
  • POST /api/v1/content/lessons: Create a new lesson
  • GET /api/v1/content/lessons/{lesson_id}: Get a lesson by ID
  • PUT /api/v1/content/lessons/{lesson_id}: Update a lesson
  • DELETE /api/v1/content/lessons/{lesson_id}: Delete a lesson

• Quizzes

  • GET /api/v1/content/lessons/{lesson_id}/quizzes: List quizzes for a lesson
  • POST /api/v1/content/quizzes: Create a new quiz
  • GET /api/v1/content/quizzes/{quiz_id}: Get a quiz by ID
  • PUT /api/v1/content/quizzes/{quiz_id}: Update a quiz
  • DELETE /api/v1/content/quizzes/{quiz_id}: Delete a quiz

• Questions and Answers

  • GET /api/v1/content/quizzes/{quiz_id}/questions: List questions for a quiz
  • POST /api/v1/content/questions: Create a new question with answers
  • GET /api/v1/content/questions/{question_id}: Get a question by ID
  • PUT /api/v1/content/questions/{question_id}: Update a question
  • DELETE /api/v1/content/questions/{question_id}: Delete a question

Progress Tracking

• GET /api/v1/progress/user/{user_id}/stats: Get a user's progress statistics
• GET /api/v1/progress/user/{user_id}/lessons: Get a user's progress for all lessons
• GET /api/v1/progress/user/{user_id}/lessons/{lesson_id}: Get a user's progress for a specific lesson
• POST /api/v1/progress/user/{user_id}/lessons/{lesson_id}/progress: Update a user's progress for a lesson
• POST /api/v1/progress/user/{user_id}/lessons/{lesson_id}/complete: Mark a lesson as completed
• POST /api/v1/progress/user/{user_id}/questions/{question_id}/answer: Submit an answer to a question
• GET /api/v1/progress/user/{user_id}/questions/{question_id}/answers: Get a user's answers for a question
• GET /api/v1/progress/user/{user_id}/quizzes/{quiz_id}/results: Get a user's quiz results

Achievements

• GET /api/v1/achievements: List all achievements
• POST /api/v1/achievements: Create a new achievement (superusers only)
• GET /api/v1/achievements/{achievement_id}: Get an achievement by ID
• PUT /api/v1/achievements/{achievement_id}: Update an achievement (superusers only)
• DELETE /api/v1/achievements/{achievement_id}: Delete an achievement (superusers only)
• GET /api/v1/achievements/user/{user_id}: Get a user's achievements
• POST /api/v1/achievements/user/{user_id}/award/{achievement_id}: Award an achievement to a user (superusers only)
• POST /api/v1/achievements/user/{user_id}/check: Check and award achievements based on user's progress

Health Check

• GET /health: Health check endpoint that returns the status of the service and its dependencies

Environment Variables

The following environment variables can be configured:

Variable	Description	Default
SECRET_KEY	Secret key for JWT token generation	Auto-generated
ENVIRONMENT	Environment (development, production)	development
ACCESS_TOKEN_EXPIRE_MINUTES	Expiration time for access tokens	11520 (8 days)

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Commit your changes: git commit -am 'Add new feature'
4. Push to the branch: git push origin feature/my-feature
5. Submit a pull request

License

This project is licensed under the MIT License.