SOFTWARE REQUIREMENTS SPECIFICATION
Hospital Feedback Management System (HFMS)
PHP + MySQL Web Application





1. Introduction

1.1 Purpose
This Software Requirements Specification (SRS) document describes the functional and non-functional requirements for the Hospital Feedback Management System (HFMS). The system is designed to digitally collect, manage, analyse, and act upon patient and visitor feedback across all departments of the hospital using QR-code-based online forms.

1.2 Scope
The HFMS shall:
Collect feedback from three categories of respondents: Outpatient (OP) patients, Inpatient (IP) patients, and Other service users (e.g., pharmacy visitors, lab users, canteen users, bystanders).
Enable feedback collection via QR codes placed at strategic locations throughout the hospital campus.
Route feedback automatically to the concerned department heads for review and action.
Provide management with real-time dashboards including heat maps, trend analysis, and categorised feedback listings.
Support a five-point rating scale: Excellent, Very Good, Good, Average, and Poor for each measurable service parameter.

1.3 Definitions, Acronyms and Abbreviations

1.4 References
IEEE Std 830-1998 — IEEE Recommended Practice for Software Requirements Specifications
NABH (National Accreditation Board for Hospitals) Patient Feedback Guidelines
PHP 8.x Official Documentation — https://www.php.net
MySQL 8.x Reference Manual — https://dev.mysql.com/doc

1.5 Document Overview
Section 2 provides an overall system description. Section 3 details functional requirements. Section 4 covers non-functional requirements. Section 5 describes the database design. Section 6 outlines the system architecture. Section 7 addresses security requirements. Section 8 covers external interfaces.

2. Overall System Description

2.1 Product Perspective
The HFMS is a standalone web application accessible via standard web browsers on desktop and mobile devices. QR codes printed on posters, standees, and discharge cards redirect patients and visitors to the appropriate feedback form without requiring any app installation or login. The system integrates with the hospital's internal email infrastructure for automated notifications to department heads.

2.2 Product Functions — High-Level Summary

2.3 User Classes and Characteristics
2.3.1 Public Users (Respondents)
Patients (OP and IP) and visitors who submit feedback via QR codes. They have no login credentials and access only the public feedback form. They are expected to use mobile devices in the majority of cases. The form must be simple, intuitive, and available in multiple languages (English, Malayalam).

2.3.2 Department Heads
Clinical and administrative heads who receive feedback notifications and are responsible for reviewing feedback pertaining to their departments. They log in with individual credentials and can mark feedback as reviewed, add internal comments, escalate issues, and view department-level analytics.

2.3.3 Management Users
Senior hospital management (CEO, CMO, COO, Quality Manager, NABH Coordinator) who require a hospital-wide view. They access comprehensive analytics, heat maps, cross-department comparisons, and can generate reports. They can view all feedback but cannot modify data.

2.3.4 System Administrator
IT staff responsible for configuring the system: creating user accounts, managing departments, defining service parameters, generating QR codes, and performing system maintenance. They have full access to all modules.

2.4 Operating Environment
Server: Linux (Ubuntu 22.04 LTS or CentOS 8) with Apache 2.4+ or Nginx 1.24+
Runtime: PHP 8.1 or higher with extensions: pdo_mysql, mbstring, openssl, gd, zip
Database: MySQL 8.0 or higher
Client: Any modern web browser (Chrome 100+, Firefox 100+, Safari 15+, Edge 100+)
Mobile: Responsive design supporting iOS 14+ and Android 10+ browsers
Email: SMTP server (internal relay or third-party such as SendGrid/Mailgun)

2.5 Design and Implementation Constraints
The system must be developed using PHP 8.1  and MySQL.
QR codes must be static printable images (PNG) that encode a URL; no dynamic QR API dependency.
The public feedback form must work without JavaScript for basic submission (progressive enhancement).
All feedback data must be stored exclusively on the hospital's own servers (no third-party cloud data storage).
The system must comply with applicable Indian data protection regulations.

2.6 Assumptions and Dependencies
The hospital has an active internet connection and a registered domain for the system.
QR codes will be printed and physically placed at locations by the hospital facilities team.
Department heads have access to email for receiving notifications.
The hospital IT team will manage server provisioning and backups.

3. Functional Requirements

3.1 QR Code Management
3.1.1 QR Code Generation
FR-QR-01: The admin shall be able to create a QR code for any combination of department and feedback category (OP / IP / Other).
FR-QR-02: Each QR code shall encode a unique URL that pre-selects the department and category in the feedback form, reducing respondent effort.
FR-QR-03: QR codes shall be downloadable as high-resolution PNG images (minimum 1000x1000 pixels) suitable for printing.
FR-QR-04: The system shall generate a printable poster template (A4, A5) embedding the QR code, department name, and instruction text.
FR-QR-05: Each QR code shall have a unique tracking identifier enabling the system to record the scan location in feedback records.
FR-QR-06: The admin shall be able to deactivate a QR code, causing its URL to display a friendly "Feedback period closed" message.

