Skip to content

nirmaljb/hall-management-server

BranchesTags

Repository files navigation

Backend API Endpoints

This document outlines the available API endpoints for the backend service.

Authentication

  • POST /api/auth/login
    • Description: Authenticates a user and returns a JWT token.
    • Status Codes: 200 OK (success), 400 Bad Request (invalid input), 401 Unauthorized (invalid credentials), 500 Internal Server Error (failure)

Schools

  • GET /api/school/all-schools

    • Description: Retrieves a list of all schools.
    • Authorization: ADMIN, FACULTY, HOD
    • Status Codes: 200 OK, 500 Internal Server Error

  • GET /api/school/:id

    • Description: Retrieves a specific school by its ID.
    • Authorization: ADMIN, FACULTY, HOD
    • Path Parameters: id (UUID) - School unique identifier
    • Status Codes: 200 OK, 500 Internal Server Error

  • POST /api/school/create

    • Description: Creates a new school.
    • Authorization: ADMIN
    • Request Body: School object with incharge_status field (PERMANENT or INCHARGE)
    • Status Codes: 200 OK, 400 Bad Request, 500 Internal Server Error

  • PUT /api/school/:id

    • Description: Updates an existing school's information.
    • Authorization: ADMIN
    • Path Parameters: id (UUID) - School unique identifier
    • Status Codes: 200 OK, 400 Bad Request, 500 Internal Server Error

  • DELETE /api/school/:id

    • Description: Deletes a school by its ID.
    • Authorization: ADMIN
    • Path Parameters: id (UUID) - School unique identifier
    • Status Codes: 200 OK, 500 Internal Server Error

Department

  • GET /api/department/all-department

    • Description: Retrieves a list of all departments.
    • Authorization: ADMIN, FACULTY, HOD
    • Status Codes: 200 OK, 500 Internal Server Error

  • GET /api/department/:id

    • Description: Retrieves a specific department by its ID.
    • Authorization: ADMIN, FACULTY, HOD
    • Path Parameters: id (UUID) - Department unique identifier
    • Status Codes: 200 OK, 500 Internal Server Error

  • POST /api/department/create

    • Description: Creates a new department.
    • Authorization: ADMIN, HOD
    • Status Codes: 200 OK, 400 Bad Request, 500 Internal Server Error

  • PATCH /api/department/:id

    • Description: Updates an existing department's information.
    • Authorization: ADMIN
    • Path Parameters: id (UUID) - Department unique identifier
    • Status Codes: 200 OK, 400 Bad Request, 500 Internal Server Error

  • DELETE /api/department/:id

    • Description: Deletes a department by its ID.
    • Authorization: ADMIN
    • Path Parameters: id (UUID) - Department unique identifier
    • Status Codes: 200 OK, 500 Internal Server Error

Halls

  • GET /api/hall/all-hall

    • Description: Retrieves a list of all halls.
    • Authorization: ADMIN, FACULTY, HOD
    • Query Parameters: filter (optional) - Values: all (default), archived, available
    • Status Codes: 200 OK, 500 Internal Server Error
    • Response: Returns halls with categorization flags: is_archived, is_available

  • GET /api/hall/:id

    • Description: Retrieves a specific hall by its ID, including school and department information.
    • Authorization: ADMIN, FACULTY, HOD
    • Path Parameters: id (UUID) - Hall unique identifier
    • Status Codes: 200 OK, 500 Internal Server Error

  • POST /api/hall/create

    • Description: Creates a new hall.
    • Authorization: ADMIN, HOD
    • Status Codes: 200 OK, 400 Bad Request, 500 Internal Server Error

  • PATCH /api/hall/:id

    • Description: Updates an existing hall's information.
    • Authorization: ADMIN, HOD
    • Path Parameters: id (UUID) - Hall unique identifier
    • Status Codes: 200 OK, 400 Bad Request, 500 Internal Server Error

  • DELETE /api/hall/:id

    • Description: Deletes a hall by its ID.
    • Authorization: ADMIN, HOD
    • Path Parameters: id (UUID) - Hall unique identifier
    • Status Codes: 200 OK, 500 Internal Server Error

