openapi: 3.0.3
info:
  title: Al Rahma Sunday School API
  version: 1.0.0
  description: |
    Unified API specification for all system modules.
    All routes require JWT Bearer authentication (`Authorization: Bearer <token>`).

servers:
  - url: https://your-domain.com/api/v1
    description: Production
  - url: http://localhost:8080/api/v1
    description: Local

security:
  - bearerAuth: []

tags:
  - name: Assignments
  - name: Attendance
  - name: Attendance Tracking
  - name: Authorized Users
  - name: Authentication
  - name: Broadcast Email
  - name: Calendar
  - name: Classes
  - name: Class Preparation
  - name: Communications
  - name: Homework
  - name: Quizzes
  - name: Projects
  - name: Payments
  - name: Invoices
  - name: Expenses
  - name: Midterms
  - name: Finals
  - name: Score Comments
  - name: Scores
  - name: Messages
  - name: Notifications
  - name: Extra Charges
  - name: Discounts
  - name: Teachers
  - name: Staff
  - name: Users
  - name: Financial
  - name: Purchase Orders
  - name: Late Slip Logs
  - name: Homework Tracking
  - name: Teachers
  - name: Parents
  - name: Admin Dashboard
  - name: Absence
  - name: Search
  - name: Enrollment
  - name: Profiles
  - name: Score Predictor
  - name: Families
  - name: Emergency Contacts
  - name: Suppliers
  - name: Roles
  - name: Permissions