3.2 Feedback Form (Public Interface)
3.2.1 Form Structure
FR-FF-01: The system shall present a single-page, mobile-optimised feedback form accessible via QR code without login.
FR-FF-02: The form shall support three respondent categories with distinct service parameter sets:


FR-FF-03: For each service parameter, the respondent shall select one rating from: Excellent, Very Good, Good, Average, or Poor (displayed as labelled radio buttons or emoji-stars).
FR-FF-04: The form shall include a free-text Comments field (max 500 characters) that is optional.
FR-FF-05: The form shall collect optional demographic fields: Patient Name, Phone Number (for follow-up), Age Group (drop-down), and Gender.
FR-FF-06: The form shall display a language toggle for English and Malayalam.
FR-FF-07: On successful submission the system shall display a Thank You message and a unique Feedback Reference Number for the respondent's record.
FR-FF-08: The system shall prevent duplicate submissions from the same device within a 2-hour window using browser cookies (soft prevention).

3.2.2 Validation
FR-FF-09: At least one service parameter rating shall be required before submission is accepted.
FR-FF-10: The phone number field, if filled, shall be validated for 10-digit Indian mobile number format.
FR-FF-11: All input shall be sanitised server-side to prevent SQL injection and XSS attacks.

3.3 Notification Engine
FR-NE-01: On each new feedback submission, the system shall send an email notification to the head of the department referenced in the feedback.
FR-NE-02: Notifications shall include: Feedback Reference Number, Category (OP/IP/Other), timestamp, overall rating, and a direct link to the feedback detail in the department dashboard.
FR-NE-03: If the overall rating is Poor or Average, the notification shall be flagged as HIGH PRIORITY and also sent to the Quality Manager and the relevant HOD's supervisor.
FR-NE-04: The system shall support optional SMS notifications via a configurable SMS gateway (e.g., Textlocal, MSG91) for critical feedback.
FR-NE-05: The admin shall be able to configure notification frequency: Instant, Hourly Digest, or Daily Digest per department.

3.4 Department Head Dashboard
FR-DH-01: Department heads shall log in with username and password credentials.
FR-DH-02: The dashboard shall display a summary panel showing: Total feedback received (today, this week, this month), breakdown by rating category, and count of unreviewed feedback.
FR-DH-03: The feedback list shall be filterable by date range, rating, respondent category (OP/IP/Other), and reviewed/unreviewed status.
FR-DH-04: On selecting a feedback record, the department head shall see the full detail: all parameter ratings, comments, date/time, QR scan location, and demographic info (if provided).
FR-DH-05: The department head shall be able to mark feedback as Reviewed and add an internal Action Note (text, max 1000 characters).
FR-DH-06: The department head shall be able to escalate a feedback record to management with a priority flag and description.
FR-DH-07: The department head shall have access to a department-level trend chart showing rating distribution over time.

3.5 Management Dashboard
3.5.1 Heat Map
FR-MG-01: The system shall render an interactive heat map displaying feedback scores across all departments on a time-configurable grid (daily, weekly, monthly).
FR-MG-02: Heat map cells shall be colour-coded: Deep Green (Excellent average) → Green → Yellow → Orange → Red (Poor average).
FR-MG-03: Clicking a heat map cell shall drill down to the feedback list for that department and period.
FR-MG-04: The heat map shall be exportable as a PNG image or embeddable in PDF reports.

3.5.2 Analytics & Trends
FR-MG-05: The management dashboard shall provide the following analytics views:
Hospital-wide CSAT trend line chart (daily/weekly/monthly).
Department comparison bar chart — average scores side by side.
Rating distribution pie/donut chart for any selected period and department.
Respondent category breakdown (OP vs IP vs Other) as stacked bar.
Service-parameter-level analysis — which specific parameters score lowest across departments.
Feedback volume trend — number of feedback submissions over time.
Top 10 recurring complaint themes extracted from comments (keyword frequency).

3.5.3 Feedback Listing
FR-MG-06: Management shall be able to view a paginated, searchable list of all feedback across all departments.
FR-MG-07: Filters available: Department, Date Range, Rating Category, Respondent Type (OP/IP/Other), Reviewed Status, and Escalated Status.
FR-MG-08: The list shall display: Reference No., Department, Respondent Type, Overall Rating, Date, and Reviewed flag.

3.5.4 Report Generation
FR-MG-09: Management shall be able to generate the following reports:
Monthly Feedback Summary Report (PDF) — department-wise rating matrix with trend graphs.
Feedback Detail Report (Excel/CSV) — raw feedback data for any selected filter combination.
NABH Audit Report (PDF) — formatted as per NABH patient satisfaction audit requirements.
Action Taken Report — lists escalated feedback with department head responses.

3.6 Admin Panel
FR-AD-01: Admin shall manage hospital departments: add, edit, deactivate departments; assign HOD users.
FR-AD-02: Admin shall manage user accounts for Department Heads and Management users: create, edit, reset password, activate/deactivate.
FR-AD-03: Admin shall configure service parameters for each feedback category (OP/IP/Other) — add, reorder, or deactivate parameters without requiring code changes.
FR-AD-04: Admin shall manage QR codes as described in Section 3.1.
FR-AD-05: Admin shall configure system settings: Hospital name, logo, SMTP email settings, SMS gateway credentials, and default language.
FR-AD-06: Admin shall view a system activity log showing logins, data exports, and configuration changes.

