openapi: 3.0.3
info:
  title: Smart Academic Hub API
  description: |
    Multi-tenant SaaS platform API for education businesses.
    
    ## Authentication
    All endpoints (except login/register) require authentication using Laravel Sanctum.
    Include the token in the Authorization header:
    ```
    Authorization: Bearer {token}
    ```
    
    ## Multi-tenancy
    Most endpoints require an `X-Academy-ID` header to specify which academy context to operate in.
  version: 1.0.0
  contact:
    name: Smart Academic Hub Support
    url: https://smartacademichub.com/support
    email: support@smartacademichub.com
  license:
    name: Proprietary
    url: https://smartacademichub.com/license

servers:
  - url: https://smartacademichub.com/api/v1
    description: Production server
  - url: https://staging.smartacademichub.com/api/v1
    description: Staging server
  - url: http://localhost:5000/api/v1
    description: Local development

tags:
  - name: Authentication
    description: User authentication and registration
  - name: Academies
    description: Academy management endpoints
  - name: Students
    description: Student management endpoints
  - name: Parents
    description: Parent management endpoints
  - name: Staff
    description: Staff management endpoints
  - name: Courses
    description: Course management endpoints
  - name: Batches
    description: Batch/schedule management for courses
  - name: Enrollments
    description: Enrollment management endpoints
  - name: Attendance
    description: Attendance tracking endpoints
  - name: Fees
    description: Fee management endpoints

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Token
      description: Laravel Sanctum API token
  
  parameters:
    AcademyIdHeader:
      in: header
      name: X-Academy-ID
      required: true
      schema:
        type: string
        format: uuid
      description: UUID of the academy context

  schemas:
    Error:
      type: object
      properties:
        message:
          type: string
          example: The given data was invalid.
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
    
    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        email:
          type: string
          format: email
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    
    Academy:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        slug:
          type: string
        type:
          type: string
          enum: [tuition, coaching, swimming, karate, chess, music, dance, yoga, coding, other]
        description:
          type: string
        email:
          type: string
          format: email
        phone:
          type: string
        address:
          type: string
        city:
          type: string
        state:
          type: string
        country:
          type: string
        postal_code:
          type: string
        website:
          type: string
        logo_url:
          type: string
        status:
          type: string
          enum: [active, inactive, suspended]
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    
    Batch:
      type: object
      properties:
        id:
          type: string
          format: uuid
        course_id:
          type: string
          format: uuid
        academy_id:
          type: string
          format: uuid
        name:
          type: string
          example: Morning Batch
        code:
          type: string
          example: BAT-ABC12345
        start_date:
          type: string
          format: date
          example: "2024-01-15"
        end_date:
          type: string
          format: date
          example: "2024-12-15"
        start_time:
          type: string
          format: time
          example: "09:00:00"
        end_time:
          type: string
          format: time
          example: "11:00:00"
        days_of_week:
          type: array
          items:
            type: string
            enum: [monday, tuesday, wednesday, thursday, friday, saturday, sunday]
          example: ["monday", "wednesday", "friday"]
        max_students:
          type: integer
          example: 30
        instructor_id:
          type: string
          format: uuid
          nullable: true
        classroom:
          type: string
          example: Room A-101
        status:
          type: string
          enum: [upcoming, ongoing, completed, cancelled]
          example: ongoing
        notes:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        course:
          type: object
          description: Related course (when included)
        instructor:
          type: object
          description: Assigned instructor (when included)
        available_seats:
          type: integer
          description: Number of available seats

