openapi: 3.0.3
info:
  title: Peek-a-Boo API
  description: Complete REST API for Childcare Management System
  version: 1.0.0
  contact:
    name: Peek-a-Boo Support
    email: support@pkb.kids

servers:
  - url: https://api.pkb.kids
    description: Production API Server

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

  schemas:
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          example: "Error message"
        message:
          type: string
          example: "User-friendly error message"

    LoginRequest:
      type: object
      required:
        - email
        - password
      properties:
        email:
          type: string
          format: email
          example: "admin@p-b.app"
        password:
          type: string
          format: password
          example: "Admin@2025"

    LoginResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        token:
          type: string
          example: "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
        user:
          type: object
          properties:
            id:
              type: string
              format: uuid
            email:
              type: string
            role:
              type: string
              enum: [super_admin, admin, staff, parent]
            first_name:
              type: string
            last_name:
              type: string

    Child:
      type: object
      properties:
        child_id:
          type: string
          format: uuid
        first_name:
          type: string
        last_name:
          type: string
        preferred_name:
          type: string
        date_of_birth:
          type: string
          format: date
        room_id:
          type: string
          format: uuid
        centre_id:
          type: string
          format: uuid
        is_active:
          type: boolean
        dietary_requirements:
          type: string
        allergies:
          type: string

    CreateObservationRequest:
      type: object
      required:
        - child_id
        - centre_id
        - description
      properties:
        child_id:
          type: string
          format: uuid
          example: "40e100c8-ece2-11f0-b1c2-00163e8be9bd"
        centre_id:
          type: string
          format: uuid
          example: "10772f8c-ece2-11f0-b1c2-00163e8be9bd"
        description:
          type: string
          example: "Ava showed excellent problem-solving skills while building with blocks"
        observation_type:
          type: string
          enum: [learning_moment, achievement, behavior, social_interaction, milestone]
          example: "learning_moment"

    Observation:
      type: object
      properties:
        observation_id:
          type: string
          format: uuid
        child_id:
          type: string
          format: uuid
        centre_id:
          type: string
          format: uuid
        description:
          type: string
        observation_type:
          type: string
        created_by_id:
          type: string
          format: uuid
        created_at:
          type: string
          format: date-time

    CreateIncidentRequest:
      type: object
      required:
        - child_id
        - centre_id
        - incident_type
        - title
        - description
        - location
        - incident_date
        - incident_time
        - action_taken
        - severity
      properties:
        child_id:
          type: string
          format: uuid
        centre_id:
          type: string
          format: uuid
        incident_type:
          type: string
          enum: [minor_injury, major_injury, illness, behavioral, accident, allergic_reaction]
        title:
          type: string
          example: "Minor bump on playground"
        description:
          type: string
        location:
          type: string
          example: "Playground"
        incident_date:
          type: string
          format: date
        incident_time:
          type: string
          format: time
        action_taken:
          type: string
          example: "Applied ice pack, monitored for 10 minutes"
        severity:
          type: string
          enum: [minor, moderate, major]

    Incident:
      type: object
      properties:
        incident_id:
          type: string
          format: uuid
        child_id:
          type: string
          format: uuid
        centre_id:
          type: string
          format: uuid
        incident_type:
          type: string
        title:
          type: string
        description:
          type: string
        location:
          type: string
        incident_date:
          type: string
          format: date
        incident_time:
          type: string
          format: time
        action_taken:
          type: string
        severity:
          type: string
        created_by_id:
          type: string
          format: uuid
        created_at:
          type: string
          format: date-time

    CreateMedicationRequest:
      type: object
      required:
        - child_id
        - centre_id
        - medication_name
        - medication_type
        - dosage
        - frequency
        - administration_method
        - reason
        - start_date
      properties:
        child_id:
          type: string
          format: uuid
        centre_id:
          type: string
          format: uuid
        medication_name:
          type: string
          example: "Amoxicillin"
        medication_type:
          type: string
          enum: [prescription, over_the_counter, emergency]
        dosage:
          type: string
          example: "5ml"
        frequency:
          type: string
          enum: [once_daily, twice_daily, three_times_daily, four_times_daily, as_needed]
        administration_method:
          type: string
          enum: [oral, topical, inhaler, injection]
        reason:
          type: string
          example: "Ear infection treatment"
        start_date:
          type: string
          format: date
        end_date:
          type: string
          format: date

    Medication:
      type: object
      properties:
        medication_id:
          type: string
          format: uuid
        child_id:
          type: string
          format: uuid
        centre_id:
          type: string
          format: uuid
        medication_name:
          type: string
        medication_type:
          type: string
        dosage:
          type: string
        frequency:
          type: string
        administration_method:
          type: string
        reason:
          type: string
        start_date:
          type: string
          format: date
        end_date:
          type: string
          format: date
        is_active:
          type: boolean

    CreatePostRequest:
      type: object
      required:
        - centre_id
        - post_type
        - title
        - content
        - visibility
      properties:
        centre_id:
          type: string
          format: uuid
        post_type:
          type: string
          enum: [announcement, update, reminder, celebration, alert]
        title:
          type: string
          example: "Important Centre Closure Notice"
        content:
          type: string
          example: "The centre will be closed on Friday, January 20th for staff training."
        visibility:
          type: string
          enum: [all_parents, specific_children, specific_rooms, staff_only]

    Post:
      type: object
      properties:
        post_id:
          type: string
          format: uuid
        centre_id:
          type: string
          format: uuid
        post_type:
          type: string
        title:
          type: string
        content:
          type: string
        visibility:
          type: string
        created_by_id:
          type: string
          format: uuid
        created_at:
          type: string
          format: date-time

    CreateEventRequest:
      type: object
      required:
        - centre_id
        - event_type
        - title
        - start_date
        - end_date
      properties:
        centre_id:
          type: string
          format: uuid
        event_type:
          type: string
          enum: [parent_meeting, celebration, excursion, workshop, performance, sports_day, open_day]
        title:
          type: string
          example: "Spring Family Picnic"
        description:
          type: string
          example: "Join us for a fun family picnic in the park!"
        start_date:
          type: string
          format: date
        end_date:
          type: string
          format: date
        start_time:
          type: string
          format: time
        end_time:
          type: string
          format: time
        location:
          type: string
          example: "Central Park"

    Event:
      type: object
      properties:
        event_id:
          type: string
          format: uuid
        centre_id:
          type: string
          format: uuid
        event_type:
          type: string
        title:
          type: string
        description:
          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
        location:
          type: string

    CheckInRequest:
      type: object
      required:
        - child_id
        - centre_id
      properties:
        child_id:
          type: string
          format: uuid
        centre_id:
          type: string
          format: uuid
        check_in_time:
          type: string
          format: time
          example: "08:30:00"

    Attendance:
      type: object
      properties:
        attendance_id:
          type: string
          format: uuid
        child_id:
          type: string
          format: uuid
        centre_id:
          type: string
          format: uuid
        attendance_date:
          type: string
          format: date
        check_in_time:
          type: string
          format: time
        check_out_time:
          type: string
          format: time
        checked_in_by_id:
          type: string
          format: uuid

    StartNapRequest:
      type: object
      required:
        - child_id
        - centre_id
      properties:
        child_id:
          type: string
          format: uuid
        centre_id:
          type: string
          format: uuid
        start_time:
          type: string
          format: time
          example: "13:00:00"

    Nap:
      type: object
      properties:
        nap_id:
          type: string
          format: uuid
        child_id:
          type: string
          format: uuid
        centre_id:
          type: string
          format: uuid
        nap_date:
          type: string
          format: date
        start_time:
          type: string
          format: time
        end_time:
          type: string
          format: time
        notes:
          type: string