4. Non-Functional Requirements

4.1 Performance
NFR-P-01: The public feedback form shall load within 3 seconds on a 4G mobile connection.
NFR-P-02: Feedback submission shall be processed and the thank-you page displayed within 2 seconds.
NFR-P-03: Dashboard pages shall load within 5 seconds for data sets up to 100,000 feedback records.
NFR-P-04: The system shall support at least 100 concurrent feedback submissions without performance degradation.

4.2 Reliability and Availability
NFR-R-01: The system shall target 99.5% uptime during hospital operating hours (6 AM – 11 PM IST).
NFR-R-02: Database backups shall be performed daily and stored for a minimum of 90 days.
NFR-R-03: Feedback data shall not be lost in the event of a server crash; MySQL transaction integrity shall be enforced.

4.3 Security
NFR-S-01: All data transmission shall be encrypted using TLS 1.2 or higher (HTTPS).
NFR-S-02: All user passwords shall be stored as bcrypt hashes with a minimum cost factor of 10.
NFR-S-03: Session tokens shall expire after 30 minutes of inactivity for department head and management users.
NFR-S-04: The system shall implement CSRF token validation on all form submissions.
NFR-S-05: RBAC shall enforce that department heads can access only their own department's feedback.
NFR-S-06: Three consecutive failed login attempts shall trigger a 15-minute account lockout.
NFR-S-07: Patient demographic data shall be stored in a separate table with restricted access.

4.4 Usability
NFR-U-01: The public feedback form shall be usable without any prior instructions, targeting a minimum SUS (System Usability Scale) score of 80.
NFR-U-02: The form shall be fully responsive and thumb-friendly on screens 360px wide and above.
NFR-U-03: All form rating controls shall have clearly visible labels and sufficient tap target sizes (≥44px height).
NFR-U-04: The feedback form shall be accessible (WCAG 2.1 Level AA) for users with visual impairments.

4.5 Maintainability
NFR-M-01: The codebase shall follow PSR-12 PHP coding standards.
NFR-M-02: Service parameters, departments, and rating labels shall be database-driven and configurable without code changes.
NFR-M-03: The system shall include inline PHPDoc comments for all classes and public methods.

4.6 Scalability
NFR-SC-01: The database schema shall support horizontal partitioning of the feedback table by year to maintain query performance as data grows.
NFR-SC-02: The architecture shall allow adding new departments and QR code locations without downtime.

5. Database Design

5.1 Entity-Relationship Overview
The database schema consists of the following core entities and their relationships:


5.2 Key Table Definitions
5.2.1 feedback_sessions

5.2.2 feedback_responses (Individual Parameter Ratings)

5.2.3 Rating Encoding Convention

5.3 Indexing Strategy
Composite index on (department_id, submitted_at) for department-filtered time-series queries.
Index on overall_rating for fast filtering by satisfaction level.
Index on (qr_code_id, submitted_at) for QR-location analytics.
Index on is_reviewed for pending-review listing queries.

6. System Architecture

6.1 Application Layers

6.2 URL Structure

7. Security Requirements

7.1 Authentication and Authorisation
All internal users (Admin, HOD, Management) shall authenticate via a username/password form.
Session-based authentication shall be used with secure, HTTP-only, same-site cookies.
Password policy: minimum 8 characters, at least one uppercase, one number, one special character.
First-time login shall force a password change.
RBAC shall be implemented using a roles and permissions table; route-level middleware shall enforce permissions.

7.2 Data Protection
Patient demographic data (name, phone) shall be stored encrypted (AES-256) in the database.
The system shall provide an option to anonymise feedback older than 12 months (remove demographic data while retaining ratings).
No patient data shall be transmitted to any third-party service; QR URL tokens shall be opaque and non-guessable (UUID v4).

7.3 Input Security
All user input shall be validated server-side; client-side validation is supplementary only.
Prepared statements (PDO) shall be used for all database queries to prevent SQL injection.
Output shall be HTML-entity-encoded to prevent XSS.
File uploads (if any, e.g., logo) shall be restricted to image MIME types and scanned for anomalies.

8. External Interface Requirements

8.1 User Interfaces
Public Feedback Form: Mobile-first, single-page, no login, maximum form completion in under 3 minutes.
Department Dashboard: Web application with sidebar navigation, data tables, and inline charts.
Management Dashboard: Web application with full-screen heat map, Chart.js visualisations, and export buttons.
Admin Panel: CRUD forms with data tables and configuration panels.

8.2 Communication Interfaces
HTTPS (TLS 1.2+) for all client-server communication.
SMTP (port 587, STARTTLS) or SMTP-SSL (port 465) for outbound email.
REST API (HTTP/JSON) for SMS gateway integration.

8.3 Software Interfaces

9. Appendices

Appendix A: Suggested Development Phases

Appendix B: Risk Register

Appendix C: Glossary of Rating Terms

--- End of Document ---