paths:
  /auth/register:
    post:
      tags:
        - Authentication
      summary: Register a new user
      description: Create a new user account
      operationId: register
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - email
                - password
                - password_confirmation
              properties:
                name:
                  type: string
                  example: John Doe
                email:
                  type: string
                  format: email
                  example: john@example.com
                password:
                  type: string
                  format: password
                  minLength: 8
                  example: password123
                password_confirmation:
                  type: string
                  format: password
                  example: password123
      responses:
        '201':
          description: User registered successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    $ref: '#/components/schemas/User'
                  token:
                    type: string
                    example: 1|abcdef1234567890
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /auth/login:
    post:
      tags:
        - Authentication
      summary: Login user
      description: Authenticate user and return access token
      operationId: login
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - password
              properties:
                email:
                  type: string
                  format: email
                  example: john@example.com
                password:
                  type: string
                  format: password
                  example: password123
      responses:
        '200':
          description: Login successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    $ref: '#/components/schemas/User'
                  token:
                    type: string
                    example: 2|xyz9876543210
        '401':
          description: Invalid credentials
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Invalid credentials

  /auth/logout:
    post:
      tags:
        - Authentication
      summary: Logout user
      description: Revoke current access token
      operationId: logout
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Logout successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Logged out successfully
        '401':
          description: Unauthorized

  /academies:
    get:
      tags:
        - Academies
      summary: List academies
      description: Get list of academies user has access to
      operationId: listAcademies
      security:
        - bearerAuth: []
      parameters:
        - in: query
          name: page
          schema:
            type: integer
            default: 1
        - in: query
          name: per_page
          schema:
            type: integer
            default: 15
        - in: query
          name: search
          schema:
            type: string
        - in: query
          name: type
          schema:
            type: string
            enum: [tuition, coaching, swimming, karate, chess, music, dance, yoga, coding, other]
      responses:
        '200':
          description: List of academies
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Academy'
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                      from:
                        type: integer
                      last_page:
                        type: integer
                      per_page:
                        type: integer
                      to:
                        type: integer
                      total:
                        type: integer


  /batches:
    get:
      tags:
        - Batches
      summary: List batches
      description: Get paginated list of batches for academy
      operationId: listBatches
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/AcademyIdHeader'
        - in: query
          name: page
          schema:
            type: integer
            default: 1
        - in: query
          name: per_page
          schema:
            type: integer
            default: 15
        - in: query
          name: search
          schema:
            type: string
          description: Search by batch name or code
        - in: query
          name: course_id
          schema:
            type: string
            format: uuid
          description: Filter by course
        - in: query
          name: status
          schema:
            type: string
            enum: [upcoming, ongoing, completed, cancelled]
        - in: query
          name: instructor_id
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: List of batches
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Batch'
        '401':
          description: Unauthorized
    
    post:
      tags:
        - Batches
      summary: Create batch
      description: Create a new batch for a course
      operationId: createBatch
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/AcademyIdHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - course_id
                - name
                - start_date
                - end_date
                - start_time
                - end_time
                - days_of_week
              properties:
                course_id:
                  type: string
                  format: uuid
                name:
                  type: string
                  example: Morning Batch
                start_date:
                  type: string
                  format: date
                end_date:
                  type: string
                  format: date
                start_time:
                  type: string
                  format: time
                  example: "09:00:00"
                end_time:
                  type: string
                  format: time
                  example: "11:00:00"
                days_of_week:
                  type: array
                  items:
                    type: string
                    enum: [monday, tuesday, wednesday, thursday, friday, saturday, sunday]
                max_students:
                  type: integer
                instructor_id:
                  type: string
                  format: uuid
                  nullable: true
                classroom:
                  type: string
                notes:
                  type: string
      responses:
        '201':
          description: Batch created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Batch'
        '422':
          description: Validation error

  /batches/{id}:
    get:
      tags:
        - Batches
      summary: Get batch details
      description: Retrieve details of a specific batch
      operationId: getBatch
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/AcademyIdHeader'
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Batch details
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Batch'
        '404':
          description: Batch not found
    
    put:
      tags:
        - Batches
      summary: Update batch
      description: Update an existing batch
      operationId: updateBatch
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/AcademyIdHeader'
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                start_date:
                  type: string
                  format: date
                end_date:
                  type: string
                  format: date
                start_time:
                  type: string
                  format: time
                end_time:
                  type: string
                  format: time
                days_of_week:
                  type: array
                  items:
                    type: string
                max_students:
                  type: integer
                instructor_id:
                  type: string
                  format: uuid
                classroom:
                  type: string
                status:
                  type: string
                  enum: [upcoming, ongoing, completed, cancelled]
                notes:
                  type: string
      responses:
        '200':
          description: Batch updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Batch'
        '404':
          description: Batch not found
        '422':
          description: Validation error
    
    delete:
      tags:
        - Batches
      summary: Delete batch
      description: Soft delete a batch
      operationId: deleteBatch
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/AcademyIdHeader'
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Batch deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Batch deleted successfully
        '404':
          description: Batch not found

  /courses/{courseId}/batches:
    get:
      tags:
        - Batches
      summary: List course batches
      description: Get all batches for a specific course
      operationId: listCourseBatches
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/AcademyIdHeader'
        - in: path
          name: courseId
          required: true
          schema:
            type: string
            format: uuid
        - in: query
          name: status
          schema:
            type: string
            enum: [upcoming, ongoing, completed, cancelled]
      responses:
        '200':
          description: List of course batches
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Batch'
        '404':
          description: Course not found