1. Product overview

Roomwise is a web-based room reservation and facility allocation decision-support system for the CCSICT department. It helps authorized users find suitable rooms, review availability, coordinate professor-led class schedules, and manage reservation records.

The system ranks rooms using requested capacity and features, shows reservation conflicts, and provides dashboards and reports based on the records visible to the signed-in user.

2. Goals and scope

• Make department room availability and reservation schedules easier to review.
• Help professors select a room that fits an activity's capacity and feature needs.
• Keep student schedule access tied to professor-created subject groups.
• Give administrators tools to review reservations, manage accounts, and monitor system activity.
• Support account recovery without exposing existing passwords to administrators.

In scope

Account registration and sign-in; professor approval; room directory and recommendations; reservation creation, review, updates, and history; subject-group access; account recovery; dashboards; and printable or downloadable reports.

Out of scope

Payment processing, automatic class timetable generation, external identity-provider integration, and native mobile applications are not part of the current application.

3. Users and permissions

4. Functional requirements

1. Authentication and accounts: Users can register as students or professors using a valid email address. Sign-in requires a role and CAPTCHA. New professor accounts remain pending until an administrator approves them; pending or rejected professors cannot sign in.
2. Password recovery: A user can request a time-limited password reset link by email. Administrators can send reset links to the registered address for student and professor accounts. The user chooses their own new password; administrators never receive or set it.
3. Room discovery: Users can browse the room directory and review capacity, room type, features, building, and availability. The recommendation view ranks matching rooms using requested capacity and features and indicates conflicts.
4. Reservations: Approved professors can create reservations for a subject group, view their bookings, edit or delete their own reservations, and mark eligible bookings complete. Administrators can review pending requests and approve or reject them.
5. Student schedule access: Professors can create subject groups with cohort details and an access code. Students can request access with the code and view schedules for groups they have joined.
6. Administration: Administrators can search accounts, filter student and professor accounts, change other users' roles, approve or reject professor registrations, and review audit activity.
7. Dashboards and reports: The dashboard presents role-scoped reservation and account metrics. Administrators can filter analytics and generate reports from available reservation, user, and activity data.
8. Notifications and session handling: The system reports important actions and errors to users, supports live reservation updates, and signs users out when their account is no longer valid.

5. Business rules

• Only approved professor accounts can sign in as professors; new professor accounts begin in pending status.
• Students and built-in demo accounts cannot manage reservations. Demo accounts are limited to viewing.
• Professor-created reservations must be associated with a subject group owned by that professor.
• Reservation dates cannot be in the past. Times must be on the same day, between 6:00 AM and 11:59 PM, using whole-minute intervals; overnight bookings are not allowed.
• A room cannot be reserved for overlapping times. Completed reservations remain in history and no longer block availability.
• Password recovery links expire after 30 minutes and can be used only once. Email delivery requires the application’s SMTP configuration.
• Dashboard data is scoped to the signed-in user's permissions; administrators can review system-wide information.

6. Quality and operational requirements

• Security: Protected actions require an authenticated session and server-side authorization. Mutating requests use CSRF protection. Passwords are stored as hashes; reset tokens are stored as hashes rather than plaintext.
• Privacy: Users see only schedules and account actions permitted by their role. Password reset links go to the account's registered email address.
• Reliability: Reservation conflicts and account permissions are checked by the server, not only by the browser interface. Errors should be communicated without reporting a failed action as successful.
• Usability: The interface should provide clear status, validation, and confirmation messages, and remain usable on desktop and narrow screens.
• Operations: The application runs with PHP, MySQL, and Apache. Email-dependent features require Composer mail dependencies and SMTP settings to be configured.

7. Acceptance criteria

• Users can open this document from the Help button and return to other app views using normal navigation.
• A pending professor is prevented from signing in and sees an administrator-approval message.
• A student can view only schedules for subject groups they have joined and cannot create reservations.
• A demo account can explore room recommendations and existing reservations, but reservation changes are rejected by the server.
• A professor can create a valid reservation for an owned subject group, and conflicting or invalid bookings are rejected.
• An administrator can approve or reject reservation requests and professor accounts, and email password reset links to student or professor accounts.
• A valid reset link allows its recipient to set a compliant password once before it expires.
• Dashboard and report information respects role permissions and the selected filters.

1. System architecture

