Request/Response Flow

Relevant source files

The following files were used as context for generating this wiki page:

• finder/urls.py
• finder/views.py
• finder/templates/finder/search.html
• finder/static/finder/js/scripts.js
• roomfinder/settings.py
• finder/templates/finder/upload_excel.html
• README.md

The request/response flow in the Campuspal Room Finder application is designed to provide a dynamic and responsive user experience. It primarily handles two major features: searching for available rooms and uploading schedule data. The system leverages a combination of traditional Django server-rendered pages for initial loads, asynchronous JavaScript (AJAX) for partial page updates during searches, and a dedicated API endpoint for retrieving detailed data on demand.

This architecture minimizes full-page reloads, creating a fluid interface. The main search functionality is handled by a single view that can respond to both standard HTTP requests and AJAX requests, while a separate view manages the file upload process for administrators.

Room Search and Timeline Display (/)

The core user interaction revolves around the search page, which allows users to find rooms and view their availability on a visual timeline. This process involves an initial page load and subsequent AJAX requests for dynamic updates.

Initial Page Load (GET Request)

When a user first navigates to the application's root URL, a standard GET request is processed to render the main search interface.

1. The request to / is handled by the home view, which issues a redirect to the search_rooms view.
2. The search_rooms view is called with a GET request. It initializes an empty RoomSearchForm.
3. The view then renders the finder/search.html template, passing the form and empty lists for room data.
4. The template displays the search form and a welcome message, as no search has been performed yet.

This flow is illustrated in the diagram below.

AJAX Search Submission (POST Request)

To provide a seamless experience without page reloads, form submissions are handled asynchronously.

1. The user fills out the search form and clicks "Search".
2. The submit event is intercepted by finder/static/finder/js/scripts.js.
3. An AJAX POST request is sent to the search_rooms view. The request includes the form data and a special header, X-Requested-With: XMLHttpRequest, to identify it as an AJAX call.
4. The search_rooms view processes the form data, queries the database for rooms and their schedules, and builds a timeline for each room.
5. If a specific time is searched, rooms are categorized into available_rooms and unavailable_rooms.
6. Crucially, the view calculates start_percentage and width_percentage for each timeline block, which are used by the CSS to render the visual timeline correctly.
7. Detecting the AJAX header, the view renders the finder/timeline_partial.html template instead of the full search.html.
8. The partial HTML is returned to the browser, and the JavaScript injects it into the results container.

The following sequence diagram details this client-server interaction.

The context passed to the template includes the following data:

Key	Type	Description
form	RoomSearchForm	The search form instance.
available_rooms	list	A list of rooms that are free for the specified time and duration. Each item contains room and timeline data.
unavailable_rooms	list	A list of all other rooms, or all rooms if no specific time was searched.
errors	list	A list of error messages, if any.
search_performed	bool	A flag indicating if a specific time-based search was executed.
Sources: finder/views.py:102-108

Room Details API (/api/room/<room_id>/)

When a user clicks on a room in the timeline, a modal appears with detailed information. This is powered by a simple API endpoint that returns JSON data.

Frontend Interaction

1. An event listener in scripts.js detects a click on a .timeline-row element.
2. It extracts the data-room-id from the clicked element and the current day from the search form.
3. A fetch GET request is made to /api/room/<room_id>/?day=<day>.
4. Upon receiving a JSON response, the script dynamically populates the modal's HTML with the room's details and its full daily schedule.
5. The modal is then displayed to the user.

Sources: finder/static/finder/js/scripts.js:40-69

Backend API Logic

The request is routed to the api.room_details view, which is responsible for serving the room data.

The sequence diagram below illustrates the API flow.

Based on the JavaScript client, the API returns a JSON object with the following structure:

Key	Type	Description
room	object	An object containing room details (name, building, capacity, amenities).
timeline	array	An array of schedule blocks, each with start, end, type, and course.
Sources: finder/static/finder/js/scripts.js:48-62

Data Upload Flow (/upload/)

This flow allows staff members to upload rooms.xlsx and timetable.xlsx files to populate the database.

1. A staff member navigates to /upload/. The upload_excel view is protected by the @staff_member_required decorator, ensuring only authorized users can access it.
2. On a GET request, the view renders finder/templates/finder/upload_excel.html, which contains a form for file uploads.
3. The user selects files and submits the form, making a POST request.
4. The upload_excel view validates the ExcelUploadForm.
5. It uses the pandas library to read the data from the uploaded Excel files in memory.
6. The view first clears existing data (Room and ClassSchedule objects) before importing new data.
7. It iterates through the rows, validates the data (e.g., day/time format), and creates new model instances.
8. Feedback is provided to the user via the Django messages framework.
9. Upon successful processing, the user is redirected back to the main search page.

The logic for handling the file upload is shown below.

URL Routing Configuration

Django's URL dispatcher maps incoming request paths to the appropriate view functions. The project's routing is configured across two main files.

Path	View Function	Name	Description
"" (root)	include("finder.urls")	-	Includes all URLs from the finder app.
"" (in finder)	views.home	finder:home	Redirects to the search page.
search/ (effective path)	views.search_rooms	finder:search_rooms	Handles room searching and timeline display.
upload/	views.upload_excel	finder:upload_excel	Handles Excel file uploads for staff.
api/room/<int:room_id>/	api.room_details	finder:room_details	API endpoint to fetch details for a specific room.
Sources: roomfinder/settings.py:53, finder/urls.py (whole file), README.md