Technical Requirements Document

1. Technical overview

The application is a browser-based PHP application. HTML provides the login, student, administrator, and help pages; JavaScript in assets/js/app.js drives interactive views and calls same-origin PHP endpoints; MySQL persists accounts and counseling records. Chart.js is loaded from jsDelivr for dashboard charts.

Deployment status: The repository is configured for local XAMPP-style development. Production use requires institution-managed infrastructure, hardened credentials, HTTPS, and operational and privacy review. The development defaults are not production settings.

2. Architecture and components

Serve the project through Apache/PHP, not by opening the HTML files as local files: application data requests require the PHP runtime and database.

3. Runtime requirements

The application has no JavaScript package manifest or build step in the current repository. The frontend is served as static files alongside PHP endpoints.

4. Database requirements

Create/import the schema in database/isu_counseling.sql into MySQL/MariaDB before application use. The script creates the isu_counseling database and its tables if absent; it also seeds demo administrator and student accounts. Remove demo accounts and change all default credentials before using real student information. database/sample_data.sql is optional test data.

Database account access should be limited to the required schema and operations. Use a dedicated account with a strong secret in deployed environments.

5. Interfaces and integrations

Application API

The browser calls same-origin PHP scripts under api/. The endpoints return JSON for application operations and use HTTP status codes to signal outcomes. Relevant endpoint groups include authentication/registration, CAPTCHA, student profile, student appointments, referrals, feedback, administrator approvals, administrator data, and administrator system/report/backup functions.

• Send JSON request bodies for actions that accept client data; check the response status and display a clear error on failure.
• State-changing requests in authenticated sessions require the session CSRF token in the X-CSRF-Token request header.
• Authentication and role checks are enforced by PHP endpoints; hiding a UI control is not an authorization boundary.
• Administrator reports are limited to at most 2,000 matching rows per request in the current implementation.

External services

• Chart.js CDN: jsDelivr serves the deferred Chart.js 4.6.1 script referenced by the main page.
• SMTP: Optional mail transport for administrator registration verification codes. Configure the relay and credentials in the protected mail configuration.
• Backup scheduler: Windows Task Scheduler or a hosting scheduler can run the PHP CLI backup script. The script refuses HTTP execution.

No calendar, SMS, or automated appointment-reminder delivery integration is present in the current application.

6. Security requirements

• Transport: Use HTTPS with a valid certificate for deployment. The supplied root .htaccess redirects non-local HTTP requests and sets browser security headers when the required Apache modules are enabled.
• Database credentials: The checked-in local connection uses MySQL root with an empty password. Replace this development default with a restricted database account and protected credentials before deployment.
• Authentication: Passwords are stored with PHP password hashing and checked server-side; sessions are regenerated after successful login. Approved-account state is checked before administrative access.
• Session and request protections: Session cookies are HTTP-only and SameSite=Lax; Secure is enabled when PHP detects HTTPS. State-changing session actions verify a CSRF token.
• Abuse controls: Login uses a single-use server-validated CAPTCHA. Five failed attempts for the same role/identifier trigger a 15-minute throttle.
• Authorization and data handling: Enforce role checks on APIs, scope student reads to the authenticated student, use prepared SQL statements, and escape dynamic HTML output.
• Secrets and backups: Keep database/mail credentials out of backups. Restrict backup storage to the service account and keep it outside the public web root.
• Proxy awareness: Only set ISU_COUNSELING_TRUST_PROXY=1 when requests pass through a trusted proxy that overwrites forwarded-address headers.

Pre-production requirement: Conduct an institution-approved security and privacy review. The settings and controls described here do not constitute a security certification.

7. Deployment and operations

1. Install a supported Apache/PHP stack and MySQL/MariaDB; enable the required PHP extensions.
2. Place the project in the configured web root and import database/isu_counseling.sql. Optionally import sample data only into a test database.
3. Configure least-privilege database credentials in includes/db.php using a secure deployment process; do not retain the root/blank-password development setting.
4. Configure outbound SMTP in the protected mail configuration if administrator email verification is required. Protect it from public reads and backups.
5. Enable HTTPS, restrict filesystem and database access, confirm that protected directories cannot be served, and verify that the supplied .htaccess rules are active on the chosen server.
6. Create the main administrator from the local setup flow, then remove demo accounts and credentials before any use with non-test data.
7. Run the verification checklist below on a disposable test database and document backup retention, restore ownership, and incident contacts.

Configurable environment

• ISU_COUNSELING_BACKUP_DIR — optional private directory for backup files; default is a directory under the system temporary directory.
• ISU_COUNSELING_TRUST_PROXY — set to 1 only behind a trusted proxy for forwarded client-IP logging.
• Database connection and SMTP settings are currently provided through PHP configuration files; protect these files and do not publish their values.

8. Backup and recovery

• Interactive backup and restore operations are administrator-only; restoration requires typing RESTORE and validates the stored SHA-256 hash.
• Database backups contain database records. Full backups add selected system files; database credentials and mail configuration are excluded. The SQL schema file must remain available for restoring the expected schema.
• Backup archives are stored outside the web root by default. Configure a protected backup directory, filesystem permissions, schedule, retention, and monitoring for the deployment.
• For scheduled operation, run php cli/backup_cli.php for a full backup or append database for a database-only backup.
• Test restoration on a disposable database before relying on backups. Restore replaces current records; coordinate recovery to avoid overwriting active data.

9. Compatibility and quality requirements

• Serve pages and API through one same-origin web application path; avoid file:// access for functional testing.
• Test supported current browsers for JavaScript, Fetch, native dialogs, responsive layouts, and chart rendering. Document any browser-specific limitations before release.
• Maintain readable API error responses, validate user-supplied values on the server, and do not show success when persistence fails.
• Verify that report and list views perform acceptably with the deployment's expected record volume; report queries currently cap returned records at 2,000.
• Test keyboard use, focus visibility, semantic headings and labels, zoom, and small-screen layouts against the institution's accessibility requirements.
• Define operational targets for availability, support response, retention, and recovery time/point with the institution; these targets are not configured by the current application.

10. Verification checklist

• Confirm the database imports cleanly and the application can connect using the deployment database account.
• Verify student and administrator login, CAPTCHA handling, approval restrictions, sign-out, and temporary login throttling.
• As a student, submit an appointment, support request, and feedback entry; confirm each is linked to the correct account.
• As an authorized administrator, review and update records; confirm student sessions cannot access administrator-only endpoints.
• Verify reports, filters, CSV output, print/PDF, activity-log access, and dashboard charts, including behavior when the CDN is unavailable.
• Create a database backup and full backup, check that protected credentials are absent, and restore only into a disposable test database.
• Confirm HTTPS redirect and response headers on the deployed host, and verify backup and protected configuration paths are not publicly accessible.

11. Known limitations

• Local database credentials are hard-coded in the connection helper and require deployment-specific replacement.
• Chart.js is fetched from a public CDN; dashboard charts may not load without CDN access.
• Reminders track status only and do not send email or SMS. Student password recovery and email verification are not implemented.
• The repository does not define a production deployment manifest, automated test suite, dependency lockfile, service-level objectives, or retention policy.
• Current tables include both current and legacy appointment records; integration and migration changes should account for both paths.
• The application handles sensitive counseling information and should not be used with real student data until hosting, access, retention, privacy, and recovery controls are approved.