paths:
  /login:
    $ref: './auth_controller.yaml#/paths/~1login'
  /register:
    $ref: './auth_controller.yaml#/paths/~1register'
  /assignments:
    $ref: './assignment_controller.yaml#/paths/~1assignments'
  /assignments/{id}:
    $ref: './assignment_controller.yaml#/paths/~1assignments~1{id}'
  /assignments/student/{id}:
    $ref: './assignment_controller.yaml#/paths/~1assignments~1student~1{id}'

  /attendance:
    $ref: './attendance_controller.yaml#/paths/~1attendance'
  /attendance/{id}:
    $ref: './attendance_controller.yaml#/paths/~1attendance~1{id}'
  /attendance/student/{id}:
    $ref: './attendance_controller.yaml#/paths/~1attendance~1student~1{id}'
  /attendance/class/{class_section_id}:
    $ref: './attendance_controller.yaml#/paths/~1attendance~1class~1{class_section_id}'
  /attendance/class/{class_section_id}/record:
    $ref: './attendance_controller.yaml#/paths/~1attendance~1class~1{class_section_id}~1record'

  /attendance-tracking/record:
    $ref: './attendance_tracking_controller.yaml#/paths/~1attendance-tracking~1record'
  /attendance-tracking/violations:
    $ref: './attendance_tracking_controller.yaml#/paths/~1attendance-tracking~1violations'
  /attendance-tracking/student/{id}:
    $ref: './attendance_tracking_controller.yaml#/paths/~1attendance-tracking~1student~1{id}'

  /authorized-users:
    $ref: './authorized_users_controller.yaml#/paths/~1authorized-users'
  /authorized-users/{id}:
    $ref: './authorized_users_controller.yaml#/paths/~1authorized-users~1{id}'

  /broadcast-email/send:
    $ref: './broadcast_email_controller.yaml#/paths/~1broadcast-email~1send'
  /broadcast-email/parents:
    $ref: './broadcast_email_controller.yaml#/paths/~1broadcast-email~1parents'

  /calendar:
    $ref: './calendar_controller.yaml#/paths/~1calendar'
  /calendar/{id}:
    $ref: './calendar_controller.yaml#/paths/~1calendar~1{id}'

  /classes:
    $ref: './class_controller.yaml#/paths/~1classes'
  /classes/{id}:
    $ref: './class_controller.yaml#/paths/~1classes~1{id}'
  /classes/{id}/students:
    $ref: './class_controller.yaml#/paths/~1classes~1{id}~1students'

  /class-preparation:
    $ref: './class_preparation_controller.yaml#/paths/~1class-preparation'
  /class-preparation/{class_id}:
    $ref: './class_preparation_controller.yaml#/paths/~1class-preparation~1{class_id}'
  /class-preparation/calculate:
    $ref: './class_preparation_controller.yaml#/paths/~1class-preparation~1calculate'

  /homework:
    $ref: './homework_controller.yaml#/paths/~1homework'
  /homework/{id}:
    $ref: './homework_controller.yaml#/paths/~1homework~1{id}'
  /homework/student/{id}:
    $ref: './homework_controller.yaml#/paths/~1homework~1student~1{id}'

  /quizzes:
    $ref: './quiz_controller.yaml#/paths/~1quizzes'
  /quizzes/{id}:
    $ref: './quiz_controller.yaml#/paths/~1quizzes~1{id}'
  /quizzes/student/{id}:
    $ref: './quiz_controller.yaml#/paths/~1quizzes~1student~1{id}'

  /projects:
    $ref: './project_controller.yaml#/paths/~1projects'
  /projects/{id}:
    $ref: './project_controller.yaml#/paths/~1projects~1{id}'
  /projects/student/{id}:
    $ref: './project_controller.yaml#/paths/~1projects~1student~1{id}'

  /payments:
    $ref: './payment_controller.yaml#/paths/~1payments'
  /payments/{id}:
    $ref: './payment_controller.yaml#/paths/~1payments~1{id}'
  /payments/parent/{id}:
    $ref: './payment_controller.yaml#/paths/~1payments~1parent~1{id}'

  /invoices:
    $ref: './invoice_controller.yaml#/paths/~1invoices'
  /invoices/{id}:
    $ref: './invoice_controller.yaml#/paths/~1invoices~1{id}'
  /invoices/parent/{id}:
    $ref: './invoice_controller.yaml#/paths/~1invoices~1parent~1{id}'

  /expenses:
    $ref: './expense_controller.yaml#/paths/~1expenses'
  /expenses/{id}:
    $ref: './expense_controller.yaml#/paths/~1expenses~1{id}'

  /midterms:
    $ref: './midterm_controller.yaml#/paths/~1midterms'
  /midterms/student/{id}:
    $ref: './midterm_controller.yaml#/paths/~1midterms~1student~1{id}'
  /midterms/{id}:
    $ref: './midterm_controller.yaml#/paths/~1midterms~1{id}'

  /finals:
    $ref: './final_controller.yaml#/paths/~1finals'
  /finals/student/{id}:
    $ref: './final_controller.yaml#/paths/~1finals~1student~1{id}'
  /finals/{id}:
    $ref: './final_controller.yaml#/paths/~1finals~1{id}'

  /score-comments:
    $ref: './score_comment_controller.yaml#/paths/~1score-comments'
  /score-comments/student/{id}:
    $ref: './score_comment_controller.yaml#/paths/~1score-comments~1student~1{id}'
  /score-comments/{id}:
    $ref: './score_comment_controller.yaml#/paths/~1score-comments~1{id}'

  /scores:
    $ref: './score_controller.yaml#/paths/~1scores'
  /scores/{id}:
    $ref: './score_controller.yaml#/paths/~1scores~1{id}'
  /scores/student/{id}:
    $ref: './score_controller.yaml#/paths/~1scores~1student~1{id}'
  /scores/recalculate:
    $ref: './score_controller.yaml#/paths/~1scores~1recalculate'

  /messages:
    $ref: './message_controller.yaml#/paths/~1messages'
  /messages/{id}:
    $ref: './message_controller.yaml#/paths/~1messages~1{id}'

  /notifications:
    $ref: './notification_controller.yaml#/paths/~1notifications'
  /notifications/{id}:
    $ref: './notification_controller.yaml#/paths/~1notifications~1{id}'
  /notifications/{id}/read:
    $ref: './notification_controller.yaml#/paths/~1notifications~1{id}~1read'

  /extra-charges:
    $ref: './extra_charges_controller.yaml#/paths/~1extra-charges'
  /extra-charges/{id}:
    $ref: './extra_charges_controller.yaml#/paths/~1extra-charges~1{id}'
  /extra-charges/{id}/apply:
    $ref: './extra_charges_controller.yaml#/paths/~1extra-charges~1{id}~1apply'
  /extra-charges/parents:
    $ref: './extra_charges_controller.yaml#/paths/~1extra-charges~1parents'

  /discounts:
    $ref: './discount_controller.yaml#/paths/~1discounts'
  /discounts/code/{code}:
    $ref: './discount_controller.yaml#/paths/~1discounts~1code~1{code}'
  /discounts/apply:
    $ref: './discount_controller.yaml#/paths/~1discounts~1apply'

  # Teacher API
  /teachers:
    $ref: './teacher_controller.yaml#/paths/~1teachers'
  /teachers/{id}:
    $ref: './teacher_controller.yaml#/paths/~1teachers~1{id}'
  /teachers/{id}/classes:
    $ref: './teacher_controller.yaml#/paths/~1teachers~1{id}~1classes'

  # Staff API
  /staff:
    $ref: './staff_controller.yaml#/paths/~1staff'
  /staff/{id}:
    $ref: './staff_controller.yaml#/paths/~1staff~1{id}'

  # User API
  /profile:
    $ref: './user_controller.yaml#/paths/~1profile'

  # Financial API
  /financial/report:
    $ref: './financial_controller.yaml#/paths/~1financial~1report'
  /financial/unpaid-parents:
    $ref: './financial_controller.yaml#/paths/~1financial~1unpaid-parents'

  # Purchase Orders API
  /purchase-orders:
    $ref: './purchase_order_controller.yaml#/paths/~1purchase-orders'
  /purchase-orders/{id}:
    $ref: './purchase_order_controller.yaml#/paths/~1purchase-orders~1{id}'

  # Late Slip Logs API
  /late-slip-logs:
    $ref: './late_slip_logs_controller.yaml#/paths/~1late-slip-logs'
  /late-slip-logs/{id}:
    $ref: './late_slip_logs_controller.yaml#/paths/~1late-slip-logs~1{id}'

  # Homework Tracking API
  /homework-tracking:
    $ref: './homework_tracking_controller.yaml#/paths/~1homework-tracking'

  /suppliers:
    $ref: './supplier_controller.yaml#/paths/~1suppliers'
  /suppliers/{id}:
    $ref: './supplier_controller.yaml#/paths/~1suppliers~1{id}'

  # Parent API (referenced from parent controller spec)
  /parents:
    $ref: '../openapi_parent_controller.yaml#/paths/~1parents'
  /parents/{id}:
    $ref: '../openapi_parent_controller.yaml#/paths/~1parents~1{id}'
  /parents/{id}/profile:
    $ref: '../openapi_parent_controller.yaml#/paths/~1parents~1{id}~1profile'
  /parents/{id}/students:
    $ref: '../openapi_parent_controller.yaml#/paths/~1parents~1{id}~1students'
  /parents/{id}/students/{studentId}:
    $ref: '../openapi_parent_controller.yaml#/paths/~1parents~1{id}~1students~1{studentId}'
  /parents/{id}/attendance:
    $ref: '../openapi_parent_controller.yaml#/paths/~1parents~1{id}~1attendance'
  /parents/{id}/payments:
    $ref: '../openapi_parent_controller.yaml#/paths/~1parents~1{id}~1payments'
  /parents/{id}/enrollments:
    $ref: '../openapi_parent_controller.yaml#/paths/~1parents~1{id}~1enrollments'
  /parents/{id}/enroll-classes:
    $ref: '../openapi_parent_controller.yaml#/paths/~1parents~1{id}~1enroll-classes'
  /parents/{id}/emergency-contacts:
    $ref: '../openapi_parent_controller.yaml#/paths/~1parents~1{id}~1emergency-contacts'
  /parents/{id}/authorized-users:
    $ref: '../openapi_parent_controller.yaml#/paths/~1parents~1{id}~1authorized-users'
  /parents/{id}/events:
    $ref: '../openapi_parent_controller.yaml#/paths/~1parents~1{id}~1events'
  /parents/{id}/events/update:
    $ref: '../openapi_parent_controller.yaml#/paths/~1parents~1{id}~1events~1update'

  /families:
    $ref: './family_controller.yaml#/paths/~1families'
  /families/{id}:
    $ref: './family_controller.yaml#/paths/~1families~1{id}'
  /families/student/{id}:
    $ref: './family_controller.yaml#/paths/~1families~1student~1{id}'
  /families/{id}/guardians:
    $ref: './family_controller.yaml#/paths/~1families~1{id}~1guardians'

  /emergency-contacts:
    $ref: './emergency_contact_controller.yaml#/paths/~1emergency-contacts'
  /emergency-contacts/{id}:
    $ref: './emergency_contact_controller.yaml#/paths/~1emergency-contacts~1{id}'
  /emergency-contacts/parent/{id}:
    $ref: './emergency_contact_controller.yaml#/paths/~1emergency-contacts~1parent~1{id}'

  # Administrator API (referenced from administrator controller spec)
  /administrator/dashboard:
    $ref: '../openapi_administrator_controller.yaml#/paths/~1administrator~1dashboard'
  /administrator/absence:
    $ref: '../openapi_administrator_controller.yaml#/paths/~1administrator~1absence'
  /administrator/search:
    $ref: '../openapi_administrator_controller.yaml#/paths/~1administrator~1search'
  /administrator/enrollment-withdrawal/data:
    $ref: '../openapi_administrator_controller.yaml#/paths/~1administrator~1enrollment-withdrawal~1data'
  /administrator/enrollment-withdrawal/update:
    $ref: '../openapi_administrator_controller.yaml#/paths/~1administrator~1enrollment-withdrawal~1update'
  /administrator/students:
    $ref: '../openapi_administrator_controller.yaml#/paths/~1administrator~1students'
  /administrator/parents:
    $ref: '../openapi_administrator_controller.yaml#/paths/~1administrator~1parents'

  /score-predictor/report:
    $ref: './score_predictor_controller.yaml#/paths/~1score-predictor~1report'

  /roles:
    $ref: './role_permission_controller.yaml#/paths/~1roles'
  /roles/{id}:
    $ref: './role_permission_controller.yaml#/paths/~1roles~1{id}'
  /roles/{id}/permissions:
    $ref: './role_permission_controller.yaml#/paths/~1roles~1{id}~1permissions'
  /permissions:
    $ref: './role_permission_controller.yaml#/paths/~1permissions'
  /users:
    $ref: './role_permission_controller.yaml#/paths/~1users'
  /admins:
    $ref: './role_permission_controller.yaml#/paths/~1admins'
  /users/{id}/roles:
    $ref: './role_permission_controller.yaml#/paths/~1users~1{id}~1roles'

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