openapi.yaml

openapi: 3.0.3
info:
  title: DreamTeam Education Platform API
  description: Comprehensive API for the DreamTeam Education Platform - managing users, courses, groups, regions, and educational analytics
  version: 1.0.0
  contact:
    name: DreamTeam Education
    email: support@dreamteameducation.com

servers:
  - url: http://localhost:3000
    description: Local development server
  - url: https://api.dreamteameducation.com
    description: Production server

security:
  - bearerAuth: []

paths:
  # Health Check
  /api/health:
    get:
      summary: Check API health status
      description: |
        Performs a health check on the API and its connected services (Database, External Integrations).
        Returns the current operational status and timestamp.
        Use this endpoint for load balancers and monitoring systems to verify system availability.
      tags:
        - Health
      responses:
        '200':
          description: System is fully operational
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "healthy"
                    description: "Current status of the API (healthy, degraded, unhealthy)"
                  timestamp:
                    type: string
                    format: date-time
                    description: "Server timestamp of the health check"
                  api:
                    type: string
                    example: "running"
                    description: "API service status"

  # Authentication Routes
  /api/auth/login:
    post:
      summary: Authenticate user
      description: |
        Authenticate a user using their email and password credentials.
        On success, returns a JSON Web Token (JWT) validity 24h and user profile information.
        The JWT must be included in the `Authorization: Bearer <token>` header for all protected endpoints.
      tags:
        - Authentication
      requestBody:
        description: User credentials
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - password
              properties:
                email:
                  type: string
                  format: email
                  description: "Registered email address"
                  example: "student@test.com"
                password:
                  type: string
                  minLength: 6
                  description: "User password"
                  example: "Test1234"
      responses:
        '200':
          description: Authentication successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          description: Authentication Failed (Invalid email or password)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/auth/logout:
    post:
      summary: Logout user
      description: |
        Invalidate the current user's session.
        This operation might blacklist the current token or simply inform the client to discard it.
        Requires a valid authentication token.
      tags:
        - Authentication
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Successfully logged out
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Logged out successfully"
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/auth/me:
    get:
      summary: Get current profile
      description: |
        Retrieve the full profile information of the currently authenticated user.
        Includes role, permissions, and group/institution associations.
        Useful for client-side state initialization.
      tags:
        - Authentication
      security:
        - bearerAuth: []
      responses:
        '200':
          description: User profile retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/auth/verify:
    get:
      summary: Verify token validity
      description: |
        Check if the provided authentication token is still valid and active.
        This is a lightweight endpoint used to validate sessions without fetching full user data.
      tags:
        - Authentication
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Token is valid
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  valid:
                    type: boolean
                    example: true
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/auth/refresh:
    post:
      summary: Refresh access token
      description: |
        Refresh the access token using a valid refresh token.
        Returns new access and refresh tokens.
        Implements single-session-per-user policy - new tokens invalidate previous ones.
      tags:
        - Authentication
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Tokens refreshed successfully
          headers:
            X-New-Access-Token:
              description: New access token
              schema:
                type: string
            X-New-Refresh-Token:
              description: New refresh token
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/auth/register:
    post:
      summary: Register new user (Admin)
      description: |
        Create a new user account in the system.
        This endpoint is restricted to administrators.
        The new user will be created with `isActive: true` by default.
      tags:
        - Authentication
      security:
        - bearerAuth: []
      requestBody:
        description: New user details
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '201':
          description: User successfully registered
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/User'
                  message:
                    type: string
                    example: "User created successfully"
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'

  # User Management Routes
  /api/users:
    get:
      summary: Get paginated list of users
      description: |
        Retrieve a paginated list of users with optional filtering capabilities.
        - **SuperAdmins**: Can view all users.
        - **RegionAdmins/CenterManagers/Instructors**: Can only view users within their assigned scope.
        Results are sorted by creation date (newest first).
      tags:
        - Users
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
        - name: role
          in: query
          description: Filter users by specific role
          schema:
            type: string
            enum: [superadmin, region_admin, center_manager, instructor, student]
        - name: groupId
          in: query
          description: Filter users by group ID
          schema:
            type: string
        - name: isActive
          in: query
          description: Filter by account status
          schema:
            type: boolean
      responses:
        '200':
          description: Successfully retrieved users list
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      users:
                        type: array
                        items:
                          $ref: '#/components/schemas/User'
                      pagination:
                        $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

    post:
      summary: Create new user
      description: |
        Create a new user account manually.
        This endpoint is typically used by administrators to onboard users.
        The system ensures email uniqueness before creation.
        Initial password will be set (requires change on first login).
      tags:
        - Users
      security:
        - bearerAuth: []
      requestBody:
        description: User creation details
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '201':
          description: User created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/User'
                  message:
                    type: string
                    example: "User created successfully"
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          description: Conflict - User with this email already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/users/profile:
    patch:
      summary: Update my profile
      description: |
        Update the currently authenticated user's profile information.
        Users can update their personal details like name and language preference.
        Sensitive fields like role or email cannot be updated here.
      tags:
        - Users
      security:
        - bearerAuth: []
      requestBody:
        description: Allowed profile updates
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                firstName:
                  type: string
                  maxLength: 50
                  description: "User's first name"
                lastName:
                  type: string
                  maxLength: 50
                  description: "User's last name"
                language:
                  type: string
                  maxLength: 10
                  description: "Preferred language code (e.g., 'en', 'es')"
                  example: "es"
                name:
                  type: string
                  maxLength: 100
                  description: "Full name (optional override)"
      responses:
        '200':
          description: Profile updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Profile updated successfully"
                  user:
                    $ref: '#/components/schemas/User'
        '400':
          description: Invalid Input (Invalid language code or length)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/users/{userId}:
    get:
      summary: Get user details
      description: |
        Retrieve detailed profile information for a specific user.
        Access is controlled by strict permission rules:
        - Users can view their own profile.
        - Admins can view users within their hierarchy.
        - SuperAdmins can view any user.
      tags:
        - Users
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/IDParam'
      responses:
        '200':
          description: User details retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

    patch:
      summary: Admin update user
      description: |
        Update a specific user's account details.
        This administrative endpoint allows modifying roles, active status, and other protected fields.
        Restricted to Administrators with appropriate scope.
      tags:
        - Users
      security:
        - bearerAuth: []
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
          description: User ID (MongoDB ObjectId)
      requestBody:
        description: Fields to update
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserRequest'
      responses:
        '200':
          description: User updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/User'
                  message:
                    type: string
                    example: "User updated successfully"
        '400':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    delete:
      summary: Delete user
      description: |
        Soft delete a user account.
        The user status is set to `isActive: false`, preventing future logins.
        Data is preserved for audit purposes.
        Restricted to Administrators.
      tags:
        - Users
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/IDParam'
      responses:
        '200':
          description: User deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "User deleted successfully"
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/users/seed:
    post:
      summary: Seed test data (Dev Only)
      description: |
        Populate the database with initial test users and data.
        **WARNING:** This endpoint performs destructive operations and clears existing collections.
        Available ONLY in development environments.
      tags:
        - Users
      responses:
        '200':
          description: Test data seeded successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Test data seeded successfully"
                  data:
                    type: object
                    properties:
                      users:
                        type: array
                        items:
                          type: object
                          properties:
                            email:
                              type: string
                            password:
                              type: string
                            role:
                              type: string
        '403':
          $ref: '#/components/responses/Forbidden'

  # Region Management Routes
  /api/regions:
    get:
      summary: Get all regions
      description: |
        Retrieve a list of all geographical regions defined in the system.
        Regions are used to organize centers and manage user access scopes.
        Returns a flat list of active regions.
      tags:
        - Regions
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of regions retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Region'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      summary: Create region
      description: |
        Create a new geographical region.
        The `code` must be unique across the system (e.g., 'NA', 'EU', 'APAC').
        Used for high-level organizational grouping.
      tags:
        - Regions
      security:
        - bearerAuth: []
      requestBody:
        description: Region creation details
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRegionRequest'
      responses:
        '201':
          description: Region created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/Region'
                  message:
                    type: string
                    example: "Region created successfully"
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /api/regions/{id}:
    get:
      summary: Get region details
      description: |
        Retrieve detailed information about a specific region by its ID.
        Includes metadata like creation and update timestamps.
      tags:
        - Regions
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/IDParam'
      responses:
        '200':
          description: Region details retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/Region'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/regions/{id}/details:
    get:
      summary: Get region with full details
      description: |
        Retrieve a region with all related data including centers, admins, and statistics.
        Useful for detail views and dashboards.
      tags:
        - Regions
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/IDParam'
      responses:
        '200':
          description: Region with details retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      region:
                        $ref: '#/components/schemas/Region'
                      centers:
                        type: array
                        items:
                          type: object
                          properties:
                            _id:
                              type: string
                            name:
                              type: string
                            code:
                              type: string
                            isActive:
                              type: boolean
                      admins:
                        type: array
                        items:
                          type: object
                          properties:
                            _id:
                              type: string
                            name:
                              type: string
                            email:
                              type: string
                            isActive:
                              type: boolean
                      stats:
                        type: object
                        properties:
                          totalCenters:
                            type: integer
                          activeCenters:
                            type: integer
                          totalStudents:
                            type: integer
                          totalInstructors:
                            type: integer
                          totalCenterManagers:
                            type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      summary: Update region
      description: |
        Update an existing region's details.
        Allows modifying the name or code.
        System checks for code uniqueness exclusion during update.
      tags:
        - Regions
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/IDParam'
      requestBody:
        description: Fields to update
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateRegionRequest'
      responses:
        '200':
          description: Region updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/Region'
                  message:
                    type: string
                    example: "Region updated successfully"
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      summary: Delete region
      description: |
        Permanently delete a region.
        **Warning:** This operation might be restricted if the region has associated centers or users.
      tags:
        - Regions
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/IDParam'
      responses:
        '200':
          description: Region deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Region deleted successfully"
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  # Course Management Routes
  /api/courses:
    get:
      summary: Get paginated list of courses
      description: |
        Retrieve a paginated list of courses with optional filtering.
        - **Instructors**: View only their own courses.
        - **SuperAdmins**: View all courses.
        - **Students**: View all available active courses (filtering rules may apply).
        Results are sorted by creation date (newest first).
      tags:
        - Courses
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
        - name: category
          in: query
          description: Filter by course category
          schema:
            type: string
        - name: status
          in: query
          description: Filter by course status
          schema:
            type: string
            enum: [draft, active, archived, cancelled]
        - name: instructorId
          in: query
          description: Filter by instructor (Admin only)
          schema:
            type: string
      responses:
        '200':
          description: List of courses retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      courses:
                        type: array
                        items:
                          $ref: '#/components/schemas/Course'
                      pagination:
                        $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'

    post:
      summary: Create new course
      description: |
        Create a new course.
        - **Validation**:
          - `title`: 1-200 characters
          - `description`: 1-2000 characters
          - `maxStudents`: 1-1000 (default 30)
        - **Permissions**: Restricted to Instructors.
        - **Initial Status**: Created as 'draft' by default.
      tags:
        - Courses
      security:
        - bearerAuth: []
      requestBody:
        description: Course creation details
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCourseRequest'
      responses:
        '201':
          description: Course created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      course:
                        $ref: '#/components/schemas/Course'
                  message:
                    type: string
                    example: "Course created successfully"
        '400':
          description: Validation Error (Invalid input data)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient permissions (Instructor role required)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/courses/{courseId}:
    get:
      summary: Get course details
      description: |
        Retrieve detailed information about a specific course.
        Includes full instructor profile and enrollment statistics.
        - **Permissions**:
          - Instructors can only view their own courses.
          - Admins/Students can view available courses.
      tags:
        - Courses
      security:
        - bearerAuth: []
      parameters:
        - name: courseId
          in: path
          required: true
          schema:
            type: string
          description: Course ID (MongoDB ObjectId)
      responses:
        '200':
          description: Course details retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      course:
                        $ref: '#/components/schemas/Course'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Course not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    patch:
      summary: Update course
      description: |
        Update an existing course.
        - **Permissions**: Instructor can only update courses they created.
        - **Constraints**: Cannot reduce `maxStudents` below current `enrolledCount`.
      tags:
        - Courses
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/IDParam'
      requestBody:
        description: Fields to update
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCourseRequest'
      responses:
        '200':
          description: Course updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      course:
                        $ref: '#/components/schemas/Course'
                  message:
                    type: string
                    example: "Course updated successfully"
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      summary: Delete course
      description: |
        Permanently delete a course.
        - **Permissions**: Instructor can only delete their own courses.
        - **Constraints**: Cannot delete a course if it has active enrollments.
      tags:
        - Courses
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/IDParam'
      responses:
        '200':
          description: Course deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Course deleted successfully"
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  # Groups Management
  /api/groups:
    get:
      summary: Get paginated list of groups
      description: |
        Retrieve a paginated list of active groups. 
        Results are sorted by creation date in descending order (newest first).
        Only groups with `isActive: true` are returned.
        Requires SuperAdmin privileges.
      tags:
        - Groups
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: Successfully retrieved list of groups
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      groups:
                        type: array
                        items:
                          $ref: '#/components/schemas/Group'
                      pagination:
                        $ref: '#/components/schemas/Pagination'
        '403':
          $ref: '#/components/responses/Forbidden'

    post:
      summary: Create group
      description: |
        Create a new group with the specified details.
        
        Validation Rules:
        - `name`: 1-100 characters
        - `code`: 1-20 characters, must be unique across all groups
        - `domain`: 1-100 characters, must be unique across all groups
        - `enabledPlatforms`: Must select at least one valid platform ('bolsa', 'tms', 'ecmr', 'transcend')
        
        Requires SuperAdmin privileges.
      tags:
        - Groups
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateGroupRequest'
      responses:
        '201':
          description: Group created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      group:
                        $ref: '#/components/schemas/Group'
                  message:
                    type: string
                    example: "Group created successfully"
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          description: Conflict - Group with this code or domain already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/groups/{id}:
    get:
      summary: Get specific group
      description: Retrieve detailed information about a specific group by its ID. Requires SuperAdmin privileges.
      tags:
        - Groups
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/IDParam'
      responses:
        '200':
          description: Successfully retrieved group details
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      group:
                        $ref: '#/components/schemas/Group'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

    patch:
      summary: Update group
      description: |
        Update an existing group's information.
        You can update `name`, `enabledPlatforms`, and `isActive` status.
        At least one field must be provided.
        Requires SuperAdmin privileges.
      tags:
        - Groups
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/IDParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateGroupRequest'
      responses:
        '200':
          description: Group updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      group:
                        $ref: '#/components/schemas/Group'
                  message:
                    type: string
                    example: "Group updated successfully"
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      summary: Delete group
      description: |
        Soft delete a group by setting `isActive` to false.
        The group will no longer appear in standard list requests.
        Requires SuperAdmin privileges.
      tags:
        - Groups
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/IDParam'
      responses:
        '200':
          description: Group deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Group deleted successfully"
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/groups/{id}/platforms:
    put:
      summary: Update group platforms
      description: |
        Replace the list of enabled platforms for a group.
        This represents a full replacement of the access list.
        Requires SuperAdmin privileges.
      tags:
        - Groups
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/IDParam'
      requestBody:
        description: List of platforms to enable for the group
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - enabledPlatforms
              properties:
                enabledPlatforms:
                  type: array
                  description: Array of platform identifiers to enable
                  items:
                    type: string
                    enum: [bolsa, tms, ecmr, transcend]
                  minItems: 1
                  example: ["bolsa", "tms"]
      responses:
        '200':
          description: Platforms updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      group:
                        $ref: '#/components/schemas/Group'
                  message:
                    type: string
                    example: "Platform access updated successfully"
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  # License Management
  /api/licenses:
    get:
      summary: Get platform licenses
      description: |
        Retrieve platform licenses based on user role:
        - **SuperAdmin**: All licenses across all institutions
        - **RegionAdmin**: Licenses for institutions in their region only
        - **CenterManager**: Licenses for their institution only
        
        Licenses determine platform access windows and user limits.
        Use this endpoint to see what platforms are available to each center.
      tags:
        - Licenses
      security:
        - bearerAuth: []
      parameters:
        - name: status
          in: query
          description: Filter by license status
          schema:
            type: string
            enum: [active, expired, pending, suspended]
        - name: platform
          in: query
          description: Filter by platform type
          schema:
            type: string
            enum: [bolsa, tms, ecmr, transcend]
        - name: institutionId
          in: query
          description: Filter by institution ID (SuperAdmin only)
          schema:
            type: string
      responses:
        '200':
          description: List of licenses
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/License'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

    post:
      summary: Create license
      description: |
        Create a new platform license for an institution.
        Defines the time window and user limits for platform access.
        
        **Constraints:**
        - One license per platform per institution (unique constraint)
        - endDate must be after startDate
        - Institution must exist
        
        **SuperAdmin only.**
      tags:
        - Licenses
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateLicenseRequest'
            example:
              institutionId: "507f1f77bcf86cd799439011"
              platform: "bolsa"
              startDate: "2025-01-01"
              endDate: "2025-12-31"
              maxUsers: 50
      responses:
        '201':
          description: License created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/License'
        '400':
          description: Invalid date range or validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          description: License for this platform already exists for the institution
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/licenses/timeline:
    get:
      summary: Get license timeline (EPG visualization)
      description: |
        Retrieve license data formatted for EPG-style timeline visualization.
        Shows license periods by institution with user counts.
        
        **Use Case:** Region Admin dashboard to visualize when licenses
        are active/expiring across all centers in the region.
        
        **Visual Representation:**
        ```
        | Jan | Feb | Mar | Apr | May | Jun |
        |-----|-----|-----|-----|-----|-----|
        IES Piramide
        [=====Bolsa 50 users=====]
              [====TMS 30 users====]
        
        IES Huesca  
              [========ecmr 20 users========]
        ```
      tags:
        - Licenses
      security:
        - bearerAuth: []
      parameters:
        - name: startDate
          in: query
          required: true
          description: Timeline start date
          schema:
            type: string
            format: date
            example: "2025-01-01"
        - name: endDate
          in: query
          required: true
          description: Timeline end date
          schema:
            type: string
            format: date
            example: "2025-12-31"
      responses:
        '200':
          description: Timeline data grouped by institution
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/LicenseTimeline'
        '400':
          description: Missing or invalid date parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/licenses/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: License ID
    
    get:
      summary: Get license details
      description: |
        Retrieve detailed information about a specific license.
        Access is controlled by role:
        - SuperAdmin: Any license
        - RegionAdmin: Only licenses in their region
        - CenterManager: Only their institution's licenses
      tags:
        - Licenses
      security:
        - bearerAuth: []
      responses:
        '200':
          description: License details
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/License'
        '403':
          description: Access denied - license not in your scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          $ref: '#/components/responses/NotFound'

    patch:
      summary: Update license
      description: |
        Update license details including dates and user limits.
        
        **Validation:**
        - endDate must remain after startDate
        - activeUsers cannot exceed maxUsers
        
        **SuperAdmin only.**
      tags:
        - Licenses
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateLicenseRequest'
      responses:
        '200':
          description: License updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/License'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          $ref: '#/components/responses/Forbidden'

    delete:
      summary: Suspend license
      description: |
        Soft delete a license by setting its status to 'suspended'.
        The license remains in the database but is marked as inactive.
        
        **SuperAdmin only.**
      tags:
        - Licenses
      security:
        - bearerAuth: []
      responses:
        '200':
          description: License suspended successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      message:
                        type: string
                      _id:
                        type: string
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  # Subject Management Routes
  /api/subjects:
    get:
      summary: Get all subjects with filters
      description: |
        Retrieve a paginated list of subjects with optional filtering capabilities.
        - **SuperAdmins**: Can view all subjects.
        - **RegionAdmins**: Can view subjects in their region.
        - **CenterManagers**: Can view subjects in their institution.
        - **Instructors**: Can view subjects in their institution/region.
        Results are sorted by creation date (newest first) by default.
      tags:
        - Subjects
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
        - name: search
          in: query
          description: Search by subject name, code, or description (case-insensitive)
          schema:
            type: string
        - name: cycle
          in: query
          description: Filter by cycle
          schema:
            type: string
            enum: [logistica, comercio, both]
        - name: isActive
          in: query
          description: Filter by active status
          schema:
            type: boolean
        - name: sortBy
          in: query
          description: Sort field (createdAt, name, code)
          schema:
            type: string
        - name: sortOrder
          in: query
          description: Sort order
          schema:
            type: string
            enum: [asc, desc]
      responses:
        '200':
          description: Subjects retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      subjects:
                        type: array
                        items:
                          $ref: '#/components/schemas/Subject'
                      pagination:
                        $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

    post:
      summary: Create a subject
      description: |
        Create a new subject with the specified details.
        - **SuperAdmins**: Can create subjects at any level.
        - **RegionAdmins**: Can create subjects in their region.
        - **CenterManagers**: Can create subjects in their institution.
        
        **Validation:**
        - `name`: 2-100 characters
        - `code`: 2-10 characters, unique, alphanumeric with underscores/hyphens
        - `cycle`: Required (logistica, comercio, or both)
        - If institutionId is provided, it must belong to the specified region
      tags:
        - Subjects
      security:
        - bearerAuth: []
      requestBody:
        description: Subject creation details
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSubjectRequest'
      responses:
        '201':
          description: Subject created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/Subject'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          description: Conflict - Subject with this code already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/subjects/{id}:
    get:
      summary: Get subject by ID
      description: |
        Retrieve detailed information about a specific subject by its ID.
        - **SuperAdmins**: Can view any subject.
        - **RegionAdmins**: Can view subjects in their region.
        - **CenterManagers**: Can view subjects in their institution.
        - **Instructors**: Can view subjects in their institution/region.
      tags:
        - Subjects
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/IDParam'
      responses:
        '200':
          description: Subject retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/Subject'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      summary: Update a subject
      description: |
        Update an existing subject's details.
        - **SuperAdmins**: Can update any subject.
        - **RegionAdmins**: Can update subjects in their region.
        - **CenterManagers**: Can update subjects in their institution.
        
        **Validation:**
        - `name`: 2-100 characters
        - `code`: 2-10 characters, unique, alphanumeric with underscores/hyphens
        - If institutionId is provided, it must belong to the specified region
      tags:
        - Subjects
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/IDParam'
      requestBody:
        description: Fields to update
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSubjectRequest'
      responses:
        '200':
          description: Subject updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/Subject'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: Conflict - Subject with this code already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    delete:
      summary: Delete a subject
      description: |
        Permanently delete a subject.
        - **SuperAdmins**: Can delete any subject.
        - **RegionAdmins**: Can delete subjects in their region.
        - **CenterManagers**: Can delete subjects in their institution.
      tags:
        - Subjects
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/IDParam'
      responses:
        '200':
          description: Subject deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      message:
                        type: string
                        example: "Subject deleted"
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/subjects/{id}/details:
    get:
      summary: Get subject details with statistics
      description: |
        Retrieve a subject with all related data including region, institution, and statistics.
        Useful for detail views and dashboards.
        - **SuperAdmins**: Can view any subject's details.
        - **RegionAdmins**: Can view subject details in their region.
        - **CenterManagers**: Can view subject details in their institution.
        - **Instructors**: Can view subject details in their institution/region.
      tags:
        - Subjects
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/IDParam'
      responses:
        '200':
          description: Subject details retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      subject:
                        $ref: '#/components/schemas/Subject'
                      region:
                        type: object
                        properties:
                          _id:
                            type: string
                          name:
                            type: string
                          code:
                            type: string
                      institution:
                        type: object
                        properties:
                          _id:
                            type: string
                          name:
                            type: string
                          code:
                            type: string
                      stats:
                        type: object
                        properties:
                          totalStudents:
                            type: integer
                          totalInstructors:
                            type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/subjects/cycle/{cycle}:
    get:
      summary: Get subjects by cycle
      description: |
        Retrieve subjects filtered by their cycle (logistica, comercio, or both).
        - **SuperAdmins**: Can view all subjects.
        - **RegionAdmins**: Can view subjects in their region.
        - **CenterManagers**: Can view subjects in their institution.
        - **Instructors**: Can view subjects in their institution/region.
        Results are sorted by name in ascending order.
      tags:
        - Subjects
      security:
        - bearerAuth: []
      parameters:
        - name: cycle
          in: path
          required: true
          description: Cycle to filter by
          schema:
            type: string
            enum: [logistica, comercio, both]
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: Subjects retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      subjects:
                        type: array
                        items:
                          $ref: '#/components/schemas/Subject'
                      pagination:
                        $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/subjects/active:
    get:
      summary: Get active subjects
      description: |
        Retrieve subjects that are currently active (isActive: true).
        - **SuperAdmins**: Can view all active subjects.
        - **RegionAdmins**: Can view active subjects in their region.
        - **CenterManagers**: Can view active subjects in their institution.
        - **Instructors**: Can view active subjects in their institution/region.
      tags:
        - Subjects
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: Active subjects retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      subjects:
                        type: array
                        items:
                          $ref: '#/components/schemas/Subject'
                      pagination:
                        $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  # Region Admin Management
  /api/region-admin/users:
    get:
      summary: Get users in region
      description: |
        Retrieve all users within the authenticated region admin's region.
        
        **Scope Constraint:** Only returns users where `regionId` matches
        the authenticated user's `regionId`.
        
        **Filtering:**
        - `role`: Filter by user role (center_manager, instructor, student)
        - `institutionId`: Filter by specific center
        - `isActive`: Filter by active status
        
        **Use Cases:**
        - View all teachers in the region
        - Find students by center
        - Manage user accounts
      tags:
        - Region Admin
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
        - name: role
          in: query
          description: Filter by user role
          schema:
            type: string
            enum: [center_manager, instructor, student]
        - name: institutionId
          in: query
          description: Filter by institution/center ID
          schema:
            type: string
        - name: isActive
          in: query
          description: Filter by active status
          schema:
            type: boolean
      responses:
        '200':
          description: Users list
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      users:
                        type: array
                        items:
                          $ref: '#/components/schemas/User'
                      pagination:
                        $ref: '#/components/schemas/Pagination'
        '403':
          description: Forbidden - User is not a region_admin
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    post:
      summary: Create user in region
      description: |
        Create a new user within the region admin's region.
        
        **Allowed Roles to Create:**
        - `center_manager`: Director of a center
        - `instructor`: Teacher/Instructor (equivalent to professor)
        - `student`: Student learner
        
        **Constraint:** Created user's `regionId` will be automatically set
        to match the authenticated region admin's `regionId`.
        
        **Time Windows (US-006):**
        - `validFrom`: Optional date when user account becomes active
        - `validUntil`: Optional date when user account is automatically deactivated
        - Used for temporary access (e.g., semester-long courses)
      tags:
        - Region Admin
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/CreateUserRequest'
                - type: object
                  properties:
                    institutionId:
                      type: string
                      description: Required for center_manager and instructor roles
                    validFrom:
                      type: string
                      format: date
                      description: Optional - Start date for temporary access
                    validUntil:
                      type: string
                      format: date
                      description: Optional - End date for temporary access
            example:
              email: "new.teacher@school.edu"
              firstName: "John"
              lastName: "Doe"
              password: "SecurePass123!"
              role: "instructor"
              institutionId: "507f1f77bcf86cd799439011"
              validFrom: "2025-01-15"
              validUntil: "2025-06-30"
      responses:
        '201':
          description: User created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/User'
        '400':
          description: Validation error or missing required fields
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - Cannot create this role
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/region-admin/users/{userId}:
    parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
        description: User ID to manage
    
    get:
      summary: Get user details in region
      description: |
        Get detailed information about a user in the region.
        User must belong to the same region as the authenticated admin.
      tags:
        - Region Admin
      security:
        - bearerAuth: []
      responses:
        '200':
          description: User details
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/User'
        '403':
          description: User is not in your region
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          $ref: '#/components/responses/NotFound'

    patch:
      summary: Update user in region
      description: |
        Update a user within the region.
        
        **Allowed Updates:**
        - firstName, lastName
        - isActive (for blocking/unblocking)
        - institutionId (reassign to different center)
        - validFrom, validUntil (adjust access windows)
        
        **Cannot Change:**
        - role
        - regionId
        - email
      tags:
        - Region Admin
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                firstName:
                  type: string
                lastName:
                  type: string
                isActive:
                  type: boolean
                institutionId:
                  type: string
                validFrom:
                  type: string
                  format: date
                validUntil:
                  type: string
                  format: date
      responses:
        '200':
          description: User updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/User'
        '403':
          description: User is not in your region
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    delete:
      summary: Delete user in region
      description: |
        Soft delete a user by setting isActive to false.
        User must belong to the same region.
      tags:
        - Region Admin
      security:
        - bearerAuth: []
      responses:
        '200':
          description: User deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
        '403':
          description: User is not in your region
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/region-admin/admins:
    get:
      summary: List other admins in region
      description: |
        List other region_admin users in the SAME region.
        Used for managing backup admins or delegating responsibilities.
        
        **Note:** Does not include the currently authenticated user.
        Cannot view or manage admins from other regions.
      tags:
        - Region Admin
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of admins in the region
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'

    post:
      summary: Create admin for region
      description: |
        Create another region_admin for the same region.
        Useful for adding backup administrators or delegating responsibilities.
        
        The new admin will have the same regionId as the creator.
      tags:
        - Region Admin
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - firstName
                - lastName
                - password
              properties:
                email:
                  type: string
                  format: email
                firstName:
                  type: string
                lastName:
                  type: string
                password:
                  type: string
                  minLength: 8
      responses:
        '201':
          description: Admin created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/User'

  /api/region-admin/centers/{institutionId}:
    get:
      summary: Get center details with statistics
      description: |
        Get detailed information about a center/institution including:
        - Center manager information
        - Student count
        - Instructor count
        - Course count
        - Active licenses
        
        Center must be in the same region as the authenticated admin.
      tags:
        - Region Admin
      security:
        - bearerAuth: []
      parameters:
        - name: institutionId
          in: path
          required: true
          schema:
            type: string
          description: Institution/center ID
      responses:
        '200':
          description: Center details with statistics
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      institution:
                        $ref: '#/components/schemas/Institution'
                      centerManager:
                        type: object
                        properties:
                          _id:
                            type: string
                          name:
                            type: string
                          email:
                            type: string
                          isActive:
                            type: boolean
                      stats:
                        type: object
                        properties:
                          totalStudents:
                            type: integer
                          totalInstructors:
                            type: integer
                          totalCourses:
                            type: integer
                          activeLicenses:
                            type: integer
        '403':
          description: Center is not in your region
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/region-admin/stats:
    get:
      summary: Get region statistics
      description: |
        Get aggregated statistics for the region admin's region.
        
        Includes:
        - Total centers
        - Total students
        - Total instructors  
        - Total center managers
        - Active licenses
        - Licenses expiring within 30 days
      tags:
        - Region Admin
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Region statistics
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      totalCenters:
                        type: integer
                        example: 15
                      totalStudents:
                        type: integer
                        example: 2450
                      totalInstructors:
                        type: integer
                        example: 95
                      totalCenterManagers:
                        type: integer
                        example: 12
                      activeLicenses:
                        type: integer
                        example: 45
                      expiringLicenses:
                        type: integer
                        description: Licenses expiring within 30 days
                        example: 3
  # Admin Dashboard Routes
  /api/admin/dashboard:
    get:
      summary: Get admin dashboard overview
      description: Retrieve comprehensive admin dashboard statistics and metrics
      tags:
        - Admin Dashboard
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Admin dashboard data
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      totalUsers:
                        type: integer
                        example: 1250
                      activeUsers:
                        type: integer
                        example: 892
                      totalCourses:
                        type: integer
                        example: 45
                      totalEnrollments:
                        type: integer
                        example: 3200
                      revenue:
                        type: number
                        example: 45000.50
                      recentActivity:
                        type: array
                        items:
                          type: object
                          properties:
                            action:
                              type: string
                              example: "user_registered"
                            timestamp:
                              type: string
                              format: date-time
                            details:
                              type: object
        '403':
          $ref: '#/components/responses/Forbidden'

  /api/admin/analytics:
    get:
      summary: Get admin analytics data
      description: Retrieve detailed analytics for admin reporting
      tags:
        - Admin Dashboard
      security:
        - bearerAuth: []
      parameters:
        - name: period
          in: query
          schema:
            type: string
            enum: [week, month, quarter, year]
            default: month
        - name: startDate
          in: query
          schema:
            type: string
            format: date
        - name: endDate
          in: query
          schema:
            type: string
            format: date
      responses:
        '200':
          description: Analytics data
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      userGrowth:
                        type: object
                        properties:
                          total:
                            type: integer
                          growth:
                            type: number
                      courseStats:
                        type: object
                        properties:
                          published:
                            type: integer
                          draft:
                            type: integer
                          completionRate:
                            type: number
                      revenue:
                        type: object
                        properties:
                          total:
                            type: number
                          byPeriod:
                            type: array
        '403':
          $ref: '#/components/responses/Forbidden'

  /api/admin/analytics/usage:
    get:
      summary: Get usage analytics
      description: |
        Retrieve usage analytics including login heatmap and usage by region.
        Used for dashboard visualizations.
      tags:
        - Admin Dashboard
      security:
        - bearerAuth: []
      parameters:
        - name: startDate
          in: query
          required: true
          schema:
            type: string
            format: date
        - name: endDate
          in: query
          required: true
          schema:
            type: string
            format: date
      responses:
        '200':
          description: Usage analytics data
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      loginHeatmap:
                        type: array
                        items:
                          type: object
                          properties:
                            date:
                              type: string
                              format: date
                            hour:
                              type: integer
                            count:
                              type: integer
                      usageByRegion:
                        type: array
                        items:
                          type: object
                          properties:
                            regionId:
                              type: string
                            regionName:
                              type: string
                            loginCount:
                              type: integer
                            percentage:
                              type: number
                      summary:
                        type: object
                        properties:
                          totalLogins:
                            type: integer
                          uniqueUsers:
                            type: integer
                          avgLoginsPerDay:
                            type: number
                          peakHour:
                            type: integer
                          peakDay:
                            type: string
                            format: date
        '403':
          $ref: '#/components/responses/Forbidden'

  /api/admin/charts:
    get:
      summary: Get chart data for admin dashboard
      description: Retrieve chart data for various admin dashboard visualizations
      tags:
        - Admin Dashboard
      security:
        - bearerAuth: []
      parameters:
        - name: chartType
          in: query
          required: true
          schema:
            type: string
            enum: [user-growth, course-completion, enrollment-trends, revenue]
        - name: period
          in: query
          schema:
            type: string
            enum: [7d, 30d, 90d, 1y]
            default: 30d
      responses:
        '200':
          description: Chart data
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        label:
                          type: string
                        value:
                          type: number
                        date:
                          type: string
                          format: date
        '403':
          $ref: '#/components/responses/Forbidden'

  /api/admin/achievements:
    get:
      summary: Get system-wide achievements
      description: Retrieve all achievements and completion statistics
      tags:
        - Admin Dashboard
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Achievements data
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        description:
                          type: string
                        completionCount:
                          type: integer
                        completionRate:
                          type: number
        '403':
          $ref: '#/components/responses/Forbidden'

  /api/admin/report:
    get:
      summary: Generate admin report
      description: Generate comprehensive admin report for specified period
      tags:
        - Admin Dashboard
      security:
        - bearerAuth: []
      parameters:
        - name: reportType
          in: query
          required: true
          schema:
            type: string
            enum: [summary, detailed, financial, user-activity]
        - name: format
          in: query
          schema:
            type: string
            enum: [json, csv, pdf]
            default: json
        - name: startDate
          in: query
          schema:
            type: string
            format: date
        - name: endDate
          in: query
          schema:
            type: string
            format: date
      responses:
        '200':
          description: Report data
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    description: Report data structure varies by report type
        '403':
          $ref: '#/components/responses/Forbidden'

  /api/admin/top-performers:
    get:
      summary: Get top performing users
      description: Retrieve top performing students and instructors by various metrics
      tags:
        - Admin Dashboard
      security:
        - bearerAuth: []
      parameters:
        - name: category
          in: query
          required: true
          schema:
            type: string
            enum: [students, instructors, courses]
        - name: metric
          in: query
          required: true
          schema:
            type: string
            enum: [completion-rate, engagement, revenue, ratings]
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 10
      responses:
        '200':
          description: Top performers data
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        user:
                          $ref: '#/components/schemas/User'
                        score:
                          type: number
                        rank:
                          type: integer

  /api/admin/activity/recent:
    get:
      summary: Get recent system activity
      description: Retrieve recent activity logs across the platform
      tags:
        - Admin Dashboard
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/LimitParam'
        - name: activityType
          in: query
          schema:
            type: string
            enum: [user, course, enrollment, payment]
      responses:
        '200':
          description: Recent activity data
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        type:
                          type: string
                        description:
                          type: string
                        user:
                          $ref: '#/components/schemas/User'
                        timestamp:
                          type: string
                          format: date-time
                        metadata:
                          type: object

  # Instructor Dashboard Routes
  /api/instructor/dashboard:
    get:
      summary: Get instructor dashboard overview
      description: Retrieve instructor-specific dashboard statistics and metrics
      tags:
        - Instructor Dashboard
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Instructor dashboard data
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      totalCourses:
                        type: integer
                        example: 5
                      totalStudents:
                        type: integer
                        example: 150
                      avgCompletionRate:
                        type: number
                        example: 78.5
                      totalRevenue:
                        type: number
                        example: 2500.00
                      recentEnrollments:
                        type: integer
                        example: 12
                      pendingGradings:
                        type: integer
                        example: 8
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/instructor/courses/{courseId}/analytics:
    get:
      summary: Get course analytics for instructor
      description: Retrieve detailed analytics for a specific course
      tags:
        - Instructor Dashboard
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/IDParam'
        - name: period
          in: query
          schema:
            type: string
            enum: [7d, 30d, 90d, 1y]
            default: 30d
      responses:
        '200':
          description: Course analytics data
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      enrollmentCount:
                        type: integer
                      completionRate:
                        type: number
                      avgProgress:
                        type: number
                      engagementMetrics:
                        type: object
                      revenue:
                        type: number
                      studentActivity:
                        type: array
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /api/instructor/courses/{courseId}/students:
    get:
      summary: Get enrolled students for course
      description: Retrieve list of students enrolled in instructor's course
      tags:
        - Instructor Dashboard
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/IDParam'
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
        - name: status
          in: query
          schema:
            type: string
            enum: [active, completed, dropped]
      responses:
        '200':
          description: Enrolled students
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      students:
                        type: array
                        items:
                          type: object
                          properties:
                            user:
                              $ref: '#/components/schemas/User'
                            enrollmentDate:
                              type: string
                              format: date-time
                            progress:
                              type: number
                            completionDate:
                              type: string
                              format: date-time
                            lastActivity:
                              type: string
                              format: date-time
                      pagination:
                        $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /api/instructor/courses/{courseId}/enrollment-chart:
    get:
      summary: Get course enrollment chart data
      description: Retrieve enrollment trends data for charting
      tags:
        - Instructor Dashboard
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/IDParam'
        - name: period
          in: query
          schema:
            type: string
            enum: [7d, 30d, 90d, 1y]
            default: 30d
      responses:
        '200':
          description: Enrollment chart data
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        date:
                          type: string
                          format: date
                        enrollments:
                          type: integer
                        cumulative:
                          type: integer

  /api/instructor/courses/{courseId}/completion-chart:
    get:
      summary: Get course completion chart data
      description: Retrieve completion trends data for charting
      tags:
        - Instructor Dashboard
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/IDParam'
        - name: period
          in: query
          schema:
            type: string
            enum: [7d, 30d, 90d, 1y]
            default: 30d
      responses:
        '200':
          description: Completion chart data
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        date:
                          type: string
                          format: date
                        completions:
                          type: integer
                        completionRate:
                          type: number

  /api/instructor/courses/{courseId}/report:
    get:
      summary: Generate course report
      description: Generate detailed report for instructor's course
      tags:
        - Instructor Dashboard
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/IDParam'
        - name: reportType
          in: query
          schema:
            type: string
            enum: [performance, engagement, completion, revenue]
            default: performance
        - name: format
          in: query
          schema:
            type: string
            enum: [json, csv, pdf]
            default: json
      responses:
        '200':
          description: Course report data
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object

  /api/instructor/courses/{courseId}/students/{studentId}/grade:
    put:
      summary: Grade student assignment
      description: Submit or update grade for student assignment
      tags:
        - Instructor Dashboard
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/IDParam'
        - name: studentId
          in: path
          required: true
          schema:
            type: string
          description: Student ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - assignmentId
                - grade
              properties:
                assignmentId:
                  type: string
                grade:
                  type: number
                  minimum: 0
                  maximum: 100
                feedback:
                  type: string
                  maxLength: 1000
                gradedBy:
                  type: string
      responses:
        '200':
          description: Grade submitted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Grade submitted successfully"

  /api/instructor/courses:
    get:
      summary: Get instructor's courses
      description: Retrieve all courses created by the current instructor
      tags:
        - Instructor Dashboard
      security:
        - bearerAuth: []
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum: [draft, active, archived]
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: Instructor courses
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      courses:
                        type: array
                        items:
                          $ref: '#/components/schemas/Course'
                      pagination:
                        $ref: '#/components/schemas/Pagination'

  # Student Dashboard Routes
  /api/student/dashboard:
    get:
      summary: Get student dashboard overview
      description: Retrieve student-specific dashboard with progress and achievements
      tags:
        - Student Dashboard
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Student dashboard data
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      enrolledCourses:
                        type: integer
                        example: 3
                      completedCourses:
                        type: integer
                        example: 1
                      inProgressCourses:
                        type: integer
                        example: 2
                      totalAchievements:
                        type: integer
                        example: 8
                      currentStreak:
                        type: integer
                        example: 5
                      studyTimeThisWeek:
                        type: integer
                        example: 480
                      nextDeadline:
                        type: string
                        format: date-time
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/student/progress:
    get:
      summary: Get student learning progress
      description: Retrieve detailed progress across all enrolled courses
      tags:
        - Student Dashboard
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Student progress data
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        course:
                          $ref: '#/components/schemas/Course'
                        progress:
                          type: number
                          minimum: 0
                          maximum: 100
                        timeSpent:
                          type: integer
                        lastAccessed:
                          type: string
                          format: date-time
                        completionDate:
                          type: string
                          format: date-time
                        status:
                          type: string
                          enum: [not-started, in-progress, completed]
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/student/achievements:
    get:
      summary: Get student achievements
      description: Retrieve all achievements earned by the student
      tags:
        - Student Dashboard
      security:
        - bearerAuth: []
      parameters:
        - name: category
          in: query
          schema:
            type: string
            enum: [learning, engagement, completion, social]
      responses:
        '200':
          description: Student achievements
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        description:
                          type: string
                        icon:
                          type: string
                        earnedDate:
                          type: string
                          format: date-time
                        category:
                          type: string
                        rarity:
                          type: string
                          enum: [common, rare, epic, legendary]
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/student/courses:
    get:
      summary: Get enrolled courses
      description: Retrieve all courses the student is enrolled in
      tags:
        - Student Dashboard
      security:
        - bearerAuth: []
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum: [active, completed, archived]
      responses:
        '200':
          description: Enrolled courses
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        course:
                          $ref: '#/components/schemas/Course'
                        enrollmentDate:
                          type: string
                          format: date-time
                        progress:
                          type: number
                        status:
                          type: string
                        certificateEarned:
                          type: boolean
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/student/progress-chart:
    get:
      summary: Get progress chart data
      description: Retrieve progress data for visualization charts
      tags:
        - Student Dashboard
      security:
        - bearerAuth: []
      parameters:
        - name: period
          in: query
          schema:
            type: string
            enum: [7d, 30d, 90d, 1y]
            default: 30d
        - name: courseId
          in: query
          schema:
            type: string
          description: Specific course ID (optional)
      responses:
        '200':
          description: Progress chart data
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        date:
                          type: string
                          format: date
                        studyTime:
                          type: integer
                        lessonsCompleted:
                          type: integer
                        progressIncrease:
                          type: number
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/student/recommendations:
    get:
      summary: Get course recommendations
      description: Retrieve personalized course recommendations for the student
      tags:
        - Student Dashboard
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: Course recommendations
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        course:
                          $ref: '#/components/schemas/Course'
                        recommendationReason:
                          type: string
                        matchScore:
                          type: number
                          minimum: 0
                          maximum: 1
                        category:
                          type: string
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/student/report:
    get:
      summary: Generate student progress report
      description: Generate comprehensive progress report for the student
      tags:
        - Student Dashboard
      security:
        - bearerAuth: []
      parameters:
        - name: format
          in: query
          schema:
            type: string
            enum: [json, pdf, csv]
            default: json
        - name: period
          in: query
          schema:
            type: string
            enum: [month, quarter, year, all-time]
            default: month
      responses:
        '200':
          description: Student progress report
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      summary:
                        type: object
                      courses:
                        type: array
                      achievements:
                        type: array
                      studyPatterns:
                        type: object

  # Data Visualization Routes
  /api/data-visualization/progress-trend:
    get:
      summary: Get progress trend data
      description: Retrieve progress trends for data visualization
      tags:
        - Data Visualization
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/PeriodParam'
        - name: groupBy
          in: query
          schema:
            type: string
            enum: [day, week, month]
            default: day
        - name: courseId
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Progress trend data
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        period:
                          type: string
                        avgProgress:
                          type: number
                        totalStudents:
                          type: integer
                        activeStudents:
                          type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/data-visualization/course-completion/{courseId}:
    get:
      summary: Get course completion data
      description: Retrieve completion statistics for a specific course
      tags:
        - Data Visualization
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/IDParam'
        - $ref: '#/components/parameters/PeriodParam'
      responses:
        '200':
          description: Course completion data
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      totalEnrolled:
                        type: integer
                      completed:
                        type: integer
                      inProgress:
                        type: integer
                      notStarted:
                        type: integer
                      completionRate:
                        type: number
                      avgTimeToComplete:
                        type: integer
                      completionTrend:
                        type: array
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /api/data-visualization/achievement-distribution:
    get:
      summary: Get achievement distribution data
      description: Retrieve achievement distribution across the platform
      tags:
        - Data Visualization
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Achievement distribution data
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        achievement:
                          type: string
                        totalEarned:
                          type: integer
                        distribution:
                          type: object
                          properties:
                            common:
                              type: integer
                            rare:
                              type: integer
                            epic:
                              type: integer
                            legendary:
                              type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/data-visualization/revenue-chart:
    get:
      summary: Get revenue chart data
      description: Retrieve revenue data for visualization
      tags:
        - Data Visualization
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/PeriodParam'
        - name: groupBy
          in: query
          schema:
            type: string
            enum: [day, week, month]
            default: week
      responses:
        '200':
          description: Revenue chart data
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        period:
                          type: string
                        revenue:
                          type: number
                        subscriptions:
                          type: integer
                        oneTimePurchases:
                          type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  # Dashboard Routes (SuperAdmin)
  /api/dashboard/stats:
    get:
      summary: Get superadmin dashboard statistics
      description: Retrieve high-level platform statistics for superadmin
      tags:
        - Dashboard
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Dashboard statistics
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      totalUsers:
                        type: integer
                      totalGroups:
                        type: integer
                      totalRevenue:
                        type: number
                      activeUsers:
                        type: integer
                      systemHealth:
                        type: string
                        enum: [healthy, warning, critical]
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /api/dashboard/regions:
    get:
      summary: Get regions overview
      description: Retrieve statistics for all regions
      tags:
        - Dashboard
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Regions overview
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        region:
                          $ref: '#/components/schemas/Region'
                        userCount:
                          type: integer
                        activeUsers:
                          type: integer
                        revenue:
                          type: number
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /api/dashboard/admins:
    get:
      summary: Get admin users overview
      description: Retrieve list and statistics of admin users
      tags:
        - Dashboard
      security:
        - bearerAuth: []
      parameters:
        - name: regionId
          in: query
          schema:
            type: string
        - name: status
          in: query
          schema:
            type: string
            enum: [active, inactive]
      responses:
        '200':
          description: Admin users overview
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        admin:
                          $ref: '#/components/schemas/User'
                        region:
                          $ref: '#/components/schemas/Region'
                        managedUsers:
                          type: integer
                        lastActive:
                          type: string
                          format: date-time
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  # Educational Materials Routes
  /api/educational-materials/modules:
    get:
      summary: Get educational modules
      description: Retrieve list of educational modules for a specific cycle
      tags:
        - Educational Materials
      security:
        - bearerAuth: []
      parameters:
        - name: cycle
          in: query
          description: Cycle code to filter modules
          schema:
            type: string
      responses:
        '200':
          description: Modules retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                        name:
                          type: string
                        cycle:
                          type: string

  /api/educational-materials/modules/{code}/learning-results:
    get:
      summary: Get learning results for module
      description: Retrieve learning results (RA) for a specific module
      tags:
        - Educational Materials
      security:
        - bearerAuth: []
      parameters:
        - name: code
          in: path
          required: true
          description: Module code
          schema:
            type: string
      responses:
        '200':
          description: Learning results retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        number:
                          type: integer
                        description:
                          type: string

  /api/educational-materials/exercises:
    get:
      summary: Get exercises
      description: Retrieve paginated list of exercises with filtering
      tags:
        - Educational Materials
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
        - name: moduleCode
          in: query
          description: Filter by module code
          schema:
            type: string
        - name: difficulty
          in: query
          description: Filter by difficulty level
          schema:
            type: string
            enum: [basic, intermediate, advanced]
        - name: isVisible
          in: query
          description: Filter by visibility
          schema:
            type: boolean
      responses:
        '200':
          description: Exercises retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/Exercise'
                      pagination:
                        $ref: '#/components/schemas/Pagination'

    post:
      summary: Create new exercise
      description: Create a new educational exercise
      tags:
        - Educational Materials
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateExerciseRequest'
      responses:
        '201':
          description: Exercise created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/Exercise'

  /api/educational-materials/exercises/{id}:
    get:
      summary: Get exercise by ID
      description: Retrieve a specific exercise by its ID
      tags:
        - Educational Materials
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: Exercise ID
          schema:
            type: string
      responses:
        '200':
          description: Exercise retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/Exercise'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      summary: Update exercise
      description: Update an existing exercise
      tags:
        - Educational Materials
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: Exercise ID
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateExerciseRequest'
      responses:
        '200':
          description: Exercise updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/Exercise'

    delete:
      summary: Delete exercise
      description: Delete an exercise
      tags:
        - Educational Materials
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: Exercise ID
          schema:
            type: string
      responses:
        '200':
          description: Exercise deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string

  /api/educational-materials/exercises/{id}/visibility:
    patch:
      summary: Toggle exercise visibility
      description: Toggle the visibility status of an exercise
      tags:
        - Educational Materials
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: Exercise ID
          schema:
            type: string
      responses:
        '200':
          description: Visibility toggled successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      _id:
                        type: string
                      isVisible:
                        type: boolean

  # Institution Routes
  /api/institutions:
    get:
      summary: Get paginated list of institutions
      description: Retrieve institutions with filtering and pagination
      tags:
        - Institutions
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
        - name: regionId
          in: query
          schema:
            type: string
        - name: isActive
          in: query
          schema:
            type: boolean
      responses:
        '200':
          description: Institutions list
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      institutions:
                        type: array
                        items:
                          $ref: '#/components/schemas/Institution'
                      pagination:
                        $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      summary: Create institution
      description: Create a new institution
      tags:
        - Institutions
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateInstitutionRequest'
      responses:
        '201':
          description: Institution created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/Institution'
                  message:
                    type: string
                    example: "Institution created successfully"
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'

  /api/institutions/{id}:
    get:
      summary: Get specific institution
      description: Retrieve detailed information about a specific institution
      tags:
        - Institutions
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/IDParam'
      responses:
        '200':
          description: Institution information
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/Institution'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/institutions/{id}/details:
    get:
      summary: Get institution with full details
      description: |
        Retrieve an institution with all related data including region, center manager, 
        and student/instructor/course statistics.
      tags:
        - Institutions
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/IDParam'
      responses:
        '200':
          description: Institution with details retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      institution:
                        $ref: '#/components/schemas/Institution'
                      region:
                        type: object
                        nullable: true
                        properties:
                          _id:
                            type: string
                          name:
                            type: string
                          code:
                            type: string
                      centerManager:
                        type: object
                        nullable: true
                        properties:
                          _id:
                            type: string
                          name:
                            type: string
                          email:
                            type: string
                      stats:
                        type: object
                        properties:
                          totalStudents:
                            type: integer
                          totalInstructors:
                            type: integer
                          totalCourses:
                            type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

    patch:
      summary: Update institution
      description: Update institution information
      tags:
        - Institutions
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/IDParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateInstitutionRequest'
      responses:
        '200':
          description: Institution updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/Institution'
                  message:
                    type: string
                    example: "Institution updated successfully"
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      summary: Delete institution
      description: Soft delete an institution
      tags:
        - Institutions
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/IDParam'
      responses:
        '200':
          description: Institution deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Institution deleted successfully"
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/institutions/{id}/platforms:
    get:
      summary: Get institution platform configurations
      description: |
        Retrieve platform configurations (enabled/disabled, valid dates) for an institution.
        - **SuperAdmins**: Can view any institution's platforms.
        - **RegionAdmins**: Can view platforms for institutions in their region.
        - **CenterManagers**: Can view their own institution's platforms.
      tags:
        - Institutions
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/IDParam'
      responses:
        '200':
          description: Platform configurations retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/InstitutionPlatform'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

    patch:
      summary: Update institution platform configurations
      description: |
        Enable/disable platforms for an institution with optional validity dates.
        - **SuperAdmins**: Can update any institution's platforms.
        - **RegionAdmins**: Can update platforms for institutions in their region.
        
        **Platform Options:**
        - `bolsa`: Bolsa de Carga platform
        - `tms`: TMS platform
        - `ecmr`: eCMR platform
        - `transcend`: TRANSCEND platform
        - `truckerapp`: TruckerAPP platform
        
        **Request Body:**
        Array of platform objects with:
        - `platform`: Platform identifier (required)
        - `isEnabled`: Boolean to enable/disable (optional)
        - `validFrom`: Start date for access (optional)
        - `validUntil`: End date for access (optional)
      tags:
        - Institutions
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/IDParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - platforms
              properties:
                platforms:
                  type: array
                  items:
                    $ref: '#/components/schemas/InstitutionPlatformUpdate'
              example:
                platforms:
                  - platform: "bolsa"
                    isEnabled: true
                    validFrom: "2025-01-01"
                    validUntil: "2025-12-31"
                  - platform: "tms"
                    isEnabled: false
      responses:
        '200':
          description: Platform configurations updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/InstitutionPlatform'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  # Group Admin Routes
  /api/group-admin/students:
    get:
      summary: Get group students
      description: Retrieve all students in the admin's group
      tags:
        - Group Admin
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
        - name: status
          in: query
          schema:
            type: string
            enum: [active, inactive]
        - name: institutionId
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Group students
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      students:
                        type: array
                        items:
                          $ref: '#/components/schemas/User'
                      pagination:
                        $ref: '#/components/schemas/Pagination'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/group-admin/students/{studentId}/role:
    put:
      summary: Update student role
      description: Change a student's role within the group
      tags:
        - Group Admin
      security:
        - bearerAuth: []
      parameters:
        - name: studentId
          in: path
          required: true
          schema:
            type: string
          description: Student ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - role
              properties:
                role:
                  type: string
                  enum: [student, instructor]
      responses:
        '200':
          description: Role updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Role updated successfully"
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/group-admin/enrollment-requests:
    get:
      summary: Get enrollment requests
      description: Retrieve pending enrollment requests for approval
      tags:
        - Group Admin
      security:
        - bearerAuth: []
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum: [pending, approved, rejected]
            default: pending
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: Enrollment requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      requests:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                            student:
                              $ref: '#/components/schemas/User'
                            course:
                              $ref: '#/components/schemas/Course'
                            requestedAt:
                              type: string
                              format: date-time
                            status:
                              type: string
                      pagination:
                        $ref: '#/components/schemas/Pagination'
        '403':
          $ref: '#/components/responses/Forbidden'

  /api/group-admin/enrollment-requests/{requestId}/approve:
    post:
      summary: Approve enrollment request
      description: Approve a pending enrollment request
      tags:
        - Group Admin
      security:
        - bearerAuth: []
      parameters:
        - name: requestId
          in: path
          required: true
          schema:
            type: string
          description: Request ID
      responses:
        '200':
          description: Request approved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Enrollment request approved"
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/group-admin/enrollment-requests/{requestId}/reject:
    post:
      summary: Reject enrollment request
      description: Reject a pending enrollment request
      tags:
        - Group Admin
      security:
        - bearerAuth: []
      parameters:
        - name: requestId
          in: path
          required: true
          schema:
            type: string
          description: Request ID
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
                  maxLength: 500
      responses:
        '200':
          description: Request rejected successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Enrollment request rejected"
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/group-admin/students/{studentId}/remove:
    delete:
      summary: Remove student from group
      description: Remove a student from the admin's group
      tags:
        - Group Admin
      security:
        - bearerAuth: []
      parameters:
        - name: studentId
          in: path
          required: true
          schema:
            type: string
          description: Student ID
      responses:
        '200':
          description: Student removed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Student removed from group"
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/group-admin/stats:
    get:
      summary: Get group statistics
      description: Retrieve statistics for the admin's group
      tags:
        - Group Admin
      security:
        - bearerAuth: []
      responses:
        '403':
          $ref: '#/components/responses/Forbidden'
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      totalStudents:
                        type: integer
                      activeStudents:
                        type: integer
                      totalCourses:
                        type: integer
                      totalEnrollments:
                        type: integer
                        completionRate:
                        type: number
                      recentActivity:
                        type: array

  # Centers Routes
  /api/centers/{id}/teachers:
    get:
      summary: Get teachers for a center
      description: Retrieve instructors associated with a specific center
      tags:
        - Centers
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: Teachers retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      teachers:
                        type: array
                        items:
                          $ref: '#/components/schemas/User'
                      pagination:
                        $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /api/centers/{id}/students:
    get:
      summary: Get students for a center
      description: Retrieve students enrolled at a specific center
      tags:
        - Centers
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: Students retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      students:
                        type: array
                        items:
                          $ref: '#/components/schemas/User'
                      pagination:
                        $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /api/centers/{id}/courses:
    get:
      summary: Get courses for a center
      description: Retrieve courses offered at a specific center
      tags:
        - Centers
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: Courses retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      courses:
                        type: array
                        items:
                          $ref: '#/components/schemas/Course'
                      pagination:
                        $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  # Educational Materials Routes
  /api/educational-materials/modules:
    get:
      summary: Get educational modules
      description: Retrieve all available educational modules
      tags:
        - Educational Materials
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Modules retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array

  /api/educational-materials/modules/{code}/learning-results:
    get:
      summary: Get learning results for a module
      description: Retrieve learning outcomes for a specific module
      tags:
        - Educational Materials
      security:
        - bearerAuth: []
      parameters:
        - name: code
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Learning results retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean

  /api/educational-materials/pills:
    get:
      summary: Get educational pills
      description: Retrieve educational pills (multimedia content)
      tags:
        - Educational Materials
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: Pills retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean

    post:
      summary: Create educational pill
      description: Create a new educational pill
      tags:
        - Educational Materials
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - title
                - videoUrl
                - duration
                - moduleCode
              properties:
                title:
                  type: string
                description:
                  type: string
                videoUrl:
                  type: string
                duration:
                  type: integer
                moduleCode:
                  type: string
      responses:
        '201':
          description: Pill created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /api/educational-materials/pills/{id}:
    put:
      summary: Update educational pill
      description: Update an educational pill
      tags:
        - Educational Materials
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Pill updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      summary: Delete educational pill
      description: Delete an educational pill
      tags:
        - Educational Materials
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Pill deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/educational-materials/pills/{id}/visibility:
    patch:
      summary: Toggle pill visibility
      description: Toggle visibility of an educational pill
      tags:
        - Educational Materials
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Visibility toggled
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean

  /api/educational-materials/exercises:
    get:
      summary: Get educational exercises
      description: Retrieve educational exercises
      tags:
        - Educational Materials
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: Exercises retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean

    post:
      summary: Create educational exercise
      description: Create a new educational exercise
      tags:
        - Educational Materials
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - title
                - statement
                - difficulty
                - moduleCode
              properties:
                title:
                  type: string
                statement:
                  type: string
                difficulty:
                  type: string
                  enum: [beginner, intermediate, advanced]
                moduleCode:
                  type: string
      responses:
        '201':
          description: Exercise created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean

  /api/educational-materials/exercises/{id}:
    put:
      summary: Update educational exercise
      description: Update an educational exercise
      tags:
        - Educational Materials
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Exercise updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean

    delete:
      summary: Delete educational exercise
      description: Delete an educational exercise
      tags:
        - Educational Materials
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Exercise deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean

  /api/educational-materials/exercises/{id}/visibility:
    patch:
      summary: Toggle exercise visibility
      description: Toggle visibility of an educational exercise
      tags:
        - Educational Materials
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Visibility toggled
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean

  # Classroom Management Routes
  /api/classroom-management/students:
    get:
      summary: Get students with filters
      description: Retrieve students with advanced filtering
      tags:
        - Classroom Management
      security:
        - bearerAuth: []
      parameters:
        - name: subjectId
          in: query
          schema:
            type: string
        - name: classroomId
          in: query
          schema:
            type: string
        - name: status
          in: query
          schema:
            type: string
            enum: [enrolled, completed, dropped]
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: Students retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean

  /api/classroom-management/subjects/{subjectId}/exercises:
    get:
      summary: Get exercises for a subject
      description: Retrieve exercises for a specific subject
      tags:
        - Classroom Management
      security:
        - bearerAuth: []
      parameters:
        - name: subjectId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Exercises retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean

  /api/classroom-management/instructor/summary:
    get:
      summary: Get instructor summary
      description: Retrieve instructor's teaching assignments summary
      tags:
        - Classroom Management
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Summary retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean

  /api/classroom-management/classrooms/{classroomId}/students:
    get:
      summary: Get classroom students
      description: Retrieve students in a classroom with progress
      tags:
        - Classroom Management
      security:
        - bearerAuth: []
      parameters:
        - name: classroomId
          in: path
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: Students retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean

  # Student Exercises Routes
  /api/student/exercises:
    get:
      summary: Get available exercises
      description: Retrieve exercises for the student
      tags:
        - Student Exercises
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: Exercises retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /api/student/exercises/calendar:
    get:
      summary: Get exercise calendar
      description: Retrieve calendar view of exercises
      tags:
        - Student Exercises
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Calendar retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean

  /api/student/exercises/{id}:
    get:
      summary: Get exercise by ID
      description: Retrieve a specific exercise
      tags:
        - Student Exercises
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Exercise retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean

  /api/student/exercises/{id}/submit:
    post:
      summary: Submit exercise
      description: Submit an exercise solution
      tags:
        - Student Exercises
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                answer:
                  type: string
      responses:
        '200':
          description: Exercise submitted
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
        '401':
          $ref: '#/components/responses/Unauthorized'

  # Student Tasks Routes
  /api/student/tasks:
    get:
      summary: Get student tasks
      description: Retrieve student's tasks/homework
      tags:
        - Student Dashboard
      security:
        - bearerAuth: []
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum: [pending, in_progress, completed, overdue]
        - name: courseId
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Tasks retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean

  /api/student/tasks/{taskId}:
    patch:
      summary: Update task status
      description: Update status of a task
      tags:
        - Student Dashboard
      security:
        - bearerAuth: []
      parameters:
        - name: taskId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - status
              properties:
                status:
                  type: string
                  enum: [pending, in_progress, completed]
      responses:
        '200':
          description: Task updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean

  /api/student/progress:
    put:
      summary: Update course progress
      description: Update progress percentage for a course
      tags:
        - Student Dashboard
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - courseId
                - progress
              properties:
                courseId:
                  type: string
                progress:
                  type: integer
                  minimum: 0
                  maximum: 100
      responses:
        '200':
          description: Progress updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean

  # Region Admin - Centers
  /api/region-admin/centers:
    get:
      summary: Get centers in region
      description: Retrieve centers within the region admin's region
      tags:
        - Region Admin
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: Centers list
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean

  # Region Admin - Licenses
  /api/region-admin/licenses:
    get:
      summary: Get licenses in region
      description: Retrieve licenses within the region admin's region
      tags:
        - Region Admin
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: Licenses list
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean

    post:
      summary: Create license in region
      description: Create a new license within the region
      tags:
        - Region Admin
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateLicenseRequest'
      responses:
        '201':
          description: License created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean

  /api/region-admin/licenses/{id}:
    get:
      summary: Get license in region
      description: Get details of a specific license
      tags:
        - Region Admin
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: License details
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean

    patch:
      summary: Update license in region
      description: Update a license
      tags:
        - Region Admin
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateLicenseRequest'
      responses:
        '200':
          description: License updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean

    delete:
      summary: Delete license in region
      description: Delete/suspend a license
      tags:
        - Region Admin
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: License deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean

  # Region Admin - Settings
  /api/region-admin/settings:
    get:
      summary: Get region settings
      description: Retrieve settings for the region admin
      tags:
        - Region Admin
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Settings retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean

    put:
      summary: Update region settings
      description: Update settings for the region admin
      tags:
        - Region Admin
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Settings updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean

  # Region Admin - Admins
  /api/region-admin/admins/{id}:
    patch:
      summary: Update region admin
      description: Update another admin in the region
      tags:
        - Region Admin
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Admin updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean

    delete:
      summary: Delete region admin
      description: Delete another admin from the region
      tags:
        - Region Admin
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Admin deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean

  # Admin Analytics Routes
  /api/admin/analytics/users:
    get:
      summary: Get user analytics
      description: Retrieve user analytics data
      tags:
        - Admin Dashboard
      security:
        - bearerAuth: []
      responses:
        '200':
          description: User analytics
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean

  /api/admin/analytics/courses:
    get:
      summary: Get course analytics
      description: Retrieve course analytics data
      tags:
        - Admin Dashboard
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Course analytics
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean

  /api/admin/analytics/revenue:
    get:
      summary: Get revenue analytics
      description: Retrieve revenue analytics data
      tags:
        - Admin Dashboard
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Revenue analytics
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean

  /api/admin/charts/popular-courses:
    get:
      summary: Get popular courses chart
      description: Retrieve popular courses visualization data
      tags:
        - Admin Dashboard
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Chart data
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean

  /api/admin/charts/system-overview:
    get:
      summary: Get system overview chart
      description: Retrieve system overview metrics
      tags:
        - Admin Dashboard
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Overview data
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean

  /api/admin/achievements/stats:
    get:
      summary: Get achievement statistics
      description: Retrieve achievement statistics
      tags:
        - Admin Dashboard
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Achievement stats
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean

  /api/admin/top-performers:
    get:
      summary: Get top performing users
      description: Retrieve top performing students and instructors
      tags:
        - Admin Dashboard
      security:
        - bearerAuth: []
      parameters:
        - name: category
          in: query
          required: true
          schema:
            type: string
            enum: [students, instructors, courses]
        - name: metric
          in: query
          required: true
          schema:
            type: string
            enum: [completion-rate, engagement, revenue, ratings]
      responses:
        '200':
          description: Top performers
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean

  /api/admin/activity/recent:
    get:
      summary: Get recent activity
      description: Retrieve recent system activity
      tags:
        - Admin Dashboard
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: Activity data
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean

  /api/admin/logs:
    get:
      summary: Get system logs
      description: Retrieve system logs
      tags:
        - Admin Dashboard
      security:
        - bearerAuth: []
      parameters:
        - name: level
          in: query
          schema:
            type: string
            enum: [info, warn, error, debug, fatal]
        - name: limit
          in: query
          schema:
            type: integer
        - name: offset
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Logs data
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean

  /api/admin/logs/stats:
    get:
      summary: Get log statistics
      description: Retrieve log statistics
      tags:
        - Admin Dashboard
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Log stats
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean

  /api/admin/logs/export:
    get:
      summary: Export logs as CSV
      description: Export system logs in CSV format
      tags:
        - Admin Dashboard
      security:
        - bearerAuth: []
      responses:
        '200':
          description: CSV file
          content:
            text/csv:
              schema:
                type: string

                  success:
                    type: boolean

