openapi: 3.0.0
info:
  title: PROJ-sdbms-php Portal API
  description: |
    School Database Management System Portal - Frontend Gateway Integration
    This portal aggregates multiple microservice endpoints for school management operations.
    
    **Connected Microservices**:
    - auth-service (authentication)
    - user-service (user profiles)
    - product-service (resources/materials)
    - order-service (class assignments/purchases)
    
    **Portal ID**: sdbms-portal
    **Version**: 1.0.0
  version: 1.0.0
  contact:
    name: School Management Team
    email: support@sdbms.local

servers:
  - url: http://localhost/projects/PROJ-sdbms-php/frontend
    description: Development SDBMS Portal
  - url: https://sdbms.emmanylcode.local
    description: Production SDBMS Portal

security:
  - BearerAuth: []
  - ApiKeyAuth: []

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token from auth-service
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

  schemas:
    PortalUser:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string
          format: email
        role:
          type: string
          enum: [student, teacher, admin, parent]
        avatar:
          type: string
          format: uri

    Course:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        code:
          type: string
        instructor:
          type: string
        enrollment_status:
          type: string

    Assignment:
      type: object
      properties:
        id:
          type: integer
        course_id:
          type: integer
        title:
          type: string
        due_date:
          type: string
          format: date-time
        status:
          type: string
          enum: [pending, submitted, graded]

paths:
  /api/portal/auth/register:
    post:
      summary: Portal User Registration
      description: |
        Register a new user via the portal, which calls the auth-service.
        Accepts user credentials and additional profile information.
      operationId: portalRegister
      tags:
        - Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - email
                - password
                - phone
                - address
              properties:
                name:
                  type: string
                email:
                  type: string
                  format: email
                password:
                  type: string
                  format: password
                phone:
                  type: string
                address:
                  type: string
                role:
                  type: string
                  enum: [student, teacher, parent]
      responses:
        '201':
          description: User registered successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  user:
                    $ref: '#/components/schemas/PortalUser'
        '400':
          description: Validation error
        '409':
          description: User already exists

  /api/portal/auth/login:
    post:
      summary: Portal User Login
      description: Authenticate user and receive JWT token
      operationId: portalLogin
      tags:
        - Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - password
              properties:
                email:
                  type: string
                  format: email
                password:
                  type: string
                  format: password
      responses:
        '200':
          description: Login successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  user:
                    $ref: '#/components/schemas/PortalUser'
                  token:
                    type: string
        '401':
          description: Invalid credentials

  /api/portal/profile:
    get:
      summary: Get User Profile
      description: Retrieve current logged-in user's profile from user-service
      operationId: getPortalProfile
      tags:
        - User Profile
      responses:
        '200':
          description: Profile retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortalUser'
        '401':
          description: Unauthorized

  /api/portal/courses:
    get:
      summary: Get Enrolled Courses
      description: Retrieve courses the user is enrolled in
      operationId: getUserCourses
      tags:
        - Courses
      responses:
        '200':
          description: Courses retrieved
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Course'

  /api/portal/assignments:
    get:
      summary: Get User Assignments
      description: Retrieve assignments for enrolled courses
      operationId: getUserAssignments
      tags:
        - Assignments
      parameters:
        - name: status
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Assignments retrieved
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Assignment'

tags:
  - name: Authentication
    description: Portal authentication endpoints (proxied to auth-service)
  - name: User Profile
    description: User profile endpoints (proxied to user-service)
  - name: Courses
    description: Course management endpoints (proxied to product-service)
  - name: Assignments
    description: Assignment endpoints (proxied to order-service)