Employees

  • GET /api/employee/all-employees

    • Description: Retrieves a list of all employees with their school and department information.
    • Authorization: ADMIN, FACULTY, HOD
    • Status Codes: 200 OK, 500 Internal Server Error

  • GET /api/employee/:id

    • Description: Retrieves a specific employee by their ID with school and department details.
    • Authorization: ADMIN, FACULTY, HOD
    • Path Parameters: id (UUID) - Employee unique identifier
    • Status Codes: 200 OK, 500 Internal Server Error

  • POST /api/employee/create

    • Description: Creates a new employee and automatically creates a corresponding user account with default password (designation + 123).
    • Authorization: ADMIN, HOD
    • Status Codes: 200 OK, 400 Bad Request, 500 Internal Server Error
    • Note: Also creates a User record with email from employee_email field

  • PATCH /api/employee/:id

    • Description: Updates an existing employee's information.
    • Authorization: ADMIN, HOD
    • Path Parameters: id (UUID) - Employee unique identifier
    • Status Codes: 200 OK, 400 Bad Request, 500 Internal Server Error

  • DELETE /api/employee/:id

    • Description: Deletes an employee by their ID.
    • Authorization: ADMIN, HOD
    • Path Parameters: id (UUID) - Employee unique identifier
    • Status Codes: 200 OK, 500 Internal Server Error

Booking

POST /api/booking/request

Create a new booking request.

  • Authorization: FACULTY, HOD
  • Status Codes: 200 OK, 400 Bad Request, 401 Unauthorized, 409 Conflict, 500 Internal Server Error

Business Logic:

  • Validates hall is not archived
  • Checks for booking conflicts (both hall and user conflicts)
  • Creates booking request with status PENDING_HOD_APPROVAL
  • Determines appropriate HOD for approval based on user's department
  • Generates booking slots for all valid dates within the specified range
  • For semester bookings, only creates slots for specified days of the week

Request Body:

{
  "hall_id": "string (UUID)",
  "purpose": "string",
  "class_code": "string (optional)",
  "booking_type": "INDIVIDUAL | SEMESTER",
  "start_date": "string (ISO 8601 datetime)",
  "end_date": "string (ISO 8601 datetime)", 
  "start_time": "string (HH:MM format, 24-hour)",
  "end_time": "string (HH:MM format, 24-hour)",
  "days_of_week": [
    "SUNDAY",
    "MONDAY", 
    "TUESDAY",
    "WEDNESDAY",
    "THURSDAY",
    "FRIDAY",
    "SATURDAY"
  ],
  "booking_requested_employee_id": "string (UUID, optional - defaults to requesting user)"
}

PUT /api/booking/:id/approve

Approve a pending booking request.

  • Authorization: HOD
  • Path Parameters: id (UUID) - Booking request unique identifier
  • Status Codes: 200 OK, 404 Not Found, 500 Internal Server Error
  • Business Logic:
    • Security check: Only the assigned approving HOD can approve
    • Updates request and all associated slots to CONFIRMED status
    • Automatically rejects any conflicting pending requests for the same hall and time slots
    • Works for both PENDING_HOD_APPROVAL and PENDING_HALL_HOD_APPROVAL statuses

PUT /api/booking/:id/forward

Forward a booking request to the hall's department HOD.

  • Authorization: HOD
  • Path Parameters: id (UUID) - Booking request unique identifier
  • Status Codes: 200 OK, 404 Not Found, 500 Internal Server Error
  • Business Logic:
    • Only works for requests in PENDING_HOD_APPROVAL status
    • Cannot forward internal bookings (same department)
    • Updates status to PENDING_HALL_HOD_APPROVAL
    • Reassigns approving_hod_id to the hall's department HOD
    • Validates that hall belongs to a department and has an HOD

PUT /api/booking/:id/reject

Reject a pending booking request.

  • Authorization: HOD
  • Path Parameters: id (UUID) - Booking request unique identifier
  • Status Codes: 200 OK, 404 Not Found, 500 Internal Server Error
  • Business Logic:
    • Security check: Only the assigned approving HOD can reject
    • Sets appropriate rejection status based on current stage:
      • PENDING_HOD_APPROVAL → REJECTED_BY_HOD
      • PENDING_HALL_HOD_APPROVAL → REJECTED_BY_HALL_HOD
    • Updates both request and associated slots

DELETE /api/booking/:id

Delete a booking request and its associated slots.

  • Authorization: HOD
  • Path Parameters: id (UUID) - Booking request unique identifier
  • Status Codes: 200 OK, 404 Not Found, 500 Internal Server Error
  • Business Logic: Deletes all associated booking slots first, then the booking request

GET /api/booking/my-requests

Get the current user's booking requests.

  • Authorization: ADMIN, HOD, FACULTY
  • Status Codes: 200 OK, 401 Unauthorized, 500 Internal Server Error
  • Response: Returns requests ordered by creation date (newest first) with hall and user details

GET /api/booking/approvals