components:
  parameters:
    PageParam:
      name: page
      in: query
      description: Page number for pagination
      schema:
        type: integer
        minimum: 1
        default: 1
    LimitParam:
      name: limit
      in: query
      description: Number of items per page
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
    IDParam:
      name: id
      in: path
      required: true
      description: Resource MongoDB ObjectId
      schema:
        type: string
    PeriodParam:
      name: period
      in: query
      schema:
        type: string
        enum: [7d, 30d, 90d, 1y]
        default: 30d

  responses:
    Success:
      description: Operation successful
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: true
              message:
                type: string
                example: "Operation successful"
    BadRequest:
      description: Validation Error (Bad Request)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized (Missing or invalid token)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Forbidden (Insufficient permissions)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

  schemas:
    AuthResponse:
      type: object
      description: Successful authentication response
      properties:
        success:
          type: boolean
          example: true
          description: Operation success status
        data:
          type: object
          properties:
            user:
              $ref: '#/components/schemas/User'
            accessToken:
              type: string
              example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
              description: "JWT access token for API authorization"
            refreshToken:
              type: string
              example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
              description: "Token to refresh the access token when expired"
            tokenType:
              type: string
              example: "Bearer"
              description: "Token type (always Bearer)"
            expiresIn:
              type: integer
              example: 3600
              description: "Access token expiration time in seconds"

    User:
      type: object
      description: User profile information
      required:
        - email
        - firstName
        - lastName
        - role
      properties:
        _id:
          type: string
          example: "507f1f77bcf86cd799439011"
          description: "Unique identifier for the user (MongoDB ObjectId)"
        email:
          type: string
          format: email
          example: "student@test.com"
          description: "User's registered email address"
        firstName:
          type: string
          maxLength: 50
          example: "John"
          description: "User's first name"
        lastName:
          type: string
          maxLength: 50
          example: "Doe"
          description: "User's last name"
        name:
          type: string
          maxLength: 100
          example: "John Doe"
          description: "Full name (virtual field)"
        role:
          type: string
          enum: [superadmin, region_admin, center_manager, instructor, student]
          example: "student"
          description: "User's role and permission level"
        language:
          type: string
          maxLength: 10
          example: "en"
          description: "Preferred interface language"
        isActive:
          type: boolean
          default: true
          example: true
          description: "Account status (false = soft deleted)"
        groupId:
          type: string
          example: "507f1f77bcf86cd799439012"
          description: "ID of the group the user belongs to"
        institutionId:
          type: string
          example: "507f1f77bcf86cd799439013"
          description: "ID of the institution the user belongs to"
        regionId:
          type: string
          example: "507f1f77bcf86cd799439014"
          description: "ID of the region the user belongs to"
        createdAt:
          type: string
          format: date-time
          description: "Account creation timestamp"
        updatedAt:
          type: string
          format: date-time
          description: "Last profile update timestamp"

    CreateUserRequest:
      type: object
      description: Payload for creating a new user (Admin only)
      required:
        - email
        - firstName
        - lastName
        - role
        - password
      properties:
        email:
          type: string
          format: email
          example: "newstudent@test.com"
          description: "Unique email address"
        firstName:
          type: string
          maxLength: 50
          example: "Jane"
        lastName:
          type: string
          maxLength: 50
          example: "Smith"
        name:
          type: string
          maxLength: 100
          example: "Jane Smith"
          description: "Optional full name override"
        role:
          type: string
          enum: [superadmin, region_admin, center_manager, instructor, student]
          example: "student"
          description: "Assigned user role"
        password:
          type: string
          minLength: 6
          example: "SecurePass123"
          description: "Initial password (min 6 chars)"
        language:
          type: string
          maxLength: 10
          example: "en"
        groupId:
          type: string
          example: "507f1f77bcf86cd799439012"
          description: "Optional group assignment"
        institutionId:
          type: string
          example: "507f1f77bcf86cd799439013"
          description: "Optional institution assignment"
        regionId:
          type: string
          example: "507f1f77bcf86cd799439014"
          description: "Optional region assignment"

    UpdateUserRequest:
      type: object
      description: Payload for updating an existing user (Admin/Self)
      properties:
        firstName:
          type: string
          maxLength: 50
          description: "Update first name"
        lastName:
          type: string
          maxLength: 50
          description: "Update last name"
        name:
          type: string
          maxLength: 100
          description: "Update full name"
        language:
          type: string
          maxLength: 10
          description: "Update preferred language"
        isActive:
          type: boolean
          description: "Update active status (Admin only)"
        groupId:
          type: string
          description: "Update group assignment (Admin only)"
        institutionId:
          type: string
          description: "Update institution assignment (Admin only)"
        regionId:
          type: string
          description: "Update region assignment (Admin only)"

    Region:
      type: object
      description: Geographical region definition
      required:
        - name
        - code
      properties:
        _id:
          type: string
          description: "Unique region identifier"
        name:
          type: string
          maxLength: 100
          example: "North America"
          description: "Full name of the region"
        code:
          type: string
          maxLength: 10
          example: "NA"
          description: "Unique region code (uppercase)"
        description:
          type: string
          maxLength: 500
          description: "Optional description of the region's coverage"
        isActive:
          type: boolean
          default: true
          description: "Region active status"
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    Course:
      type: object
      description: Educational course details
      required:
        - title
        - instructorId
        - category
      properties:
        _id:
          type: string
          description: "Unique course identifier"
        title:
          type: string
          maxLength: 200
          example: "Introduction to JavaScript"
          description: "Course title"
        description:
          type: string
          maxLength: 2000
          description: "Detailed course description"
        category:
          type: string
          example: "Programming"
          description: "Course category/topic"
        instructorId:
          type: string
          example: "507f1f77bcf86cd799439011"
          description: "ID of the instructor teaching the course"
        instructor:
          $ref: '#/components/schemas/User'
        status:
          type: string
          enum: [draft, active, archived, cancelled]
          default: draft
          description: "Current lifecycle status of the course"
        price:
          type: number
          minimum: 0
          example: 99.99
          description: "Course price (0 for free courses)"
        duration:
          type: integer
          minimum: 0
          example: 480
          description: "Estimated duration in minutes"
        level:
          type: string
          enum: [beginner, intermediate, advanced]
          example: "beginner"
          description: "Target difficulty level"
        tags:
          type: array
          items:
            type: string
          description: "Search tags"
        requirements:
          type: array
          items:
            type: string
          description: "Prerequisites or requirements"
        learningObjectives:
          type: array
          items:
            type: string
          description: "What students will learn"
        modules:
          type: array
          description: "Course content structure"
          items:
            type: object
            properties:
              title:
                type: string
              lessons:
                type: array
                items:
                  type: object
                  properties:
                    title:
                      type: string
                    content:
                      type: string
                    duration:
                      type: integer
        enrollmentCount:
          type: integer
          readOnly: true
          description: "Number of students currently enrolled"
        rating:
          type: number
          minimum: 0
          maximum: 5
          readOnly: true
          description: "Average course rating (0-5)"
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    CreateCourseRequest:
      type: object
      description: Payload for creating a new course (Instructor only)
      required:
        - title
        - category
      properties:
        title:
          type: string
          maxLength: 200
          description: "Course title (unique)"
        description:
          type: string
          maxLength: 2000
          description: "Detailed description"
        category:
          type: string
          description: "Course category"
        price:
          type: number
          minimum: 0
          description: "Price in base currency"
        duration:
          type: integer
          minimum: 0
          description: "Estimated duration in minutes"
        level:
          type: string
          enum: [beginner, intermediate, advanced]
          description: "Difficulty level"
        tags:
          type: array
          items:
            type: string
        requirements:
          type: array
          items:
            type: string
        learningObjectives:
          type: array
          items:
            type: string
        modules:
          type: array
          items:
            type: object
            properties:
              title:
                type: string
              lessons:
                type: array
                items:
                  type: object
                  properties:
                    title:
                      type: string
                    content:
                      type: string
                    duration:
                      type: integer

    UpdateCourseRequest:
      type: object
      description: Payload for updating an existing course
      properties:
        title:
          type: string
          maxLength: 200
          description: "Update title"
        description:
          type: string
          maxLength: 2000
          description: "Update description"
        category:
          type: string
          description: "Update category"
        price:
          type: number
          minimum: 0
          description: "Update price"
        duration:
          type: integer
          minimum: 0
          description: "Update duration"
        level:
          type: string
          enum: [beginner, intermediate, advanced]
          description: "Update difficulty level"
        status:
          type: string
          enum: [draft, active, archived, cancelled]
          description: "Update status"
        tags:
          type: array
          items:
            type: string
          description: "Update tags"
        requirements:
          type: array
          items:
            type: string
          description: "Update requirements"
        learningObjectives:
          type: array
          items:
            type: string
          description: "Update learning objectives"
        modules:
          type: array
          items:
            type: object
            properties:
              title:
                type: string
              lessons:
                type: array
                items:
                  type: object
                  properties:
                    title:
                      type: string
                    content:
                      type: string
                    duration:
                      type: integer

    Group:
      type: object
      description: Representative model of a user group within the system.
      required:
        - name
        - code
        - domain
        - enabledPlatforms
      properties:
        _id:
          type: string
          description: Unique identifier for the group (MongoDB ObjectId)
        name:
          type: string
          description: Display name of the group
          maxLength: 100
          example: "TechCorp Group"
        code:
          type: string
          description: Unique code identifier for the group (uppercase)
          maxLength: 20
          example: "TECH001"
        domain:
          type: string
          description: Unique email domain associated with the group
          maxLength: 100
          example: "techcorp.com"
        enabledPlatforms:
          type: array
          description: List of platforms this group has access to
          items:
            type: string
            enum: [bolsa, tms, ecmr, transcend]
        isActive:
          type: boolean
          description: Flag indicating if the group is active. False indicates soft-deletion.
          default: true
        createdAt:
          type: string
          description: Timestamp of creation
          format: date-time
        updatedAt:
          type: string
          description: Timestamp of last update
          format: date-time

    CreateGroupRequest:
      type: object
      description: Payload for creating a new group.
      required:
        - name
        - code
        - domain
        - enabledPlatforms
      properties:
        name:
          type: string
          description: Display name of the group
          maxLength: 100
          example: "TechCorp Group"
        code:
          type: string
          description: Unique code identifier for the group (must be unique)
          maxLength: 20
          example: "TECH001"
        domain:
          type: string
          description: Email domain associated with the group (must be unique)
          maxLength: 100
          example: "techcorp.com"
        enabledPlatforms:
          type: array
          description: List of platforms to enable for this group
          items:
            type: string
            enum: [bolsa, tms, ecmr, transcend]

    UpdateGroupRequest:
      type: object
      description: Payload for updating an existing group. logic will only update provided fields.
      properties:
        name:
          type: string
          description: New display name for the group
          maxLength: 100
        enabledPlatforms:
          type: array
          description: New list of enabled platforms (overwrites existing list if provided)
          items:
            type: string
            enum: [bolsa, tms, ecmr, transcend]
        isActive:
          type: boolean
          description: Set to false to soft-delete, or true to reactivate

    Institution:
      type: object
      required:
        - name
        - code
      properties:
        _id:
          type: string
        name:
          type: string
          maxLength: 200
          example: "Harvard University"
        code:
          type: string
          maxLength: 20
          example: "HARVARD"
        description:
          type: string
          maxLength: 1000
        type:
          type: string
          enum: [university, college, school, training-center]
          example: "university"
        regionId:
          type: string
        region:
          $ref: '#/components/schemas/Region'
        address:
          type: object
          properties:
            street:
              type: string
            city:
              type: string
            state:
              type: string
            zipCode:
              type: string
            country:
              type: string
        contact:
          type: object
          properties:
            email:
              type: string
              format: email
            phone:
              type: string
            website:
              type: string
              format: uri
        isActive:
          type: boolean
          default: true
        studentCount:
          type: integer
          readOnly: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    InstitutionPlatform:
      type: object
      description: Platform configuration for an institution
      properties:
        _id:
          type: string
          example: "507f1f77bcf86cd799439011"
        institutionId:
          type: string
          example: "507f1f77bcf86cd799439012"
        platform:
          type: string
          enum: [bolsa, tms, ecmr, transcend, truckerapp]
          example: "bolsa"
        isEnabled:
          type: boolean
          example: true
        validFrom:
          type: string
          format: date
          nullable: true
          example: "2025-01-01"
        validUntil:
          type: string
          format: date
          nullable: true
          example: "2025-12-31"
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    InstitutionPlatformUpdate:
      type: object
      description: Update payload for institution platform
      required:
        - platform
      properties:
        platform:
          type: string
          enum: [bolsa, tms, ecmr, transcend, truckerapp]
          example: "bolsa"
        isEnabled:
          type: boolean
          description: Whether the platform is enabled for this institution
          example: true
        validFrom:
          type: string
          format: date
          description: Start date for platform access
          example: "2025-01-01"
        validUntil:
          type: string
          format: date
          description: End date for platform access
          example: "2025-12-31"

    CreateInstitutionRequest:
      type: object
      required:
        - name
        - code
        - type
      properties:
        name:
          type: string
          maxLength: 200
        code:
          type: string
          maxLength: 20
        description:
          type: string
          maxLength: 1000
        type:
          type: string
          enum: [university, college, school, training-center]
        regionId:
          type: string
        address:
          type: object
          properties:
            street:
              type: string
            city:
              type: string
            state:
              type: string
            zipCode:
              type: string
            country:
              type: string
        contact:
          type: object
          properties:
            email:
              type: string
              format: email
            phone:
              type: string
            website:
              type: string
              format: uri

    UpdateInstitutionRequest:
      type: object
      properties:
        name:
          type: string
          maxLength: 200
        code:
          type: string
          maxLength: 20
        description:
          type: string
          maxLength: 1000
        type:
          type: string
          enum: [university, college, school, training-center]
        regionId:
          type: string
        address:
          type: object
          properties:
            street:
              type: string
            city:
              type: string
            state:
              type: string
            zipCode:
              type: string
            country:
              type: string
        contact:
          type: object
          properties:
            email:
              type: string
              format: email
            phone:
              type: string
            website:
              type: string
              format: uri
        isActive:
          type: boolean

    Exercise:
      type: object
      description: Educational exercise with questions and learning materials
      properties:
        _id:
          type: string
          description: Unique exercise identifier
        title:
          type: string
          description: Exercise title
        statement:
          type: string
          description: Exercise statement/question
        possibleAnswers:
          type: string
          description: Possible answers or options
        teacherExplanation:
          type: string
          description: Teacher's explanation of the correct answer
        studentExplanation:
          type: string
          description: Explanation shown to students
        moduleCode:
          type: string
          description: Associated module code
        raNumbers:
          type: array
          items:
            type: integer
          description: Learning result numbers
        estimatedHours:
          type: integer
          description: Estimated hours to complete
        difficulty:
          type: string
          enum: [basic, intermediate, advanced]
          description: Difficulty level
        platform:
          type: string
          description: Associated platform
        isVisible:
          type: boolean
          description: Visibility status
        regionId:
          type: string
          description: Associated region ID
        createdBy:
          $ref: '#/components/schemas/User'
        tags:
          type: array
          items:
            type: string
          description: Exercise tags
        studentVideoUrl:
          type: string
          description: Student video URL
        teacherVideoUrl:
          type: string
          description: Teacher video URL
        videoThumbnail:
          type: string
          description: Video thumbnail URL
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    CreateExerciseRequest:
      type: object
      required:
        - title
        - statement
        - estimatedHours
        - difficulty
      properties:
        title:
          type: string
          description: Exercise title
        statement:
          type: string
          description: Exercise statement/question
        possibleAnswers:
          type: string
          description: Possible answers or options
        teacherExplanation:
          type: string
          description: Teacher's explanation of the correct answer
        studentExplanation:
          type: string
          description: Explanation shown to students
        moduleCode:
          type: string
          description: Associated module code
        raNumbers:
          type: array
          items:
            type: integer
          description: Learning result numbers
        estimatedHours:
          type: integer
          minimum: 1
          description: Estimated hours to complete
        difficulty:
          type: string
          enum: [basic, intermediate, advanced]
          description: Difficulty level
        platform:
          type: string
          description: Associated platform
        isVisible:
          type: boolean
          default: true
          description: Visibility status
        tags:
          type: array
          items:
            type: string
          description: Exercise tags
        studentVideoUrl:
          type: string
          description: Student video URL
        teacherVideoUrl:
          type: string
          description: Teacher video URL
        videoThumbnail:
          type: string
          description: Video thumbnail URL

    UpdateExerciseRequest:
      type: object
      properties:
        title:
          type: string
          description: Exercise title
        statement:
          type: string
          description: Exercise statement/question
        possibleAnswers:
          type: string
          description: Possible answers or options
        teacherExplanation:
          type: string
          description: Teacher's explanation of the correct answer
        studentExplanation:
          type: string
          description: Explanation shown to students
        moduleCode:
          type: string
          description: Associated module code
        raNumbers:
          type: array
          items:
            type: integer
          description: Learning result numbers
        estimatedHours:
          type: integer
          minimum: 1
          description: Estimated hours to complete
        difficulty:
          type: string
          enum: [basic, intermediate, advanced]
          description: Difficulty level
        platform:
          type: string
          description: Associated platform
        tags:
          type: array
          items:
            type: string
          description: Exercise tags
        studentVideoUrl:
          type: string
          description: Student video URL
        teacherVideoUrl:
          type: string
          description: Teacher video URL
        videoThumbnail:
          type: string
          description: Video thumbnail URL

    License:
      type: object
      description: |
        Platform license that defines access windows and user limits for educational centers.
        Each license is tied to one institution and one platform (bolsa, tms, ecmr, transcend).
      properties:
        _id:
          type: string
          description: Unique license identifier
          example: "507f1f77bcf86cd799439012"
        institutionId:
          type: object
          description: The educational center this license belongs to
          properties:
            _id:
              type: string
            name:
              type: string
            code:
              type: string
        platform:
          type: string
          enum: [bolsa, tms, ecmr, transcend]
          description: |
            Platform identifier:
            - `bolsa`: Bolsa de Carga (Load Exchange) - Freight matching platform
            - `tms`: Transport Management System - Fleet and logistics management
            - `ecmr`: Electronic CMR - Digital consignment notes
            - `transcend`: Transcend Platform - Advanced logistics tools
          example: "bolsa"
        startDate:
          type: string
          format: date
          description: License activation date (ISO 8601)
          example: "2025-01-01"
        endDate:
          type: string
          format: date
          description: License expiration date (ISO 8601)
          example: "2025-12-31"
        maxUsers:
          type: integer
          minimum: 1
          maximum: 10000
          description: Maximum number of concurrent users allowed on this platform
          example: 50
        activeUsers:
          type: integer
          description: Current number of active users using the license
          example: 32
        status:
          type: string
          enum: [active, expired, pending, suspended]
          description: |
            License status:
            - `active`: Currently usable (current date is between startDate and endDate)
            - `expired`: End date has passed
            - `pending`: Start date has not yet been reached
            - `suspended`: Temporarily disabled by administrator
          example: "active"
        daysRemaining:
          type: integer
          description: Number of days until license expires (negative if already expired)
          example: 180
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    Subject:
      type: object
      description: Educational subject/course subject details
      required:
        - name
        - code
        - cycle
      properties:
        _id:
          type: string
          description: Unique subject identifier (MongoDB ObjectId)
          example: "507f1f77bcf86cd799439011"
        name:
          type: string
          minLength: 2
          maxLength: 100
          description: Subject name
          example: "Mathematics"
        code:
          type: string
          minLength: 2
          maxLength: 10
          pattern: ^[A-Z0-9_-]+$
          description: Unique subject code (uppercase, alphanumeric with underscores/hyphens)
          example: "MATH101"
        description:
          type: string
          maxLength: 500
          description: Optional subject description
          example: "Introduction to basic mathematics concepts"
        cycle:
          type: string
          enum: [logistica, comercio, both]
          description: |
            Cycle the subject belongs to:
            - `logistica`: Logistics cycle
            - `comercio`: Commerce cycle
            - `both`: Both cycles
          example: "logistica"
        regionId:
          type: string
          description: Region ID (if subject is at region level)
          example: "507f1f77bcf86cd799439012"
        institutionId:
          type: string
          description: Institution ID (if subject is at institution level)
          example: "507f1f77bcf86cd799439013"
        isActive:
          type: boolean
          default: true
          description: Subject active status
          example: true
        createdAt:
          type: string
          format: date-time
          description: Creation timestamp
        updatedAt:
          type: string
          format: date-time
          description: Last update timestamp

    CreateSubjectRequest:
      type: object
      description: Payload for creating a new subject
      required:
        - name
        - code
        - cycle
      properties:
        name:
          type: string
          minLength: 2
          maxLength: 100
          description: Subject name
          example: "Mathematics"
        code:
          type: string
          minLength: 2
          maxLength: 10
          pattern: ^[A-Z0-9_-]+$
          description: Unique subject code (uppercase, alphanumeric with underscores/hyphens)
          example: "MATH101"
        description:
          type: string
          maxLength: 500
          description: Optional subject description
          example: "Introduction to basic mathematics concepts"
        cycle:
          type: string
          enum: [logistica, comercio, both]
          description: |
            Cycle the subject belongs to:
            - `logistica`: Logistics cycle
            - `comercio`: Commerce cycle
            - `both`: Both cycles
          example: "logistica"
        regionId:
          type: string
          description: Region ID (if subject is at region level)
          example: "507f1f77bcf86cd799439012"
        institutionId:
          type: string
          description: Institution ID (if subject is at institution level)
          example: "507f1f77bcf86cd799439013"
        isActive:
          type: boolean
          default: true
          description: Subject active status
          example: true

    UpdateSubjectRequest:
      type: object
      description: Payload for updating an existing subject
      properties:
        name:
          type: string
          minLength: 2
          maxLength: 100
          description: Update subject name
          example: "Advanced Mathematics"
        code:
          type: string
          minLength: 2
          maxLength: 10
          pattern: ^[A-Z0-9_-]+$
          description: Update subject code (must be unique)
          example: "MATH201"
        description:
          type: string
          maxLength: 500
          description: Update subject description
          example: "Advanced mathematics concepts including calculus and algebra"
        cycle:
          type: string
          enum: [logistica, comercio, both]
          description: Update subject cycle
          example: "both"
        regionId:
          type: string
          description: Update region ID (if subject is at region level)
          example: "507f1f77bcf86cd799439012"
        institutionId:
          type: string
          description: Update institution ID (if subject is at institution level)
          example: "507f1f77bcf86cd799439013"
        isActive:
          type: boolean
          description: Update subject active status
          example: false

    CreateLicenseRequest:
      type: object
      required:
        - institutionId
        - platform
        - startDate
        - endDate
      properties:
        institutionId:
          type: string
          description: Target institution/center ID
          example: "507f1f77bcf86cd799439011"
        platform:
          type: string
          enum: [bolsa, tms, ecmr, transcend]
        startDate:
          type: string
          format: date
          example: "2025-01-01"
        endDate:
          type: string
          format: date
          example: "2025-12-31"
        maxUsers:
          type: integer
          minimum: 1
          maximum: 10000
          default: 50
          description: Maximum concurrent users allowed
          example: 50

    UpdateLicenseRequest:
      type: object
      properties:
        maxUsers:
          type: integer
          minimum: 1
          maximum: 10000
        startDate:
          type: string
          format: date
        endDate:
          type: string
          format: date
        status:
          type: string
          enum: [active, expired, pending, suspended]

    LicenseTimeline:
      type: object
      description: License data formatted for EPG-style timeline visualization
      properties:
        institution:
          type: object
          properties:
            _id:
              type: string
            name:
              type: string
            code:
              type: string
        licenses:
          type: array
          items:
            $ref: '#/components/schemas/License'

    Pagination:
      type: object
      properties:
        page:
          type: integer
          example: 1
        limit:
          type: integer
          example: 20
        total:
          type: integer
          example: 150
        totalPages:
          type: integer
          example: 8
        hasNext:
          type: boolean
          example: true
        hasPrev:
          type: boolean
          example: false

    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: string
              example: "VALIDATION_ERROR"
            message:
              type: string
              example: "Invalid input data"
            details:
              type: object
              description: Additional error details

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  x-role-hierarchy:
    superadmin:
      level: 1
      label: "Super Administrator"
      description: |
        Full platform access. Can manage all regions, institutions, users, and settings.
        This role is typically held by platform operators and support staff who need
        complete visibility across all educational institutions.
      permissions:
        - "create:region"
        - "delete:region"
        - "create:group"
        - "manage:all-users"
        - "manage:licenses"
        - "view:global-analytics"
      dataScope: "All data across all regions and institutions"
    region_admin:
      level: 2
      label: "Regional Administrator"
      description: |
        Manages ONE geographic region. Can create center_managers, instructors, and students
        within their assigned region. Cannot access data from other regions.
        
        Use Cases:
        - Manage educational centers in a province/state
        - Assign directors to centers
        - View regional usage statistics
        - Manage license timelines for centers
      permissions:
        - "manage:region-centers"
        - "manage:region-users"
        - "create:center_manager"
        - "create:instructor"
        - "create:student"
        - "view:region-analytics"
        - "view:region-licenses"
      dataScope: "Only data within assigned regionId"
      constraints:
        - "Cannot access other regions"
        - "Cannot create superadmin or other region_admin users"
        - "Can only manage users in their region"
    center_manager:
      level: 3
      label: "Center Director"
      description: |
        Manages ONE educational center/institution. Can create instructors and students.
        Views center-specific statistics and manages classroom assignments.
      permissions:
        - "manage:center-teachers"
        - "manage:center-students"
        - "create:instructor"
        - "create:student"
        - "view:center-stats"
        - "view:center-licenses"
      dataScope: "Only data within assigned institutionId"
    instructor:
      level: 4
      label: "Instructor/Professor"
      description: |
        Creates and manages classrooms and courses. Can add students to their classrooms
        and track student progress.
      permissions:
        - "manage:own-classrooms"
        - "manage:own-courses"
        - "create:students"
        - "view:student-progress"
      dataScope: "Own classrooms and enrolled students only"
    student:
      level: 5
      label: "Student"
      description: |
        End user. Views enrolled courses, personal progress, and educational content.
      permissions:
        - "view:own-courses"
        - "view:own-progress"
        - "submit:assignments"
      dataScope: "Read-only access to own data"