security:
  - bearerAuth: []

paths:
  /auth/login:
    post:
      tags:
        - Authentication
      summary: Login to get JWT token
      description: Authenticate a user and receive a JWT token for subsequent requests
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
      responses:
        '200':
          description: Successfully authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
        '401':
          description: Invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /children:
    get:
      tags:
        - Children
      summary: Get all children
      description: Get all children filtered by user's permissions and centre
      responses:
        '200':
          description: List of children
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Child'
              example:
                success: true
                data:
                  - child_id: "40e100c8-ece2-11f0-b1c2-00163e8be9bd"
                    first_name: "Ava"
                    last_name: "Jones"
                    date_of_birth: "2022-03-20"
                    room_id: "60a100c8-ece2-11f0-b1c2-00163e8be9bd"
                    centre_id: "10772f8c-ece2-11f0-b1c2-00163e8be9bd"
                    is_active: true
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /children/{child_id}:
    get:
      tags:
        - Children
      summary: Get child details
      description: Get detailed information about a specific child
      parameters:
        - name: child_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Child details
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/Child'
        '401':
          description: Unauthorized
        '404':
          description: Child not found

    put:
      tags:
        - Children
      summary: Update child profile
      description: Update a child's profile information
      parameters:
        - name: child_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                first_name:
                  type: string
                last_name:
                  type: string
                preferred_name:
                  type: string
                dietary_requirements:
                  type: string
                allergies:
                  type: string
            example:
              dietary_requirements: "No dairy"
              allergies: "Peanuts"
      responses:
        '200':
          description: Child updated successfully
          content:
            application/json:
              example:
                success: true
                message: "Child profile updated successfully"
                data:
                  child_id: "40e100c8-ece2-11f0-b1c2-00163e8be9bd"
                  dietary_requirements: "No dairy"
                  allergies: "Peanuts"
        '401':
          description: Unauthorized
        '404':
          description: Child not found

  /children/{child_id}/parents:
    get:
      tags:
        - Children
      summary: Get child's parents
      description: Get all parents/guardians linked to a child
      parameters:
        - name: child_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: List of parents
          content:
            application/json:
              example:
                success: true
                data:
                  - parent_id: "50a100c8-ece2-11f0-b1c2-00163e8be9bd"
                    first_name: "Sarah"
                    last_name: "Jones"
                    relationship: "mother"
                    email: "sarah.jones@example.com"
                    phone: "+1234567890"
        '401':
          description: Unauthorized

  /observations:
    get:
      tags:
        - Observations
      summary: Get all observations
      description: Get all observations filtered by user permissions
      responses:
        '200':
          description: List of observations
          content:
            application/json:
              example:
                success: true
                data:
                  - observation_id: "70a100c8-ece2-11f0-b1c2-00163e8be9bd"
                    child_id: "40e100c8-ece2-11f0-b1c2-00163e8be9bd"
                    description: "Showed great creativity in art activity"
                    observation_type: "learning_moment"
                    created_at: "2026-01-12T10:30:00Z"
        '401':
          description: Unauthorized

    post:
      tags:
        - Observations
      summary: Create observation
      description: Create a new observation for a child
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateObservationRequest'
      responses:
        '201':
          description: Observation created successfully
          content:
            application/json:
              example:
                success: true
                message: "Observation created successfully"
                data:
                  observation_id: "70a100c8-ece2-11f0-b1c2-00163e8be9bd"
                  child_id: "40e100c8-ece2-11f0-b1c2-00163e8be9bd"
                  description: "Ava showed excellent problem-solving skills"
                  observation_type: "learning_moment"
                  created_at: "2026-01-12T10:30:00Z"
        '400':
          description: Invalid request
        '401':
          description: Unauthorized

  /children/{child_id}/observations:
    get:
      tags:
        - Observations
      summary: Get child's observations
      description: Get all observations for a specific child
      parameters:
        - name: child_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: List of observations
          content:
            application/json:
              example:
                success: true
                data:
                  - observation_id: "70a100c8-ece2-11f0-b1c2-00163e8be9bd"
                    description: "Showed great creativity"
                    observation_type: "learning_moment"
        '401':
          description: Unauthorized

  /observations/{observation_id}:
    put:
      tags:
        - Observations
      summary: Update observation
      description: Update an existing observation
      parameters:
        - name: observation_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                description:
                  type: string
                observation_type:
                  type: string
            example:
              description: "Updated observation description"
      responses:
        '200':
          description: Observation updated
          content:
            application/json:
              example:
                success: true
                message: "Observation updated successfully"
        '401':
          description: Unauthorized
        '404':
          description: Observation not found

    delete:
      tags:
        - Observations
      summary: Delete observation
      description: Delete an observation
      parameters:
        - name: observation_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Observation deleted
          content:
            application/json:
              example:
                success: true
                message: "Observation deleted successfully"
        '401':
          description: Unauthorized
        '404':
          description: Observation not found

  /incidents:
    get:
      tags:
        - Incidents
      summary: Get all incidents
      description: Get all incident reports
      responses:
        '200':
          description: List of incidents
          content:
            application/json:
              example:
                success: true
                data:
                  - incident_id: "80a100c8-ece2-11f0-b1c2-00163e8be9bd"
                    child_id: "40e100c8-ece2-11f0-b1c2-00163e8be9bd"
                    incident_type: "minor_injury"
                    title: "Bump on playground"
                    severity: "minor"
        '401':
          description: Unauthorized

    post:
      tags:
        - Incidents
      summary: Create incident
      description: Create a new incident report
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateIncidentRequest'
            example:
              child_id: "40e100c8-ece2-11f0-b1c2-00163e8be9bd"
              centre_id: "10772f8c-ece2-11f0-b1c2-00163e8be9bd"
              incident_type: "minor_injury"
              title: "Minor bump"
              description: "Child bumped head on playground equipment"
              location: "Playground"
              incident_date: "2026-01-12"
              incident_time: "14:30:00"
              action_taken: "Applied ice pack, monitored"
              severity: "minor"
      responses:
        '201':
          description: Incident created
          content:
            application/json:
              example:
                success: true
                message: "Incident created successfully"
                data:
                  incident_id: "80a100c8-ece2-11f0-b1c2-00163e8be9bd"
                  title: "Minor bump"
                  severity: "minor"
        '400':
          description: Invalid request
        '401':
          description: Unauthorized

  /children/{child_id}/incidents:
    get:
      tags:
        - Incidents
      summary: Get child's incidents
      description: Get all incidents for a specific child
      parameters:
        - name: child_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: List of incidents
        '401':
          description: Unauthorized

  /incidents/{incident_id}:
    put:
      tags:
        - Incidents
      summary: Update incident
      parameters:
        - name: incident_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            example:
              action_taken: "Updated action taken"
      responses:
        '200':
          description: Incident updated
        '401':
          description: Unauthorized
        '404':
          description: Incident not found

    delete:
      tags:
        - Incidents
      summary: Delete incident
      parameters:
        - name: incident_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Incident deleted
        '401':
          description: Unauthorized
        '404':
          description: Incident not found

  /medications:
    post:
      tags:
        - Medications
      summary: Create medication
      description: Create a new medication record
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMedicationRequest'
            example:
              child_id: "40e100c8-ece2-11f0-b1c2-00163e8be9bd"
              centre_id: "10772f8c-ece2-11f0-b1c2-00163e8be9bd"
              medication_name: "Amoxicillin"
              medication_type: "prescription"
              dosage: "5ml"
              frequency: "twice_daily"
              administration_method: "oral"
              reason: "Ear infection"
              start_date: "2026-01-12"
              end_date: "2026-01-22"
      responses:
        '201':
          description: Medication created
          content:
            application/json:
              example:
                success: true
                message: "Medication created successfully"
                data:
                  medication_id: "90a100c8-ece2-11f0-b1c2-00163e8be9bd"
                  medication_name: "Amoxicillin"
                  dosage: "5ml"
        '400':
          description: Invalid request
        '401':
          description: Unauthorized

  /children/{child_id}/medications:
    get:
      tags:
        - Medications
      summary: Get child's medications
      parameters:
        - name: child_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: List of medications
          content:
            application/json:
              example:
                success: true
                data:
                  - medication_id: "90a100c8-ece2-11f0-b1c2-00163e8be9bd"
                    medication_name: "Amoxicillin"
                    dosage: "5ml"
                    frequency: "twice_daily"
        '401':
          description: Unauthorized

  /medications/{medication_id}:
    put:
      tags:
        - Medications
      summary: Update medication
      parameters:
        - name: medication_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            example:
              dosage: "7.5ml"
      responses:
        '200':
          description: Medication updated
        '401':
          description: Unauthorized
        '404':
          description: Medication not found

    delete:
      tags:
        - Medications
      summary: Delete medication
      parameters:
        - name: medication_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Medication deleted
        '401':
          description: Unauthorized
        '404':
          description: Medication not found

  /attendance/today:
    get:
      tags:
        - Attendance
      summary: Get today's attendance
      parameters:
        - name: centre_id
          in: query
          required: true
          schema:
            type: string
            format: uuid
        - name: room_id
          in: query
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Today's attendance
          content:
            application/json:
              example:
                success: true
                data:
                  - child_id: "40e100c8-ece2-11f0-b1c2-00163e8be9bd"
                    first_name: "Ava"
                    last_name: "Jones"
                    check_in_time: "08:30:00"
                    check_out_time: null
        '400':
          description: Centre ID required
        '401':
          description: Unauthorized

  /attendance/check-in:
    post:
      tags:
        - Attendance
      summary: Check in child
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckInRequest'
      responses:
        '201':
          description: Child checked in
          content:
            application/json:
              example:
                success: true
                message: "Child checked in successfully"
                data:
                  attendance_id: "a0a100c8-ece2-11f0-b1c2-00163e8be9bd"
                  check_in_time: "08:30:00"
        '400':
          description: Invalid request
        '401':
          description: Unauthorized

  /children/{child_id}/attendance:
    get:
      tags:
        - Attendance
      summary: Get child's attendance history
      parameters:
        - name: child_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Attendance history
        '401':
          description: Unauthorized

  /naps/current:
    get:
      tags:
        - Naps
      summary: Get currently napping children
      parameters:
        - name: centre_id
          in: query
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Currently napping children
          content:
            application/json:
              example:
                success: true
                data:
                  - child_id: "40e100c8-ece2-11f0-b1c2-00163e8be9bd"
                    first_name: "Ava"
                    last_name: "Jones"
                    start_time: "13:00:00"
                    duration_minutes: 45
        '400':
          description: Centre ID required
        '401':
          description: Unauthorized

  /naps/start:
    post:
      tags:
        - Naps
      summary: Start a nap
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartNapRequest'
      responses:
        '201':
          description: Nap started
          content:
            application/json:
              example:
                success: true
                message: "Nap started successfully"
                data:
                  nap_id: "b0a100c8-ece2-11f0-b1c2-00163e8be9bd"
                  start_time: "13:00:00"
        '400':
          description: Invalid request
        '401':
          description: Unauthorized

  /posts:
    get:
      tags:
        - Posts
      summary: Get news feed posts
      responses:
        '200':
          description: List of posts
          content:
            application/json:
              example:
                success: true
                data:
                  - post_id: "c0a100c8-ece2-11f0-b1c2-00163e8be9bd"
                    title: "Important Notice"
                    content: "Centre closure next Friday"
                    post_type: "announcement"
                    created_at: "2026-01-12T09:00:00Z"
        '401':
          description: Unauthorized

    post:
      tags:
        - Posts
      summary: Create post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePostRequest'
      responses:
        '201':
          description: Post created
          content:
            application/json:
              example:
                success: true
                message: "Post created successfully"
                data:
                  post_id: "c0a100c8-ece2-11f0-b1c2-00163e8be9bd"
                  title: "Important Centre Closure Notice"
        '400':
          description: Invalid request
        '401':
          description: Unauthorized

  /posts/{post_id}:
    put:
      tags:
        - Posts
      summary: Update post
      parameters:
        - name: post_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            example:
              title: "Updated Title"
              content: "Updated content"
      responses:
        '200':
          description: Post updated
        '401':
          description: Unauthorized
        '404':
          description: Post not found

    delete:
      tags:
        - Posts
      summary: Delete post
      parameters:
        - name: post_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Post deleted
        '401':
          description: Unauthorized
        '404':
          description: Post not found

  /events:
    get:
      tags:
        - Events
      summary: Get all events
      responses:
        '200':
          description: List of events
          content:
            application/json:
              example:
                success: true
                data:
                  - event_id: "d0a100c8-ece2-11f0-b1c2-00163e8be9bd"
                    title: "Spring Picnic"
                    event_type: "celebration"
                    start_date: "2026-03-15"
                    location: "Central Park"
        '401':
          description: Unauthorized

    post:
      tags:
        - Events
      summary: Create event
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEventRequest'
      responses:
        '201':
          description: Event created
          content:
            application/json:
              example:
                success: true
                message: "Event created successfully"
                data:
                  event_id: "d0a100c8-ece2-11f0-b1c2-00163e8be9bd"
                  title: "Spring Family Picnic"
        '400':
          description: Invalid request
        '401':
          description: Unauthorized

  /events/{event_id}:
    put:
      tags:
        - Events
      summary: Update event
      parameters:
        - name: event_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            example:
              location: "Updated location"
      responses:
        '200':
          description: Event updated
        '401':
          description: Unauthorized
        '404':
          description: Event not found

    delete:
      tags:
        - Events
      summary: Delete event
      parameters:
        - name: event_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Event deleted
        '401':
          description: Unauthorized
        '404':
          description: Event not found

  /messages/conversations:
    get:
      tags:
        - Messages
      summary: Get message conversations
      responses:
        '200':
          description: List of conversations
          content:
            application/json:
              example:
                success: true
                data:
                  - conversation_id: "e0a100c8-ece2-11f0-b1c2-00163e8be9bd"
                    other_user:
                      first_name: "Sarah"
                      last_name: "Jones"
                    last_message: "Thanks for the update"
                    unread_count: 2
        '401':
          description: Unauthorized

  /messages:
    post:
      tags:
        - Messages
      summary: Send message
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - recipient_id
                - message_text
              properties:
                recipient_id:
                  type: string
                  format: uuid
                subject:
                  type: string
                message_text:
                  type: string
            example:
              recipient_id: "50a100c8-ece2-11f0-b1c2-00163e8be9bd"
              subject: "Regarding pickup time"
              message_text: "I'll be 15 minutes late today"
      responses:
        '201':
          description: Message sent
          content:
            application/json:
              example:
                success: true
                message: "Message sent successfully"
        '400':
          description: Invalid request
        '401':
          description: Unauthorized

  /notifications:
    get:
      tags:
        - Notifications
      summary: Get notifications
      responses:
        '200':
          description: List of notifications
          content:
            application/json:
              example:
                success: true
                data:
                  - notification_id: "f0a100c8-ece2-11f0-b1c2-00163e8be9bd"
                    title: "New Observation"
                    message: "A new observation has been added for Ava"
                    notification_type: "observation"
                    is_read: false
                    created_at: "2026-01-12T10:30:00Z"
        '401':
          description: Unauthorized

  /notifications/unread-count:
    get:
      tags:
        - Notifications
      summary: Get unread notification count
      responses:
        '200':
          description: Unread count
          content:
            application/json:
              example:
                success: true
                count: 5
        '401':
          description: Unauthorized

  /staff:
    get:
      tags:
        - Staff
      summary: Get all staff
      responses:
        '200':
          description: List of staff members
          content:
            application/json:
              example:
                success: true
                data:
                  - user_id: "30a100c8-ece2-11f0-b1c2-00163e8be9bd"
                    first_name: "Emily"
                    last_name: "Smith"
                    role: "staff"
                    email: "emily@p-b.app"
        '401':
          description: Unauthorized

  /parents:
    get:
      tags:
        - Parents
      summary: Get all parents
      responses:
        '200':
          description: List of parents
          content:
            application/json:
              example:
                success: true
                data:
                  - user_id: "50a100c8-ece2-11f0-b1c2-00163e8be9bd"
                    first_name: "Sarah"
                    last_name: "Jones"
                    email: "sarah.jones@example.com"
        '401':
          description: Unauthorized

  /rooms:
    get:
      tags:
        - Rooms
      summary: Get all rooms
      responses:
        '200':
          description: List of rooms
          content:
            application/json:
              example:
                success: true
                data:
                  - room_id: "60a100c8-ece2-11f0-b1c2-00163e8be9bd"
                    room_name: "Toddler Room"
                    age_group: "2-3 years"
                    capacity: 15
        '401':
          description: Unauthorized

  /assessments:
    post:
      tags:
        - Assessments
      summary: Create assessment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - child_id
                - centre_id
                - assessment_type
                - assessment_date
              properties:
                child_id:
                  type: string
                  format: uuid
                centre_id:
                  type: string
                  format: uuid
                assessment_type:
                  type: string
                  enum: [developmental, behavioral, learning, social]
                assessment_date:
                  type: string
                  format: date
                notes:
                  type: string
            example:
              child_id: "40e100c8-ece2-11f0-b1c2-00163e8be9bd"
              centre_id: "10772f8c-ece2-11f0-b1c2-00163e8be9bd"
              assessment_type: "developmental"
              assessment_date: "2026-01-12"
              notes: "Good progress in all areas"
      responses:
        '201':
          description: Assessment created
          content:
            application/json:
              example:
                success: true
                message: "Assessment created successfully"
        '400':
          description: Invalid request
        '401':
          description: Unauthorized

  /children/{child_id}/assessments:
    get:
      tags:
        - Assessments
      summary: Get child's assessments
      parameters:
        - name: child_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: List of assessments
          content:
            application/json:
              example:
                success: true
                data:
                  - assessment_id: "g0a100c8-ece2-11f0-b1c2-00163e8be9bd"
                    assessment_type: "developmental"
                    assessment_date: "2026-01-12"
                    notes: "Good progress"
        '401':
          description: Unauthorized