Get all pending booking requests for HOD approval. This endpoint is designed for Heads of Department (HODs) to view and manage booking requests that require their attention. It provides categorized views of requests based on their origin and approval status.

  • Authorization: HOD
  • Status Codes: 200 OK, 401 Unauthorized, 500 Internal Server Error
  • Query Parameters:
    • filter (optional): Filters the requests. If omitted, it defaults to all.
      • all: Returns all requests pending the HOD's approval.
      • internal: Returns requests from the HOD's own department for halls within the same department.
      • forward: Returns requests from the HOD's department for halls in other departments, which can be forwarded.
      • external: Returns requests that have been forwarded from other departments for halls within the HOD's department.

Business Logic:

  • Only shows requests where the current HOD is the approving_hod_id
  • Categorizes requests based on user department vs hall department relationship
  • Determines available actions for each request (approve, forward, reject)

Response Body: The response is an array of booking request objects. Each object is augmented with additional properties to aid the UI in displaying the request appropriately.

  • is_internal_request (boolean): true if the booking user and the hall belong to the same department.
  • can_be_forwarded (boolean): true if the request is in the PENDING_HOD_APPROVAL state and is for a hall in a different department.
  • is_external_approval (boolean): true if the request has been forwarded from another department and has the status PENDING_HALL_HOD_APPROVAL.
  • approval_stage (string): Indicates the current stage of approval (user_department or hall_department).
  • category (string): A convenience category for the frontend (internal, forward, or external).

Example Response (?filter=all):

{
  "success": true,
  "data": [
    {
      "unique_id": "booking-uuid-1",
      "purpose": "Internal Department Meeting",
      "status": "PENDING_HOD_APPROVAL",
      // ... other booking fields
      "hall": {
        "name": "CS Conference Room",
        "department_id": "cs-dept-uuid"
      },
      "user": {
        "employee": {
          "employee_name": "Dr. Smith",
          "department_id": "cs-dept-uuid"
        }
      },
      "is_internal_request": true,
      "can_be_forwarded": false,
      "is_external_approval": false,
      "approval_stage": "user_department",
      "category": "internal"
    },
    {
      "unique_id": "booking-uuid-2",
      "purpose": "Guest Lecture for ECE",
      "status": "PENDING_HOD_APPROVAL",
      // ... other booking fields
      "hall": {
        "name": "ECE Seminar Hall",
        "department_id": "ece-dept-uuid"
      },
      "user": {
        "employee": {
          "employee_name": "Dr. Jones",
          "department_id": "cs-dept-uuid"
        }
      },
      "is_internal_request": false,
      "can_be_forwarded": true,
      "is_external_approval": false,
      "approval_stage": "user_department",
      "category": "forward"
    },
    {
      "unique_id": "booking-uuid-3",
      "purpose": "Workshop by MECH dept",
      "status": "PENDING_HALL_HOD_APPROVAL",
      // ... other booking fields
      "hall": {
        "name": "CS Main Auditorium",
        "department_id": "cs-dept-uuid"
      },
      "user": {
        "employee": {
          "employee_name": "Dr. Brown",
          "department_id": "mech-dept-uuid"
        }
      },
      "is_internal_request": false,
      "can_be_forwarded": false,
      "is_external_approval": true,
      "approval_stage": "hall_department",
      "category": "external"
    }
  ]
}

PUT /api/booking/:id/modify

Modify an existing booking request.

  • Authorization: FACULTY, HOD
  • Path Parameters: id (UUID) - Booking request unique identifier
  • Status Codes: 200 OK, 400 Bad Request, 401 Unauthorized, 500 Internal Server Error
  • Business Logic:
    • Only allows modification of requests in PENDING_HOD_APPROVAL or PENDING_HALL_HOD_APPROVAL status
    • Security check: Only the original requesting user can modify their request
    • Validates new hall is not archived
    • Checks for conflicts with other bookings (excluding current request)
    • Deletes existing slots and creates new ones based on modified parameters
    • Preserves the current approval status and assigned HOD

Request Body: Same as /api/booking/request - full booking object with updated parameters

Conflict Detection

GET /api/booking/conflicts

Retrieve all booking conflicts in the system.

  • Authorization: ADMIN, HOD
  • Status Codes: 200 OK, 401 Unauthorized, 500 Internal Server Error
  • Business Logic:
    • Analyzes all confirmed booking slots for overlapping time periods
    • Detects both hall conflicts (same hall, overlapping time) and user conflicts (same user, overlapping time)
    • Returns detailed conflict information with overlap periods and affected parties

Response Body:

{
  "success": true,
  "data": {
    "total_conflicts": 5,
    "hall_conflicts": 2,
    "user_conflicts": 2,
    "both_conflicts": 1,
    "conflicts": [
      {
        "conflict_type": "HALL",
        "booking_1": {
          "booking_id": "uuid",
          "hall_name": "Conference Room A",
          "user_name": "Dr. Smith",
          "department": "Computer Science",
          "purpose": "Team Meeting",
          "start_time": "2024-01-15T10:00:00Z",
          "end_time": "2024-01-15T12:00:00Z"
        },
        "booking_2": { /* similar structure */ },
        "overlap_details": {
          "overlap_start": "2024-01-15T11:00:00Z",
          "overlap_end": "2024-01-15T12:00:00Z",
          "conflict_hall": "Conference Room A",
          "conflict_user": null
        }
      }
    ]
  }
}

GET /api/booking/conflicts/hall/:id

Get booking conflicts for a specific hall.

  • Authorization: ADMIN, HOD
  • Path Parameters: id (UUID) - Hall unique identifier
  • Status Codes: 200 OK, 401 Unauthorized, 500 Internal Server Error
  • Business Logic:
    • Returns all overlapping confirmed bookings for the specified hall
    • Provides detailed conflict information including user details and overlap periods

GET /api/booking/conflicts/user/:id

Get booking conflicts for a specific user.

  • Authorization: ADMIN, HOD
  • Path Parameters: id (UUID) - User unique identifier
  • Status Codes: 200 OK, 401 Unauthorized, 500 Internal Server Error
  • Business Logic:
    • Returns all overlapping confirmed bookings for the specified user
    • Shows conflicts where the same user has multiple bookings at the same time

Key Business Rules for New Endpoints

Modification Workflow

  1. Security: Only the original requester can modify their booking
  2. Status Limitation: Can only modify pending requests (not approved/rejected)
  3. Conflict Prevention: Validates against all other bookings except the current one being modified
  4. Slot Management: Completely replaces existing slots with new ones while preserving approval workflow state

Conflict Detection Logic

  1. Overlap Detection: Uses time-based overlap algorithm (start1 < end2 && end1 > start2)
  2. Conflict Types:
    • HALL: Same hall, overlapping time, different users
    • USER: Same user, overlapping time, different halls
    • BOTH: Same hall AND same user with overlapping time
  3. Performance: Processes all confirmed slots with optimized nested loops and duplicate prevention
  4. Detailed Reports: Provides comprehensive conflict information for administrative review

Error Handling Additions

  • Modification attempts on non-modifiable requests are rejected
  • Archived hall selection during modification is prevented
  • Conflict detection handles large datasets efficiently
  • All operations maintain database consistency with proper transaction handling

GET /api/booking/hall/pending/:id

Get pending booking slots for a specific hall.

  • Authorization: ADMIN, HOD, FACULTY
  • Path Parameters: id (UUID) - Hall unique identifier
  • Status Codes: 200 OK, 500 Internal Server Error
  • Response: Returns slots with status PENDING_HOD_APPROVAL or PENDING_HALL_HOD_APPROVAL, including booking request details and user information

GET /api/booking/hall/:id

Get confirmed bookings for a specific hall.

  • Authorization: ADMIN, HOD, FACULTY
  • Path Parameters: id (UUID) - Hall unique identifier
  • Status Codes: 200 OK, 500 Internal Server Error
  • Response: Returns only slots with CONFIRMED status, including booking request details

Key Business Rules for AI Implementation

Booking Workflow

  1. Initial Request: Faculty/HOD creates booking → Status: PENDING_HOD_APPROVAL
  2. Department HOD Review:
    • If internal (same dept): Can approve directly
    • If external (different dept): Must forward to hall's dept HOD
  3. Hall Department HOD Review: Approves/rejects external requests
  4. Conflict Resolution: Approving a request automatically rejects conflicting pending requests

Role-Based Access

  • ADMIN: Full access to all CRUD operations
  • HOD: Can create/update employees, departments (limited), approve/forward/reject bookings assigned to them
  • FACULTY: Can view data and create booking requests
  • Security: All endpoints validate user authorization and UUID parameters

Data Relationships

  • Users have employee records linked to departments
  • Halls belong to departments
  • Booking requests require HOD approval from user's department
  • External bookings require additional approval from hall's department HOD
  • Employee creation automatically creates user account with role-based default password

Error Handling

  • Archived halls cannot be booked
  • Conflicting time slots are prevented
  • Missing HOD assignments cause booking failures
  • All operations use database transactions for consistency

About

The hall management backend for Pondicherry University

hall-management.nirmaljyotib.workers.dev/

Topics

postgresql hono prisma-orm zod-validation

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages