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:
   ```bash
   git clone <repository-url>
   cd userauthenticationservice-mt157i
   ```

2. Create a virtual environment:
   ```bash
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   ```

3. Install dependencies:
   ```bash
   pip install -r requirements.txt
   ```

4. Set up environment variables (optional):
   ```bash
   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:

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

# Run migrations
alembic upgrade head
```

### Running the Application

Run the development server:

```bash
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.