High-Level Architecture Overview

Relevant source files

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

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

The Campuspal Room Finder is a Django-based web application designed to provide a modern and intuitive interface for finding available rooms on a campus. The architecture is centered around a single Django app, finder, which handles backend logic, data processing, and rendering. The frontend is a dynamic, single-page experience for search, leveraging AJAX to update results without page reloads.

The system's core functionality includes a visual timeline of room availability, a detailed room profile modal, and a time-based search that categorizes rooms as "Available" or "Unavailable". Data is initially ingested into the SQLite database from Excel files, with a provided script to generate realistic sample data.

Core Components

The application follows a traditional client-server architecture, with a clear separation between the Django backend, the browser-based frontend, and the database.

The diagram below illustrates the main components and their interactions.

Backend Architecture

The backend is built using the Django framework and consists of a single application, finder, which encapsulates most of the project's logic.

Sources: roomfinder/settings.py:44, README.md:22

Application Structure & Configuration

File/Component	Description	Source Files
roomfinder/settings.py	Main project configuration. Defines INSTALLED_APPS (including finder), database connection (dj_database_url), and static file settings.	roomfinder/settings.py:44, 88, 125
finder/views.py	Contains the core business logic for handling user requests, processing data, and rendering templates. Key views are search_rooms and upload_excel.	finder/views.py
finder/urls.py	Defines URL patterns for the finder app, mapping paths like /, /upload/, and /api/room/<id>/ to their corresponding views.	README.md:151-157
finder/models.py	Defines the database schema through Django's ORM. Key models are Room and ClassSchedule. (Inferred from other files).	README.md:142-149

Views and Logic

search_rooms(request)

This is the main view of the application. It handles both the initial page load (GET) and search queries (POST).

1. Input Handling: Receives building, day, and optionally time and duration from the RoomSearchForm.
2. Timeline Generation: For each room matching the building query, it constructs a full-day timeline (7 AM to 11 PM). It iterates through the room's ClassSchedule and fills in "free" and "booked" time blocks.
3. Availability Check: If a search time and duration are provided, it checks which rooms have a continuous "free" block large enough to accommodate the request.
4. Categorization: Rooms are sorted into available_rooms and unavailable_rooms lists.
5. Response:
   • For standard requests, it renders the full search.html template.
   • For AJAX requests (identified by the X-Requested-With header), it renders only the timeline_partial.html fragment to update the results dynamically.

Sources: finder/views.py:15-110, README.md:80-102

upload_excel(request)

This view is restricted to staff members and provides a mechanism for populating the database from Excel files.

1. File Handling: Accepts rooms_file and timetable_file uploads.
2. Data Parsing: Uses the pandas library to read data from the uploaded Excel files.
3. Database Population: It clears existing data from Room and ClassSchedule tables and then iterates through the DataFrame rows to create new model instances. It performs data validation, such as checking for required columns and valid day/time formats.
4. Feedback: Uses Django's messages framework to report success or errors back to the user.

Sources: finder/views.py:113-241, finder/templates/upload_excel.html:31-37

Room Details API

An API endpoint provides detailed information for a single room, used to populate the frontend modal.

Method	Endpoint	Description	Response
GET	/api/room/<int:room_id>/?day=<day>	Fetches a room's details (name, capacity, amenities) and its full daily schedule for the specified day.	JsonResponse with room data and a timeline array.

Sources: README.md:104-114, finder/static/finder/js/scripts.js:41-43

Frontend Architecture

The frontend is designed to be a responsive and interactive single-page application for the search feature.

Sources: finder/templates/search.html, finder/static/finder/css/styles.css

Structure and Styling

• Templates: The UI is built with Django templates. search.html serves as the main page, containing the search form and results container. upload_excel.html provides the data upload interface.
• Styling: A comprehensive stylesheet (finder/static/finder/css/styles.css) defines a modern aesthetic with a card-based layout, a responsive flexbox grid, custom form elements, and detailed styling for the visual timeline and modal window. It also includes a dark theme.

Sources: finder/templates/search.html:18-64, finder/static/finder/css/styles.css:1-400

Client-Side Interaction (scripts.js)

The finder/static/finder/js/scripts.js file orchestrates the dynamic behavior of the search page.

• 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.
• Modal Interaction: It uses event delegation to detect clicks on room timeline rows. On click, it fetches detailed room data from the /api/room/... endpoint and dynamically populates a modal window with the room's schedule.
• Tab Toggling: It manages the "Available" and "Unavailable" tabs, showing and hiding the relevant content sections on the client side for instant feedback.

Sources: finder/static/finder/js/scripts.js:8-88

Data Flow and Management

Room Search and Display Flow

The following diagram shows the sequence of events when a user performs a search.

Room Details Modal Flow

This diagram shows how room details are fetched and displayed in the modal.

Database Schema

The database contains two primary models, Room and ClassSchedule. The schema is inferred from usage in views.py and descriptions in README.md.

Sources: README.md:142-149, finder/views.py:40, 189-192

Data Ingestion

The application relies on a manual data ingestion process.

1. Data Generation: A standalone script, generate_sample_data.py, can be run to create rooms.xlsx and timetable.xlsx files with a large, realistic dataset. This is useful for testing and demonstration.
2. Data Upload: An administrator can use the /upload/ page to upload these Excel files. The upload_excel view in views.py then uses pandas to parse the files and populate the Room and ClassSchedule tables in the database.

Sources: generate_sample_data.py, finder/views.py:113-241, README.md:179-186