Developer Guide

Relevant source files

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

• CONTRIBUTING.md
• README.md
• TODO.md
• finder/static/finder/css/styles.css
• finder/static/finder/js/scripts.js
• roomfinder/settings.py
• generate_sample_data.py
• finder/tests.py
• finder/templates/finder/upload_excel.html
• finder/templates/finder/search.html
• finder/views.py

This guide provides a technical overview of the Campuspal Room Finder application. It covers the project's architecture, key components, data flow, and contribution guidelines for developers. The application is a Django-based web tool designed to help users find available rooms on a campus by providing a visual timeline of room schedules.

The project consists of a single Django app, finder, which handles all core logic, including room searching, data visualization, and data import from Excel files. The frontend is built with standard HTML, CSS, and JavaScript, featuring a modern, responsive design with dynamic updates via AJAX.

Sources: README.md:1-19

Project Structure

The project is organized as a standard Django project with one primary application.

File/Directory	Description	Source(s)
roomfinder/	The main Django project directory, containing settings and root URL configuration.	roomfinder/settings.py
finder/	The core Django app containing models, views, templates, and static files for the room finder functionality.	roomfinder/settings.py:41
finder/static/	Contains the application's CSS and JavaScript files.	finder/static/finder/css/styles.css, finder/static/finder/js/scripts.js
finder/templates/	Contains the Django templates for rendering the UI.	finder/templates/finder/search.html, finder/templates/finder/upload_excel.html
generate_sample_data.py	A script to create realistic sample rooms.xlsx and timetable.xlsx files for testing.	generate_sample_data.py
CONTRIBUTING.md	Guidelines for developers who wish to contribute to the project.	CONTRIBUTING.md

Backend Architecture

The backend is built with Django and handles data processing, business logic, and API services.

Database Models

The application uses two primary models, Room and ClassSchedule, to store data. The README.md indicates that the Room model was enhanced to include fields for capacity, amenities, and photo_url.

The relationship between the models is that a Room can have many ClassSchedule entries.

This diagram shows the ERD for the Room and ClassSchedule models.

Sources: README.md:164-169, finder/views.py:127-131, 203-206

Core Views

The primary logic is contained within finder/views.py.

Room Search (search_rooms)

This view handles both the initial page load and AJAX-based search requests. Its main responsibility is to process search criteria, generate a detailed timeline for each room, and categorize rooms as "available" or "unavailable" based on user input.

The logic flow is as follows:

1. Receives a POST request with form data (building, day, optional time/duration).
2. Fetches all relevant Room objects.
3. For each room, it constructs a timeline for the selected day by iterating through its ClassSchedule entries. It calculates free slots between booked periods.
4. If a specific time and duration are provided, it checks if the requested time slot fits within any "free" block in each room's timeline.
5. Rooms are sorted into available_rooms and unavailable_rooms lists.
6. Percentage-based values (start_percentage, width_percentage) are calculated for each timeline block to aid frontend rendering.
7. The context is rendered into timeline_partial.html for AJAX requests or search.html for standard requests.

This diagram illustrates the control flow within the search_rooms view.

Sources: finder/views.py:14-106, README.md:104-127

Excel Data Upload (upload_excel)

This view, accessible only to staff members, provides a mechanism to populate the database from .xlsx files. It uses a drag-and-drop interface for file selection.

The process is:

1. The user uploads rooms_file and/or timetable_file.
2. The view uses pandas to read the Excel files into DataFrames.
3. For Rooms: It clears the existing Room table and iterates through the rows, creating new Room objects.
4. For Timetables: It clears the ClassSchedule table. It then iterates through rows, parsing the Day/Time string, finding the corresponding Room object, and creating a ClassSchedule entry.
5. Success or error messages are passed to the template.

This diagram shows the data flow for the Excel upload feature.

Sources: finder/views.py:109-227, finder/templates/finder/upload_excel.html:31-56

API Endpoint

A simple API is provided to fetch detailed information for a single room, which is used to populate the modal on the frontend.

