Frontend Architecture

Relevant source files

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

• finder/static/finder/js/scripts.js
• finder/templates/finder/search.html
• finder/static/finder/css/styles.css
• finder/templates/finder/upload_excel.html
• README.md

The frontend architecture of Campuspal Room Finder is designed to provide a modern, intuitive, and responsive user experience. It employs a traditional server-side rendering approach using Django templates for the initial page structure, which is then progressively enhanced with vanilla JavaScript to create a dynamic, single-page-application-like feel for core interactions. The styling is managed through a single, comprehensive CSS file that utilizes modern features like custom properties for theming and a responsive, component-based design.

The primary goal is to deliver a "sleek, modern, and unforgettable" design that is both visually appealing and highly functional. This is achieved through a clean, card-based layout, a harmonious color palette, and micro-interactions that provide instant feedback to the user without full page reloads.

Sources: README.md, finder/static/finder/css/styles.css, finder/static/finder/js/scripts.js

Core Technologies

The frontend is built upon a foundation of standard web technologies, leveraging the Django template engine for server-side rendering.

• HTML: Generated by Django templates, primarily search.html and upload_excel.html. These files define the core structure of the application's pages.
• CSS: A single stylesheet, styles.css, controls the entire visual presentation. It uses a modern approach with CSS variables, flexbox, and grid for layout.
• JavaScript: Vanilla JavaScript, located in scripts.js, is used to add interactivity, handle user events, and communicate with the backend via AJAX.

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

Styling and Design System

The visual design is implemented in styles.css and is built around a flexible and maintainable system.

Sources: finder/static/finder/css/styles.css

Theming and Color Palette

A robust theming system is established using CSS custom properties (variables) defined within the :root selector. This allows for easy adjustments to the color scheme and supports both light (default) and dark themes. The dark theme is activated by adding a theme-dark class to the <html> element, which overrides the default variable values.

The primary color palette is based on HSL values, making it simple to modify hue, saturation, and lightness.

:root {
    --primary-hue: 265;
    --primary-color: hsl(var(--primary-hue), 88%, 55%);
    --text-primary: #0f172a;
    --surface-color: #ffffff;
    --background-color: #f6f7fb;
    --border-color: #e2e8f0;
    --success-color: #10b981;
    --danger-color: #ef4444;
}

/* Dark theme variables */
.theme-dark {
    --surface-color: #0b1220;
    --background-color: #0a0f1c;
    --text-primary: #e2e8f0;
    --border-color: #1e293b;
}

Sources: finder/static/finder/css/styles.css:1-31, finder/static/finder/css/styles.css:50-58

Layout and Components

The application uses a responsive layout built with Flexbox. The main view (search.html) is divided into a sticky sidebar for the search form and a main results section. Key UI elements are styled as reusable components.

The following diagram illustrates the main layout components of the search page.

Key styled components are summarized in the table below:

Class Name	Description	Source File
.card	A container with a background, border, and shadow. Used for the search form and modal.	styles.css:127-134
.search-btn	The primary action button with a gradient background and hover effects.	styles.css:180-201
.timeline-row	Represents a single room's schedule, with hover effects to indicate interactivity.	styles.css:300-313
.timeline-block	A colored block representing a free or booked time slot on the timeline.	styles.css:339-370
.modal	A full-screen overlay with a blurred backdrop for displaying room details.	styles.css:386-401
.tab-link	A button for switching between "Available" and "Unavailable" result tabs.	styles.css:262-274

Page Structure and Templates

The application consists of two primary pages, each with its own Django template.

• Search Page (search.html): The main interface for finding rooms. It contains the search form, the results container, and the hidden modal structure. It uses a Django include tag to render the timeline_partial.html inside the results-container when results are available.
• Upload Page (upload_excel.html): A page for uploading room and timetable data. It features a modern drag-and-drop interface for file selection.

Both templates share a common header and overall page structure, linking to the same styles.css and scripts.js files for a consistent look and feel.

Sources: finder/templates/finder/search.html, finder/templates/finder/upload_excel.html

Client-Side Interactivity

All client-side logic is contained within finder/static/finder/js/scripts.js. It is loaded at the end of the <body> tag and enhances the static HTML with dynamic features.

Sources: finder/static/finder/js/scripts.js

AJAX Search

To avoid full page reloads, the search form submission is intercepted. The form data is sent to the backend via an AJAX POST request. The server responds with a rendered HTML partial, which is then injected into the #results-container div.

This diagram shows the sequence of events during an AJAX search.

Room Details Modal

When a user clicks on a room's timeline (.timeline-row), an event listener (using event delegation on the #results-container) triggers a modal. An AJAX GET request is sent to the /api/room/<room_id>/ endpoint to fetch detailed data for that specific room. The returned JSON is used to dynamically populate the modal's content before it is displayed.

This diagram illustrates the modal opening flow.

Other Interactions

The scripts.js file also handles several other key UI features:

Feature	Description	Source
Tab Toggling	Listens for clicks on .tab-link elements to show/hide the "Available" and "Unavailable" room lists by toggling an active class. This is a purely client-side operation.	scripts.js:80-94
Theme Toggling	A click on the theme toggle button switches between light and dark modes. The selected theme is saved to localStorage to persist across sessions.	scripts.js:97-126
Modal Closing	The modal can be closed by clicking the close button or by clicking on the backdrop overlay.	scripts.js:65-77
File Upload UI	Implements drag-and-drop functionality for the file input fields on the upload_excel.html page, providing visual feedback when a file is dragged over or selected.	scripts.js:129-175

Conclusion

The frontend of the Campuspal Room Finder is a well-structured system that balances the simplicity of server-rendered pages with the rich interactivity of client-side JavaScript. The use of a component-based CSS architecture with theming support ensures a consistent and modern aesthetic, while the targeted use of AJAX for search and data fetching creates a smooth and responsive user experience. This architecture effectively meets the project's goal of being a modern and intuitive tool for finding campus rooms.

Sources: README.md, finder/static/finder/js/scripts.js, finder/static/finder/css/styles.css