Roomwise is a browser-based application served from an Apache web root. The client uses HTML, CSS, and vanilla JavaScript; PHP API endpoints handle authentication, database operations, permissions, email, reporting, and administration. MySQL stores users, rooms, reservations, subject groups, audit events, and password-reset records.

• Presentation: index.html, styles.css, and app.js.
• Application/API: PHP scripts under api/; JSON is used for client/API payloads.
• Data: MySQL accessed through PHP PDO with the PDO MySQL driver.
• Email: PHPMailer installed with Composer and connected to an SMTP server.
• Build process: The client is served directly; no JavaScript bundler or frontend package installation is required.

2. Server runtime requirements

3. Database requirements

• Create/import the ccsict_room_reservation database using db/ccsict_room_reservation.sql.
• Use InnoDB tables and utf8mb4 character encoding. The connection is configured in db_connect.php and uses PDO exception mode, associative fetches, and native prepared statements.
• For existing installations, apply the database migrations documented in README.md, then run db/update_room_inventory.sql.
• Database connection failures are written to the PHP error log; verify the database name, user, password, host, and privileges if the API reports an unavailable database.
• Back up the database before applying migrations or restoring data. The restore workflow replaces application data and should only be used by an administrator.

4. Browser and client requirements

• Use a current version of Microsoft Edge, Google Chrome, Mozilla Firefox, or Safari with JavaScript enabled.
• The client requires modern browser support for Fetch, Promises, async/await, optional chaining, URL/history APIs, CSS Grid and Flexbox, and HTML form validation.
• Canvas support is used for dashboard charts. Printing uses the browser print dialog.
• Serve the app over HTTP/HTTPS through Apache. Opening index.html directly as a file does not provide the PHP API and database-backed features.
• For production, use HTTPS so session cookies and password-reset links are protected in transit.

5. Configuration requirements

Database

Set the database host, schema name, username, and password in db_connect.php. The sample XAMPP defaults are for local development only and must be replaced with a least-privilege database account in a deployed environment.

Email and password recovery

Install Composer dependencies and provide these environment variables to the PHP process used by Apache:

ROOMWISE_SMTP_HOST
ROOMWISE_SMTP_PORT
ROOMWISE_SMTP_USER
ROOMWISE_SMTP_PASS
ROOMWISE_SMTP_FROM
ROOMWISE_SMTP_NAME
ROOMWISE_BASE_URL

Use a valid public application URL for ROOMWISE_BASE_URL. SMTP credentials must be stored outside source control. Email-dependent registration notices and password recovery will fail to deliver if SMTP is not configured.

6. Security requirements

• All protected API operations must authenticate the session and authorize the requested action by role and account ownership on the server.
• Mutating API calls must carry a valid CSRF token. Authentication challenges are session-bound and short-lived.
• Passwords must be stored using PHP password hashing. Password recovery tokens must be random, single-use, time-limited, and stored as cryptographic hashes.
• Use secure, HttpOnly, SameSite session cookies; enable the Secure cookie attribute when served over HTTPS.
• Use prepared SQL statements for values. Do not expose database credentials, SMTP secrets, reset tokens, or detailed internal errors to client responses.
• Configure the deployed database account with only the permissions the app requires. Restrict access to backups, logs, configuration files, and Composer metadata.

7. Operations and deployment

1. Install XAMPP or a compatible Apache, PHP, and MySQL environment; start Apache and MySQL.
2. Place the application in the Apache document root, import the fresh-install SQL, apply any required migrations, and configure the database connection.
3. Run composer install in the application directory and configure SMTP environment variables for Apache/PHP when email features are needed.
4. Set ROOMWISE_BASE_URL to the correct app URL and verify that reset emails link back to the deployed instance.
5. For production, use HTTPS, non-demo credentials, a protected database account, regular off-site backups, and access-controlled PHP/Apache logs.
6. The application uses Asia/Manila for reservation date/time processing. Confirm the server timezone and business expectations before deployment.

8. Deployment verification

• The app page loads through the Apache URL, and PHP API responses are valid JSON.
• MySQL connection and authentication work; reservations persist and role/ownership checks are enforced.
• Students and demo accounts cannot mutate reservations; unauthorized API calls are rejected server-side.
• Professor approval, CSRF validation, CAPTCHA-protected login, and session expiry behave as expected.
• SMTP can deliver a test account or password-reset email, and links use the configured public base URL.
• Backups can be created, and restoration is tested only against a safe test database or verified backup environment.