Method	Endpoint	Description	Response	Source
GET	/api/room/<int:room_id>/?day=<day>	Retrieves details and a full daily schedule for a specific room.	JSON object with room attributes and a timeline array.	README.md:130-141

The room_details function in finder/api.py (as described in README.md) constructs a timeline for the specified room and day and returns it as a JsonResponse.

Frontend

The frontend is responsible for user interaction, rendering the visual timeline, and communicating with the backend via AJAX.

JavaScript (scripts.js)

The file finder/static/finder/js/scripts.js handles all client-side interactivity.

• AJAX Search: It intercepts the search form submission, sends the data to the search_rooms view via an AJAX POST request, and injects the returned HTML partial into the results container.
• Room Details Modal: It listens for clicks on timeline rows. On click, it extracts the room-id, fetches room details from the /api/room/<id>/ endpoint, and dynamically populates and displays a modal with the room's schedule.
• Tab Toggling: It manages the "Available" and "Unavailable" tabs in the results section, showing and hiding content client-side for instant feedback.
• File Upload UI: It enhances the upload_excel.html page by providing drag-and-drop functionality for the file input fields.

AJAX Search Sequence

The following diagram shows the interaction between the user, browser, and server during a search.

This diagram details the sequence of events for an AJAX search and opening the details modal.

Sources: finder/static/finder/js/scripts.js:5-32, 35-71

Styling (styles.css)

The UI is styled using finder/static/finder/css/styles.css. Key features of the styling approach include:

• CSS Variables: A comprehensive set of HSL-based CSS variables are defined in :root for easy theming (e.g., --primary-color, --surface-color). A .theme-dark class overrides these variables for a dark mode.
• Responsive Design: Media queries are used to adapt the layout for smaller screens (e.g., stacking the sidebar and main content).
• Visual Timeline: The timeline blocks (.timeline-block) are positioned absolutely within a relative container (.timeline). Their left and width are controlled by the percentage values calculated in the backend.
• Animations: Subtle animations are used for modal pop-ups (modal-fade-in), timeline block appearance (block-pop), and animated gradients on "free" time blocks (stripe-animate).

Sources: finder/static/finder/css/styles.css:1-40, 312-323, 370-375, 431-435

Data Management

Sample Data Generation

The generate_sample_data.py script is a utility for creating realistic test data. It generates two files in the sample_data/ directory:

• rooms.xlsx: Contains a list of rooms with generated names, buildings, capacities, amenities (as a JSON string), and photo URLs.
• timetable.xlsx: Contains a list of class schedules with random courses, subjects, times, and assigned rooms.

This script is crucial for local development and testing the application's performance with a significant amount of data.

Sources: generate_sample_data.py, README.md:92-99

Data Loading

Data is loaded into the database via two primary methods:

1. Excel Upload Page: The /upload/ page, which uses the upload_excel view. This is the primary method for administrators.
2. Management Commands: The README.md mentions load_rooms_excel and load_timetable management commands, which are updated to read from the sample_data directory.

Sources: README.md:178-182, finder/views.py:109-227

Setup and Contribution

Project Setup

To set up the project for local development, follow these steps:

1. Clone the repository.
2. Create and activate a virtual environment.
3. Install dependencies from requirements.txt.
4. Apply database migrations: python manage.py migrate.
5. Generate sample data: python generate_sample_data.py.
6. Load the data into the database using the management commands (load_rooms_excel, load_timetable).
7. Run the development server: python manage.py runserver.

Sources: README.md:190-217, CONTRIBUTING.md:7-10

Contribution Guidelines

Contributions are welcome in the form of bug fixes, features, and documentation. The standard workflow is:

1. Fork the repository.
2. Create a new feature branch (e.g., feature/your-feature).
3. Make changes, adhering to PEP 8 style guidelines.
4. Add or update tests in finder/tests.py.
5. Run tests locally with python manage.py test.
6. Submit a Pull Request (PR) with a clear description of the changes.

The TODO.md file lists known linting issues and potential future improvements, which can be a good starting point for new contributors.

Sources: CONTRIBUTING.md:4-30, TODO.md