### Run FastAPI Backend Locally

Source: https://github.com/muwahhidun/muwahhidaudio-mobile-app/blob/master/CLAUDE.md

Instructions for running the FastAPI backend locally using pip and uvicorn. This method requires installing dependencies from requirements.txt.

```bash
cd backend

# Local development
pip install -r requirements.txt
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

--------------------------------

### Install Flutter Mobile App Dependencies

Source: https://github.com/muwahhidun/muwahhidaudio-mobile-app/blob/master/CLAUDE.md

Bash command to fetch and install all the necessary dependencies for the Flutter mobile application. This is a standard step before running or building the app.

```bash
cd mobile_app

# Install dependencies
flutter pub get
```

--------------------------------

### Backend Build and Test Commands (Bash)

Source: https://github.com/muwahhidun/muwahhidaudio-mobile-app/blob/master/AGENTS.md

Commands for managing the backend services, including starting Docker containers, running database migrations, seeding data, and executing API tests. Dependencies: Docker, Python, asyncpg driver.

```bash
cd backend
docker-compose up -d                    # Start all services (PostgreSQL, Redis, API)
docker-compose exec api alembic revision --autogenerate -m "Description"  # Create migration
docker-compose exec api alembic upgrade head  # Apply migrations
docker-compose exec api python -m app.seed  # Seed test data
python test_api.py                       # Run API tests
python test_audio_streaming.py           # Test audio streaming with Range requests
```

--------------------------------

### FastAPI Backend CRUD Example - Get All Themes

Source: https://github.com/muwahhidun/muwahhidaudio-mobile-app/blob/master/CLAUDE.md

An asynchronous Python function using SQLAlchemy to retrieve all themes from the database, supporting pagination with skip and limit parameters. This demonstrates a typical backend list retrieval pattern.

```python
async def get_all_themes(db, search=None, include_inactive=False, skip=0, limit=100):
    query = select(Theme)
    # Apply filters
    query = query.offset(skip).limit(limit)
    return await db.scalars(query)
```

--------------------------------

### Run FastAPI Backend with Docker Compose

Source: https://github.com/muwahhidun/muwahhidaudio-mobile-app/blob/master/CLAUDE.md

Commands to start, view logs, and stop the FastAPI backend services using Docker Compose. This is the recommended method for running the backend.

```bash
cd backend

# Using Docker Compose (recommended)
docker-compose up -d              # Start all services (PostgreSQL, Redis, API)
docker-compose logs -f api        # View logs
docker-compose down               # Stop services
```

--------------------------------

### CMake Installation Rules for Application Bundle

Source: https://github.com/muwahhidun/muwahhidaudio-mobile-app/blob/master/mobile_app/windows/CMakeLists.txt

Configures the installation process for the application bundle, including setting the installation prefix and defining destinations for runtime components, data files, libraries, and native assets. It ensures that the application and its dependencies are correctly packaged for deployment.

```cmake
# === Installation ===
# Support files are copied into place next to the executable, so that it can
# run in place. This is done instead of making a separate bundle (as on Linux)
# so that building and running from within Visual Studio will work.
set(BUILD_BUNDLE_DIR "$<TARGET_FILE_DIR:${BINARY_NAME}>")
# Make the "install" step default, as it's required to run.
set(CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD 1)
if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
  set(CMAKE_INSTALL_PREFIX "${BUILD_BUNDLE_DIR}" CACHE PATH "..." FORCE)
endif()

set(INSTALL_BUNDLE_DATA_DIR "${CMAKE_INSTALL_PREFIX}/data")
set(INSTALL_BUNDLE_LIB_DIR "${CMAKE_INSTALL_PREFIX}")

install(TARGETS ${BINARY_NAME} RUNTIME DESTINATION "${CMAKE_INSTALL_PREFIX}"
  COMPONENT Runtime)

install(FILES "${FLUTTER_ICU_DATA_FILE}" DESTINATION "${INSTALL_BUNDLE_DATA_DIR}"
  COMPONENT Runtime)

install(FILES "${FLUTTER_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
  COMPONENT Runtime)

if(PLUGIN_BUNDLED_LIBRARIES)
  install(FILES "${PLUGIN_BUNDLED_LIBRARIES}"
    DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
    COMPONENT Runtime)
endif()

# Copy the native assets provided by the build.dart from all packages.
set(NATIVE_ASSETS_DIR "${PROJECT_BUILD_DIR}native_assets/windows/")
install(DIRECTORY "${NATIVE_ASSETS_DIR}"
   DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
   COMPONENT Runtime)

# Fully re-copy the assets directory on each build to avoid having stale files
# from a previous install.
set(FLUTTER_ASSET_DIR_NAME "flutter_assets")
install(CODE "
  file(REMOVE_RECURSE \"${INSTALL_BUNDLE_DATA_DIR}/${FLUTTER_ASSET_DIR_NAME}\")
  " COMPONENT Runtime)
install(DIRECTORY "${PROJECT_BUILD_DIR}/${FLUTTER_ASSET_DIR_NAME}"
  DESTINATION "${INSTALL_BUNDLE_DATA_DIR}" COMPONENT Runtime)

# Install the AOT library on non-Debug builds only.
install(FILES "${AOT_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_DATA_DIR}"
  CONFIGURATIONS Profile;Release
  COMPONENT Runtime)
```

--------------------------------

### GET /themes

Source: https://context7.com/muwahhidun/muwahhidaudio-mobile-app/llms.txt

Retrieves a list of themes with optional filtering and pagination. Admins can include inactive themes.

```APIDOC
## GET /themes

### Description
Retrieves a list of themes with optional filtering and pagination. Admins can include inactive themes.

### Method
GET

### Endpoint
/themes

### Parameters
#### Query Parameters
- **search** (string) - Optional - Keyword to search for within themes.
- **teacher_id** (integer) - Optional - Filter themes by a specific teacher ID.
- **has_series** (boolean) - Optional - If true, only themes that are part of a series are returned. Defaults to false.
- **include_inactive** (boolean) - Optional - If true, inactive themes are included in the results. Only accessible to admins. Defaults to false.
- **skip** (integer) - Optional - Number of themes to skip for pagination. Defaults to 0.
- **limit** (integer) - Optional - Maximum number of themes to return per page. Defaults to 100. Max is 1000.

### Response
#### Success Response (200)
- **items** (array) - A list of theme objects.
- **total** (integer) - The total number of themes matching the query.
- **skip** (integer) - The number of themes skipped.
- **limit** (integer) - The number of themes returned per page.

#### Response Example
{
  "items": [
    {
      "id": 1,
      "name": "Example Theme",
      "description": "This is an example theme.",
      "is_active": true,
      "series_count": 5,
      "content_count": 10
    }
  ],
  "total": 10,
  "skip": 0,
  "limit": 100
}
```

--------------------------------

### Docker Compose for Backend Setup (Bash)

Source: https://github.com/muwahhidun/muwahhidaudio-mobile-app/blob/master/CLAUDE.md

Shell commands using Docker Compose to manage the backend services. Includes bringing services down, removing volumes, and bringing them back up. Essential for resetting the database and ensuring a clean environment.

```bash
# Remove volumes to reset database
docker-compose down -v

# Recreate and start services in detached mode
docker-compose up -d
```

--------------------------------

### Apply Migrations Programmatically (Python)

Source: https://github.com/muwahhidun/muwahhidaudio-mobile-app/blob/master/CLAUDE.md

Python script to apply database migrations programmatically. Useful for automated deployment or setup processes. Assumes a database connection and migration setup is available.

```python
import os
import sys

# Add project root to sys.path
project_root = os.path.abspath(os.path.join(os.path.dirname(__main__), '..'))
sys.path.insert(0, project_root)

from backend.app.database import SessionLocal
from backend.app.alembic.versions import apply_migrations

def main():
    db = SessionLocal()
    try:
        apply_migrations(db)
        print("Migrations applied successfully.")
    except Exception as e:
        print(f"Error applying migrations: {e}")
    finally:
        db.close()

if __name__ == "__main__":
    main()
```

--------------------------------

### Mobile App Build and Test Commands (Flutter)

Source: https://github.com/muwahhidun/muwahhidaudio-mobile-app/blob/master/AGENTS.md

Commands for managing the Flutter mobile application, including installing dependencies, generating code, running the app on a device or emulator, and performing tests and static analysis. Dependencies: Flutter SDK.

```bash
cd mobile_app
flutter pub get                         # Install dependencies
flutter pub run build_runner build --delete-conflicting-outputs  # Generate code
flutter run                             # Run on device/emulator
flutter test                            # Run widget tests
flutter analyze                         # Run static analysis
```

--------------------------------

### Get Book Details API

Source: https://context7.com/muwahhidun/muwahhidaudio-mobile-app/llms.txt

Retrieves detailed information about a specific book, including its related theme and author information.

```bash
# Get book with relations
curl "http://localhost:8000/api/v1/books/1"

# Response
# {
#   "id": 1,
#   "name": "Три основы",
#   "description": "Основополагающий труд по акыде",
#   "theme_id": 1,
#   "author_id": 1,
#   "sort_order": 1,
#   "is_active": true,
#   "theme": {
#     "id": 1,
#     "name": "Акыда"
#   },
#   "author": {
#     "id": 1,
#     "name": "Мухаммад ибн Абд аль-Ваххаб"
#   }
# }
```

--------------------------------

### Dart Retrofit API Client Setup

Source: https://context7.com/muwahhidun/muwahhidaudio-mobile-app/llms.txt

Sets up a Retrofit API client using Dio for making HTTP requests. It defines various endpoints for user authentication, content retrieval (themes, series, lessons), test management, bookmarking, and feedback submission. This client requires generated code (`api_client.g.dart`) which can be produced using `flutter pub run build_runner build --delete-conflicting-outputs`.

```dart
// lib/data/api/api_client.dart
import 'package:retrofit/retrofit.dart';
import 'package:dio/dio.dart';
import '../models/user.dart';
import '../models/theme.dart';
import '../models/lesson.dart';
import '../models/paginated_response.dart';

part 'api_client.g.dart';

@RestApi(baseUrl: "http://localhost:8000/api/v1")
abstract class ApiClient {
  factory ApiClient(Dio dio, {String baseUrl}) = _ApiClient;

  // Authentication
  @POST("/auth/login")
  Future<AuthResponse> login(@Body() LoginRequest request);

  @POST("/auth/register")
  Future<AuthResponse> register(@Body() RegisterRequest request);

  @GET("/auth/me")
  Future<User> getCurrentUser();

  @PUT("/auth/me")
  Future<User> updateProfile(@Body() UserProfileUpdate profileData);

  // Themes
  @GET("/themes")
  Future<PaginatedResponse<AppThemeModel>> getThemes({
    @Query("search") String? search,
    @Query("teacher_id") int? teacherId,
    @Query("has_series") bool? hasSeries,
    @Query("include_inactive") bool? includeInactive,
    @Query("skip") int? skip,
    @Query("limit") int? limit,
  });

  @GET("/themes/{id}")
  Future<AppThemeModel> getTheme(@Path("id") int id);

  // Series
  @GET("/series")
  Future<PaginatedResponse<SeriesModel>> getSeries({
    @Query("search") String? search,
    @Query("teacher_id") int? teacherId,
    @Query("book_id") int? bookId,
    @Query("theme_id") int? themeId,
    @Query("year") int? year,
    @Query("is_completed") bool? isCompleted,
    @Query("include_inactive") bool? includeInactive,
    @Query("skip") int? skip,
    @Query("limit") int? limit,
  });

  @GET("/series/{id}")
  Future<SeriesModel> getSeriesById(@Path("id") int id);

  @GET("/series/{id}/lessons")
  Future<List<Lesson>> getSeriesLessons(@Path("id") int id);

  // Lessons
  @GET("/lessons")
  Future<PaginatedResponse<Lesson>> getLessons({
    @Query("search") String? search,
    @Query("series_id") int? seriesId,
    @Query("teacher_id") int? teacherId,
    @Query("book_id") int? bookId,
    @Query("theme_id") int? themeId,
    @Query("include_inactive") bool? includeInactive,
    @Query("skip") int? skip,
    @Query("limit") int? limit,
  });

  @GET("/lessons/{id}")
  Future<Lesson> getLesson(@Path("id") int id);

  // Tests
  @GET("/tests/series/{seriesId}/test")
  Future<Test> getSeriesTest(@Path("seriesId") int seriesId);

  @POST("/tests/{testId}/start")
  Future<TestAttempt> startTest(
    @Path("testId") int testId,
    @Body() Map<String, dynamic> body,
  );

  @POST("/tests/attempts/{attemptId}/submit")
  Future<TestAttempt> submitTestAttempt(
    @Path("attemptId") int attemptId,
    @Body() TestAttemptSubmit submission,
  );

  @GET("/tests/attempts/my")
  Future<List<TestAttempt>> getMyAttempts({
    @Query("series_id") int? seriesId,
    @Query("skip") int? skip,
    @Query("limit") int? limit,
  });

  @GET("/tests/series/{seriesId}/statistics")
  Future<SeriesStatistics> getSeriesStatistics(@Path("seriesId") int seriesId);

  // Bookmarks
  @GET("/bookmarks/series")
  Future<PaginatedResponse<SeriesWithBookmarks>> getBookmarkedSeries({
    @Query("skip") int? skip,
    @Query("limit") int? limit,
  });

  @POST("/bookmarks/toggle")
  Future<BookmarkToggleResponse> toggleBookmark(@Body() BookmarkCreateRequest request);

  @POST("/bookmarks")
  Future<Bookmark> createBookmark(@Body() BookmarkCreateRequest request);

  @PUT("/bookmarks/{id}")
  Future<Bookmark> updateBookmark(
    @Path("id") int id,
    @Body() BookmarkUpdateRequest request,
  );

  @DELETE("/bookmarks/{id}")
  Future<void> deleteBookmark(@Path("id") int id);

  // Feedback
  @POST("/feedbacks")
  Future<Feedback> createFeedback(@Body() FeedbackCreate feedback);

  @GET("/feedbacks/my")
  Future<PaginatedFeedbacksResponse> getMyFeedbacks({
    @Query("skip") int? skip,
    @Query("limit") int? limit,
  });

  @POST("/feedbacks/{id}/messages")
  Future<FeedbackMessage> createFeedbackMessage(
    @Path("id") int id,
    @Body() FeedbackMessageCreate message,
  );
}

// Generate code with: flutter pub run build_runner build --delete-conflicting-outputs

```

--------------------------------

### Get All Themes Endpoint (Python)

Source: https://context7.com/muwahhidun/muwahhidaudio-mobile-app/llms.txt

Retrieves a list of themes with support for searching, filtering by teacher, and pagination. Admins can also view inactive themes. Requires an active database session and user authentication.

```python
from fastapi import APIRouter, Depends, HTTPException, status, Query
from sqlalchemy.ext.asyncio import AsyncSession
from typing import Optional
from app.database import get_db
from app.api.auth import get_current_user
from app.models import User
from app.schemas.content import ThemeResponse, ThemeCreate, ThemeUpdate
from app.crud import theme as theme_crud

router = APIRouter(prefix="/themes", tags=["Themes"])

@router.get("")
async def get_themes(
    search: Optional[str] = Query(None),
    teacher_id: Optional[int] = Query(None),
    has_series: bool = Query(False),
    include_inactive: bool = Query(False),
    skip: int = Query(0, ge=0),
    limit: int = Query(100, ge=1, le=1000),
    db: AsyncSession = Depends(get_db),
    current_user: Optional[User] = Depends(get_current_user)
):
    """Get all themes with pagination."""
    # Only admins can see inactive themes
    can_see_inactive = include_inactive and current_user and current_user.role.level >= 2

    # Get total count
    total = await theme_crud.count_themes(
        db,
        search=search,
        teacher_id=teacher_id,
        has_series=has_series,
        include_inactive=can_see_inactive
    )

    # Get themes
    themes = await theme_crud.get_all_themes(
        db,
        search=search,
        teacher_id=teacher_id,
        has_series=has_series,
        include_inactive=can_see_inactive,
        skip=skip,
        limit=limit
    )

    return {
        "items": themes,
        "total": total,
        "skip": skip,
        "limit": limit
    }
```

--------------------------------

### List Themes with Pagination - Bash

Source: https://context7.com/muwahhidun/muwahhidaudio-mobile-app/llms.txt

Retrieves a paginated list of active themes by sending a GET request to the /api/v1/themes endpoint. Supports 'skip' and 'limit' query parameters for pagination. Returns a list of theme items along with total count, skip, and limit information.

```bash
# Get all active themes
curl -X GET "http://localhost:8000/api/v1/themes?skip=0&limit=10"
```

--------------------------------

### Get Teacher's Series API

Source: https://context7.com/muwahhidun/muwahhidaudio-mobile-app/llms.txt

Retrieves a non-paginated list of all lesson series taught by a specific teacher, identified by their ID.

```bash
# Get all lesson series taught by this teacher
curl "http://localhost:8000/api/v1/teachers/1/series"

# Response (List - not paginated)
# [
#   {
#     "id": 1,
#     "name": "Три основы - Фаида 1",
#     "year": 2025,
#     "description": "Разъяснение трех основ",
#     "teacher_id": 1,
#     "book_id": 1,
#     "theme_id": 1,
#     "is_completed": false,
#     "order": 1,
#     "is_active": true
#   }
# ]
```

--------------------------------

### Get User's Feedbacks - API

Source: https://context7.com/muwahhidun/muwahhidaudio-mobile-app/llms.txt

Retrieves a list of all feedback entries for the currently authenticated user, with pagination support. Requires an authorization token. Useful for users to track their submitted requests.

```bash
# Get all feedbacks for current user
curl -X GET "http://localhost:8000/api/v1/feedbacks/my?skip=0&limit=10" \
  -H "Authorization: Bearer USER_TOKEN"
```

--------------------------------

### FastAPI Backend CRUD Example - Count Themes

Source: https://github.com/muwahhidun/muwahhidaudio-mobile-app/blob/master/CLAUDE.md

An asynchronous Python function using SQLAlchemy to count themes in the database, with optional search and filtering capabilities. This demonstrates a typical backend count pattern.

```python
async def count_themes(db, search=None, include_inactive=False) -> int:
    query = select(func.count(Theme.id))
    # Apply filters
    return await db.scalar(query)
```

--------------------------------

### Get Dashboard Statistics - API

Source: https://context7.com/muwahhidun/muwahhidaudio-mobile-app/llms.txt

Retrieves comprehensive administrative statistics for the application, including counts for themes, books, authors, teachers, series, lessons, and users. Requires an administrator token. Provides insights into platform usage and content.

```bash
# Get comprehensive statistics (admin only)
curl -X GET "http://localhost:8000/api/v1/statistics" \
  -H "Authorization: Bearer ADMIN_TOKEN"
```

--------------------------------

### Admin Screen Pagination Implementation

Source: https://github.com/muwahhidun/muwahhidaudio-mobile-app/blob/master/CLAUDE.md

Example implementation of pagination logic for admin management screens. It demonstrates loading paginated data using Dio, managing state for current page, total items, and items per page, and updating the UI.

```dart
int _currentPage = 0;
int _totalItems = 0;
final int _itemsPerPage = 10;

Future<void> _loadItems({bool resetPage = false}) async {
  final dio = DioProvider.getDio();
  final response = await dio.get('/endpoint', queryParameters: {
    'include_inactive': true,
    'skip': _currentPage * _itemsPerPage,
    'limit': _itemsPerPage,
  });
  final data = response.data as Map<String, dynamic>;
  setState(() {
    _items = (data['items'] as List).map((e) => Model.fromJson(e)).toList();
    _totalItems = data['total'] as int;
  });
}
```

--------------------------------

### Get All Themes with Pagination and Filters - SQLAlchemy

Source: https://context7.com/muwahhidun/muwahhidaudio-mobile-app/llms.txt

Retrieves a list of themes, applying filters for search, teacher ID, series association, and active status, followed by pagination using skip and limit parameters. It ensures results are ordered by sort order and name. This function is used for fetching paginated lists of themes.

```python
async def get_all_themes(
    db: AsyncSession,
    search: Optional[str] = None,
    teacher_id: Optional[int] = None,
    has_series: bool = False,
    include_inactive: bool = False,
    skip: int = 0,
    limit: int = 100
) -> List[Theme]:
    """Get themes with pagination."""
    query = select(Theme).distinct()

    # Apply same filters as count function
    if teacher_id is not None or has_series:
        query = query.join(LessonSeries, LessonSeries.theme_id == Theme.id)
        query = query.where(LessonSeries.is_active == True)

        if teacher_id is not None:
            query = query.where(LessonSeries.teacher_id == teacher_id)

    if not include_inactive:
        query = query.where(Theme.is_active == True)

    if search:
        search_term = f"%{search}%"
        query = query.where(
            or_(
                Theme.name.ilike(search_term),
                Theme.description.ilike(search_term)
            )
        )

    # Order and paginate
    query = query.order_by(Theme.sort_order, Theme.name).offset(skip).limit(limit)
    result = await db.execute(query)
    return list(result.scalars().all())
```

--------------------------------

### Create Theme API (Admin Only)

Source: https://context7.com/muwahhidun/muwahhidaudio-mobile-app/llms.txt

Allows administrators to create a new theme by providing its name, description, and sort order in a JSON payload. Requires administrator authentication.

```bash
# Create new theme
curl -X POST "http://localhost:8000/api/v1/themes" \
  -H "Authorization: Bearer ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ 
    "name": "Сира",
    "description": "Жизнеописание Пророка",
    "sort_order": 3
  }'

# Response: Created theme object
```

--------------------------------

### POST /themes

Source: https://context7.com/muwahhidun/muwahhidaudio-mobile-app/llms.txt

Creates a new theme. This endpoint is restricted to administrators.

```APIDOC
## POST /themes

### Description
Creates a new theme. This endpoint is restricted to administrators.

### Method
POST

### Endpoint
/themes

### Parameters
#### Request Body
- **name** (string) - Required - The name of the new theme.
- **description** (string) - Optional - A description for the new theme.
- **is_active** (boolean) - Optional - Whether the theme should be active. Defaults to true.

### Request Example
```json
{
  "name": "New Awesome Theme",
  "description": "This is a brand new theme.",
  "is_active": true
}
```

### Response
#### Success Response (201)
- **id** (integer) - The unique identifier of the newly created theme.
- **name** (string) - The name of the theme.
- **description** (string) - The description of the theme.
- **is_active** (boolean) - Indicates if the theme is active.

#### Response Example
```json
{
  "id": 2,
  "name": "New Awesome Theme",
  "description": "This is a brand new theme.",
  "is_active": true
}
```
```

--------------------------------

### User Registration API

Source: https://context7.com/muwahhidun/muwahhidaudio-mobile-app/llms.txt

Allows new users to register an account. Returns tokens upon successful registration, but requires email verification before login.

```APIDOC
## POST /api/v1/auth/register

### Description
Registers a new user with the provided credentials. An email verification link will be sent to the user's email address. Tokens are returned, but the user cannot log in until their email is verified.

### Method
POST

### Endpoint
/api/v1/auth/register

### Parameters
#### Request Body
- **email** (string) - Required - The user's email address.
- **username** (string) - Required - The user's desired username.
- **password** (string) - Required - The user's password.
- **first_name** (string) - Required - The user's first name.
- **last_name** (string) - Required - The user's last name.

### Request Example
```json
{
  "email": "user@example.com",
  "username": "newuser123",
  "password": "SecurePass123",
  "first_name": "Ahmed",
  "last_name": "Ali"
}
```

### Response
#### Success Response (201 Created)
- **access_token** (string) - The JWT access token.
- **refresh_token** (string) - The JWT refresh token.
- **token_type** (string) - The type of token (e.g., "bearer").
- **user** (object) - The registered user object.
  - **id** (integer) - The user's unique identifier.
  - **email** (string) - The user's email address.
  - **username** (string) - The user's username.
  - **first_name** (string) - The user's first name.
  - **last_name** (string) - The user's last name.
  - **email_verified** (boolean) - Indicates if the user's email has been verified.
  - **is_active** (boolean) - Indicates if the user account is active.
  - **role** (object) - The user's assigned role.
    - **id** (integer) - The role's unique identifier.
    - **name** (string) - The name of the role (e.g., "User").
    - **level** (integer) - The role's hierarchical level.

#### Response Example
```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "user": {
    "id": 1,
    "email": "user@example.com",
    "username": "newuser123",
    "first_name": "Ahmed",
    "last_name": "Ali",
    "email_verified": false,
    "is_active": true,
    "role": {
      "id": 1,
      "name": "User",
      "level": 0
    }
  }
}
```
```

--------------------------------

### Get Current User Profile - Bash

Source: https://context7.com/muwahhidun/muwahhidaudio-mobile-app/llms.txt

Retrieves the profile information of the currently authenticated user by sending a GET request to the /api/v1/auth/me endpoint with a Bearer token. Returns detailed user information including ID, email, username, and role.

```bash
# Get authenticated user profile
curl -X GET "http://localhost:8000/api/v1/auth/me" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

--------------------------------

### Content - Get Themes

Source: https://github.com/muwahhidun/muwahhidaudio-mobile-app/blob/master/CLAUDE.md

Retrieves a list of content themes available in the application. Supports pagination.

```APIDOC
## GET /api/themes

### Description
Retrieves a list of available themes for Islamic audio content. Supports pagination.

### Method
GET

### Endpoint
/api/themes

### Query Parameters
- **skip** (integer) - Optional - The number of records to skip (offset). Defaults to 0.
- **limit** (integer) - Optional - The maximum number of records to return. Defaults to 100.
- **search** (string) - Optional - Filter themes by name.

### Response
#### Success Response (200)
- **items** (array) - A list of theme objects.
  - **id** (integer) - The unique identifier for the theme.
  - **name** (string) - The name of the theme.
  - **description** (string) - A brief description of the theme.
- **total** (integer) - The total number of themes available.
- **skip** (integer) - The number of records skipped.
- **limit** (integer) - The limit applied to the returned items.

#### Response Example
```json
{
  "items": [
    {
      "id": 1,
      "name": "Акыда",
      "description": "Beliefs and creed"
    },
    {
      "id": 2,
      "name": "Сира",
      "description": "Biography of Prophet Muhammad (peace be upon him)"
    }
  ],
  "total": 2,
  "skip": 0,
  "limit": 100
}
```
```

--------------------------------

### Get Series Lessons

Source: https://context7.com/muwahhidun/muwahhidaudio-mobile-app/llms.txt

Retrieves all lessons belonging to a specific series, ordered by their lesson number.

```APIDOC
## GET /api/v1/series/{series_id}/lessons

### Description
Retrieves a list of all lessons associated with a particular series. The lessons are returned in the order of their `lesson_number`.

### Method
GET

### Endpoint
`/api/v1/series/{series_id}/lessons`

### Parameters
#### Path Parameters
- **series_id** (integer) - Required - The unique identifier of the series whose lessons are to be retrieved.

### Request Example
```bash
curl "http://localhost:8000/api/v1/series/1/lessons"
```

### Response
#### Success Response (200)
Returns a list of lesson objects.
- **id** (integer) - Unique identifier of the lesson.
- **title** (string) - The title of the lesson.
- **description** (string) - A brief description of the lesson content.
- **lesson_number** (integer) - The sequence number of the lesson within the series.
- **duration_seconds** (integer) - The duration of the lesson in seconds.
- **audio_path** (string) - The relative path to the processed audio file.
- **waveform_data** (array) - Sample data representing the audio waveform.
- **tags** (string) - Comma-separated tags associated with the lesson.
- **series_id** (integer) - The ID of the series this lesson belongs to.
- **book_id** (integer) - The ID of the book associated with this lesson.
- **teacher_id** (integer) - The ID of the teacher associated with this lesson.
- **theme_id** (integer) - The ID of the theme associated with this lesson.
- **is_active** (boolean) - Indicates if the lesson is active.

#### Response Example
```json
[
  {
    "id": 1,
    "title": "Урок 1 - Введение",
    "description": "Вступительный урок",
    "lesson_number": 1,
    "duration_seconds": 3600,
    "audio_path": "processed/lesson_1.mp3",
    "waveform_data": [0.5, 0.7, 0.3, ...],
    "tags": "введение,основы",
    "series_id": 1,
    "book_id": 1,
    "teacher_id": 1,
    "theme_id": 1,
    "is_active": true
  }
]
```
```

--------------------------------

### Get Current User Profile API

Source: https://context7.com/muwahhidun/muwahhidaudio-mobile-app/llms.txt

Retrieves the profile information for the currently authenticated user.

```APIDOC
## GET /api/v1/auth/me

### Description
Retrieves the profile details of the user associated with the provided authentication token.

### Method
GET

### Endpoint
/api/v1/auth/me

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token for authentication (e.g., `Bearer YOUR_ACCESS_TOKEN`).

### Response
#### Success Response
- **id** (integer) - The user's unique identifier.
- **email** (string) - The user's email address.
- **username** (string) - The user's username.
- **first_name** (string) - The user's first name.
- **last_name** (string) - The user's last name.
- **email_verified** (boolean) - Indicates if the user's email has been verified.
- **is_active** (boolean) - Indicates if the user account is active.
- **role** (object) - The user's assigned role.
  - **id** (integer) - The role's unique identifier.
  - **name** (string) - The name of the role (e.g., "User").
  - **level** (integer) - The role's hierarchical level.

#### Response Example
```json
{
  "id": 1,
  "email": "user@example.com",
  "username": "newuser123",
  "first_name": "Ahmed",
  "last_name": "Ali",
  "email_verified": true,
  "is_active": true,
  "role": {
    "id": 1,
    "name": "User",
    "level": 0
  }
}
```
```

--------------------------------

### Register User - Bash

Source: https://context7.com/muwahhidun/muwahhidaudio-mobile-app/llms.txt

Registers a new user by sending a POST request to the /api/v1/auth/register endpoint. It requires user details like email, username, password, first name, and last name. The response includes access and refresh tokens, but the user must verify their email before logging in.

```bash
# Register new user (returns tokens but requires email verification before login)
curl -X POST "http://localhost:8000/api/v1/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "username": "newuser123",
    "password": "SecurePass123",
    "first_name": "Ahmed",
    "last_name": "Ali"
  }'
```

--------------------------------

### GET /themes/{theme_id}

Source: https://context7.com/muwahhidun/muwahhidaudio-mobile-app/llms.txt

Retrieves a specific theme by its ID, including counts of related series and content.

```APIDOC
## GET /themes/{theme_id}

### Description
Retrieves a specific theme by its ID, including counts of related series and content.

### Method
GET

### Endpoint
/themes/{theme_id}

### Parameters
#### Path Parameters
- **theme_id** (integer) - Required - The unique identifier of the theme to retrieve.

### Response
#### Success Response (200)
- **id** (integer) - The unique identifier of the theme.
- **name** (string) - The name of the theme.
- **description** (string) - The description of the theme.
- **is_active** (boolean) - Indicates if the theme is active.
- **series_count** (integer) - The number of series associated with this theme.
- **content_count** (integer) - The number of content items associated with this theme.

#### Response Example
{
  "id": 1,
  "name": "Example Theme",
  "description": "This is an example theme.",
  "is_active": true,
  "series_count": 5,
  "content_count": 10
}
```

--------------------------------

### List Lessons

Source: https://context7.com/muwahhidun/muwahhidaudio-mobile-app/llms.txt

Retrieves a paginated list of all lessons. Supports filtering by series, teacher, book, theme, and searching by keywords.

```APIDOC
## GET /api/v1/lessons

### Description
Retrieves a paginated list of lessons. Allows filtering by various criteria such as series, teacher, book, and theme, as well as searching by keywords in the title or description.

### Method
GET

### Endpoint
`/api/v1/lessons`

### Parameters
#### Query Parameters
- **skip** (integer) - Optional - Number of records to skip for pagination. Defaults to 0.
- **limit** (integer) - Optional - Maximum number of records to return. Defaults to 20.
- **series_id** (integer) - Optional - Filter lessons by a specific series ID.
- **teacher_id** (integer) - Optional - Filter lessons by a specific teacher ID.
- **book_id** (integer) - Optional - Filter lessons by a specific book ID.
- **theme_id** (integer) - Optional - Filter lessons by a specific theme ID.
- **search** (string) - Optional - Search term to filter lessons by title, description, or tags.

### Request Example
```bash
# Get all lessons with pagination
curl "http://localhost:8000/api/v1/lessons?skip=0&limit=20"

# Filter by series
curl "http://localhost:8000/api/v1/lessons?series_id=1&skip=0&limit=20"

# Search by title, description, tags
curl "http://localhost:8000/api/v1/lessons?search=введение&skip=0&limit=20"
```

### Response
#### Success Response (200)
- **items** (array) - A list of lesson objects.
  - **id** (integer) - Unique identifier of the lesson.
  - **title** (string) - The title of the lesson.
  - **description** (string) - A brief description of the lesson content.
  - **lesson_number** (integer) - The sequence number of the lesson.
  - **duration_seconds** (integer) - Duration of the lesson in seconds.
  - **audio_path** (string) - Path to the processed audio file.
  - **original_audio_path** (string) - Path to the original audio file.
  - **waveform_data** (array) - Waveform data points.
  - **tags** (string) - Comma-separated tags.
  - **series_id** (integer) - Series ID.
  - **book_id** (integer) - Book ID.
  - **teacher_id** (integer) - Teacher ID.
  - **theme_id** (integer) - Theme ID.
  - **is_active** (boolean) - Whether the lesson is active.
  - **display_title** (string) - Formatted display title.
  - **formatted_duration** (string) - Formatted duration (HH:MM:SS).
  - **audio_url** (string) - URL to stream the audio.
  - **tags_list** (array) - List of tags.
- **total** (integer) - Total number of lessons available matching the query.
- **skip** (integer) - The number of records skipped.
- **limit** (integer) - The number of records returned.

#### Response Example
```json
{
  "items": [
    {
      "id": 1,
      "title": "Урок 1 - Введение",
      "description": "Вступительный урок",
      "lesson_number": 1,
      "duration_seconds": 3600,
      "audio_path": "processed/lesson_1.mp3",
      "original_audio_path": "original/lesson_1_orig.mp3",
      "waveform_data": [0.5, 0.7, ...],
      "tags": "введение,основы",
      "series_id": 1,
      "book_id": 1,
      "teacher_id": 1,
      "theme_id": 1,
      "is_active": true,
      "display_title": "Урок 1: Введение",
      "formatted_duration": "1:00:00",
      "audio_url": "/api/v1/lessons/1/audio",
      "tags_list": ["введение", "основы"]
    }
  ],
  "total": 100,
  "skip": 0,
  "limit": 20
}
```
```

--------------------------------

### Get Test for Series (User)

Source: https://context7.com/muwahhidun/muwahhidaudio-mobile-app/llms.txt

Retrieves a test associated with a specific series for a user. This test will not include correct answers.

```APIDOC
## GET /api/v1/tests/series/{series_id}/test

### Description
Fetches a test designed for a specific series. This endpoint is intended for end-users and provides the test questions without revealing the correct answers.

### Method
GET

### Endpoint
`/api/v1/tests/series/{series_id}/test`

### Parameters
#### Path Parameters
- **series_id** (integer) - Required - The unique identifier of the series for which to retrieve the test.

#### Headers
- **Authorization**: `Bearer USER_TOKEN` - Required - Authentication token for the user.

### Request Example
```bash
curl -X GET "http://localhost:8000/api/v1/tests/series/1/test" \
  -H "Authorization: Bearer USER_TOKEN"
```

### Response
#### Success Response (200)
Returns the test structure, typically including questions and their options, but excluding correct answer keys.

#### Response Example
(Example response structure would typically be provided here, detailing the test questions and options.)
```

--------------------------------

### List and Filter Books API

Source: https://context7.com/muwahhidun/muwahhidaudio-mobile-app/llms.txt

Provides functionality to list all books with pagination and filtering options. Filters include theme ID, author ID, search by name/description, and availability of lesson series.

```bash
# Get all books with pagination
curl "http://localhost:8000/api/v1/books?skip=0&limit=10"

# Response (Paginated)
# {
#   "items": [
#     {
#       "id": 1,
#       "name": "Три основы",
#       "description": "Основополагающий труд по акыде",
#       "theme_id": 1,
#       "author_id": 1,
#       "sort_order": 1,
#       "is_active": true
#     }
#   ],
#   "total": 25,
#   "skip": 0,
#   "limit": 10
# }

# Filter by theme
curl "http://localhost:8000/api/v1/books?theme_id=1&skip=0&limit=10"

# Filter by author
curl "http://localhost:8000/api/v1/books?author_id=2&skip=0&limit=10"

# Search by name/description
curl "http://localhost:8000/api/v1/books?search=Три&skip=0&limit=10"

# Only books with lesson series
curl "http://localhost:8000/api/v1/books?has_series=true&skip=0&limit=10"
```

--------------------------------

### Search and Filter Themes API

Source: https://context7.com/muwahhidun/muwahhidaudio-mobile-app/llms.txt

Allows searching themes by name or description, and filtering by teacher, lesson series availability, or including inactive themes. Requires authentication for admin-only operations.

```bash
# Search themes by name or description
curl "http://localhost:8000/api/v1/themes?search=Акыда&skip=0&limit=10"

# Filter by teacher (themes taught by this teacher)
curl "http://localhost:8000/api/v1/themes?teacher_id=5&skip=0&limit=10"

# Only themes with lesson series
curl "http://localhost:8000/api/v1/themes?has_series=true&skip=0&limit=10"

# Admin: Include inactive themes
curl -H "Authorization: Bearer ADMIN_TOKEN" \
  "http://localhost:8000/api/v1/themes?include_inactive=true&skip=0&limit=10"
```

--------------------------------

### Themes API

Source: https://context7.com/muwahhidun/muwahhidaudio-mobile-app/llms.txt

Endpoints for retrieving and fetching theme information, including listing themes with filtering and getting a specific theme by ID.

```APIDOC
## GET /themes

### Description
Retrieves a paginated list of themes. Supports filtering by search query, teacher ID, series status, and inclusion of inactive themes.

### Method
GET

### Endpoint
/themes

### Parameters
#### Query Parameters
- **search** (string) - Optional - Search query for themes.
- **teacher_id** (integer) - Optional - Filter by teacher ID.
- **has_series** (boolean) - Optional - Filter themes that have series.
- **include_inactive** (boolean) - Optional - Include inactive themes in the results.
- **skip** (integer) - Optional - Number of themes to skip.
- **limit** (integer) - Optional - Maximum number of themes to return.

### Response
#### Success Response (200)
- **data** (array of AppThemeModel) - A paginated list of themes.
- **total** (integer) - Total number of themes available.

#### Response Example
```json
{
  "data": [
    {
      "id": 1,
      "name": "Introduction to Quran",
      "description": "Learn the basics of the Quran."
    }
  ],
  "total": 10
}
```

## GET /themes/{id}

### Description
Retrieves a specific theme by its ID.

### Method
GET

### Endpoint
/themes/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the theme to retrieve.

### Response
#### Success Response (200)
- **theme** (AppThemeModel) - The details of the requested theme.

#### Response Example
```json
{
  "id": 1,
  "name": "Introduction to Quran",
  "description": "Learn the basics of the Quran."
}
```
```

--------------------------------

### List Lesson Series API

Source: https://context7.com/muwahhidun/muwahhidaudio-mobile-app/llms.txt

Fetches a list of lesson series with pagination. Supports filtering by teacher, book, theme, year, and completion status.

```bash
# Get all series with pagination
curl "http://localhost:8000/api/v1/series?skip=0&limit=10"

# Response
# {
#   "items": [
#     {
#       "id": 1,
#       "name": "Три основы - Фаида 1",
#       "year": 2025,
#       "description": "Разъяснение трех основ",
#       "teacher_id": 1,
#       "book_id": 1,
#       "theme_id": 1,
#       "is_completed": false,
#       "order": 1,
#       "is_active": true,
#       "display_name": "2025 - Три основы - Фаида 1"
#     }
#   ],
#   "total": 50,
#   "skip": 0,
#   "limit": 10
# }

# Filter by teacher, book, theme
curl "http://localhost:8000/api/v1/series?teacher_id=1&book_id=1&theme_id=1&skip=0&limit=10"

# Filter by year
curl "http://localhost:8000/api/v1/series?year=2025&skip=0&limit=10"

# Filter by completion status
curl "http://localhost:8000/api/v1/series?is_completed=true&skip=0&limit=10"
```