Backend Architecture

Relevant source files

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

• finder/views.py
• finder/models.py
• roomfinder/settings.py
• finder/admin.py
• generate_sample_data.py
• finder/static/finder/js/scripts.js
• README.md

The backend of the Campuspal Room Finder is built using the Django web framework. It follows a monolithic structure with a single Django app, finder, handling the majority of the application's logic. The backend is responsible for serving web pages, processing user search queries, managing room and schedule data in a database, and providing an interface for bulk data uploads via Excel files.

The architecture is designed to support both standard server-rendered pages and dynamic, client-side updates through AJAX requests. It exposes a RESTful API endpoint for fetching detailed room information, which is consumed by the frontend to populate modal dialogs without requiring a full page reload.

Project Configuration

The project's core settings are defined in roomfinder/settings.py. This file configures the Django environment, including installed applications, database connections, and middleware.

Sources: roomfinder/settings.py

Installed Applications

The project relies on standard Django contrib apps and the main finder application.

Application Name	Purpose
django.contrib.admin	Provides the Django administration site.
django.contrib.auth	Handles user authentication.
django.contrib.contenttypes	Framework for content types.
django.contrib.sessions	Manages user sessions.
django.contrib.messages	Handles message framework.
django.contrib.staticfiles	Manages static files (CSS, JS, images).
finder.apps.FinderConfig	The primary application for the room finder.

Sources: roomfinder/settings.py:30-37

Database Configuration

The application uses dj-database-url to configure the database from a DATABASE_URL environment variable, with a fallback to a local SQLite database for development. This allows for flexible deployment across different environments. The SECRET_KEY and DEBUG settings are also loaded from environment variables using python-decouple.

# roomfinder/settings.py:89-91
DATABASES = {
    'default': dj_database_url.config(default=config('DATABASE_URL'))
}

Sources: roomfinder/settings.py:16, roomfinder/settings.py:22, roomfinder/settings.py:25, roomfinder/settings.py:89-91

Data Models

The data persistence layer is defined by two primary Django models in the finder app. These models represent the core entities of the application: rooms and their schedules.

Sources: finder/models.py

Entity Relationship Diagram

The diagram below illustrates the relationship between the Room and ClassSchedule models. A single Room can have multiple ClassSchedule entries.

Room Model

The Room model stores information about each physical room on campus.

Field	Type	Description
name	CharField(max_length=100)	The unique identifier for the room (e.g., "A101").
building	CharField(max_length=100)	The building where the room is located (e.g., "Hephaestus Hall").
capacity	PositiveIntegerField	The maximum occupancy of the room. Defaults to 0.
amenities	JSONField	A JSON list of amenities (e.g., ["Projector", "Whiteboard"]).
photo_url	URLField	An optional URL to an image of the room.

A UniqueConstraint ensures that the combination of name and building is unique across all records.

Sources: finder/models.py:7-12, finder/models.py:17-21

ClassSchedule Model

The ClassSchedule model represents a single booking or class event within a room.

Field	Type	Description
course	CharField(max_length=50)	The course code (e.g., "CS101").
subject	CharField(max_length=100)	The full subject name (e.g., "Intro to Programming").
day	CharField(max_length=3)	The day of the week, chosen from DAY_CHOICES (e.g., "Mon").
start_time	TimeField	The start time of the class.
end_time	TimeField	The end time of the class.
room	ForeignKey(Room)	A foreign key relationship to the Room where the class is held.
lecturer	CharField(max_length=100)	The name of the lecturer.
is_cancelled	BooleanField	A flag to indicate if the class is cancelled. Defaults to False.

This model includes database indexes on (day, start_time, end_time) and (room, is_cancelled) to optimize query performance.

Sources: finder/models.py:31-48, finder/models.py:52-55

Core Views and Logic

The primary business logic resides in finder/views.py, which contains functions to handle search requests and data uploads.

Sources: finder/views.py

Room Search (search_rooms)

This view is the main entry point for users. It handles both the initial page load (GET) and search form submissions (POST). When a search is performed, it can operate in two modes:

1. Timeline View: If only building and day are provided, it generates a full-day availability timeline for all matching rooms.
2. Availability Search: If time and duration are also provided, it categorizes rooms into "Available" and "Unavailable" based on the specified time window.

The view is optimized to handle AJAX requests by rendering a partial template (timeline_partial.html) for dynamic updates, avoiding a full page refresh.

Sources: finder/views.py:14-106, finder/static/finder/js/scripts.js:6-25

Search Logic Flow

The following diagram shows the logical flow within the search_rooms view upon a POST request.

Excel Data Upload (upload_excel)

This view provides a mechanism for staff members to bulk-upload or overwrite room and timetable data using .xlsx files. Access is restricted to staff members via the @staff_member_required decorator.

The function processes two separate files:

1. Rooms File: Clears existing Room data and populates it from rooms.xlsx.
2. Timetable File: Clears existing ClassSchedule data and populates it from timetable.xlsx, parsing day/time strings and linking schedules to the appropriate rooms.

Sources: finder/views.py:109-245, finder/templates/finder/upload_excel.html

Upload Logic Flow

This diagram outlines the process for handling file uploads.

API Endpoint

The backend exposes a simple API to provide detailed data for a single room, which is used by the frontend to populate a modal window. This is defined in finder/api.py (as inferred from README.md and finder/static/finder/js/scripts.js).

GET /api/room/<room_id>/

This endpoint retrieves detailed information for a specific room, including its full daily schedule.

Request-Response Sequence

The following sequence diagram shows how the frontend interacts with this API endpoint.

Data Management

Admin Interface

The Django Admin site is configured in finder/admin.py to provide a user-friendly interface for managing Room and ClassSchedule data.

• Room Admin: Displays rooms with a count of their scheduled classes. It allows filtering by building and searching by name or building.
• ClassSchedule Admin: Provides a detailed list view with filtering by day, status, building, and time. It allows for inline editing of the is_cancelled status.

Sources: finder/admin.py:6-41

Sample Data Generation

A standalone script, generate_sample_data.py, is provided to create realistic rooms.xlsx and timetable.xlsx files. This script is essential for development, testing, and demonstrating the application's features without requiring real data. It generates 50 rooms and 300 schedule entries with randomized details.

Sources: generate_sample_data.py