Citizen Feedback and Sentiment Analysis System
A modern, AI-powered feedback classification and response platform designed for local government agencies (PhilHealth Cauayan City).
test
This repository contains a full-stack Django application that bridges the gap between public service feedback collection and administrative action. By combining an intuitive public submission workflow with an offline Machine Learning pipeline, the system automatically classifies the sentiment of citizen comments to surface urgent concerns instantly. Administrators are equipped with a comprehensive dashboard containing trends, analytics, action logs, granular reports, and database utilities.
Portfolio UI Previews
The screenshots below showcase the user interfaces and administrative tools of the system:
Public-Facing Portal
Figure 1: Step-by-step form for citizens to log experience ratings and comments.
Feedback Submission Success Modal
Figure 2: Success modal displaying unique tracking code after a successful submission.
Admin Login Page
Figure 3: Secure login portal for administrative staff.
Administrative Dashboard
Figure 4: Main analytics dashboard showing metrics, daily/weekly stats, and feedback trends.
Responses and Actions Management
Figure 5: Table interface to update statuses, assign categories, and add internal notes/replies.
Sentiment Analytics
Figure 6: Real-time sentiment metrics (Positive, Neutral, Negative) and trend over time.
Periodical Performance Reports
Figure 7: Detailed tabular breakdowns of experience and categorization over custom intervals.
Database and System Settings
Figure 8: Interface for database backup/restore operations, user accounts, and batch sentiment processing.
Core Features
Public-Facing Feedback Submission
- Structured Submission: Collects Service Quality Dimensions (SQD) ratings on a 3-point scale (Very Satisfactory, Satisfactory, Unsatisfactory) along with detailed feedback comments. The final sentiment combines the comment's sentiment with the rating (see below); the rating alone never sets it.
- Topics (chosen by the client, required): The client ticks at least one topic the feedback is about: Waiting time, Staff, Facilities, Document requirements, or Other. Several can be picked (e.g. "mabait ang staff pero ang tagal ng pila" is Staff + Waiting time). Topics are stored as a list in
FeedbackEntry.topics and shown on the Responses page (column and filter), as "Feedback by Topic" on the Dashboard and Reports (one entry counts once in each topic it names), in the Excel export, and in the daily email. Topics are separate from the staff-assigned Category (complaint, suggestion, compliment, concern). Entries submitted before topics existed have none.
- Unique Tracking Code: Generates an immutable, human-readable identifier (e.g., CF-YYYYMMDD-[HEX]) upon submission for tracking.
- AJAX Driven: High-fidelity modal success screen and instant code generation without page reloads.
Offline Machine Learning Sentiment Classification
-
Naive Bayes Classifier: A pre-trained scikit-learn pipeline (feedback/ml/sentiment_model.pkl, TF-IDF 1-2 grams + Multinomial Naive Bayes) trained on FiReCS + SentiTaglish, so it reads English, Tagalog, and Taglish comments offline. Training lives in training/train_sentiment_model.ipynb; Cell 19 exports the deployed model.
-
Deterministic Text Processing: Cleans text exactly as the training notebook does:
- Form header removal ("Comments:", "Commendation:").
- Lowercase normalization.
- Repeated-letter collapse (sobraaaa -> sobraa).
- Non-alphabetic characters replaced with spaces.
- English + Tagalog stopword removal (
stopwords.txt; negation words such as "not" and "hindi" are kept).
- Snowball stemming.
-
Replacing the Model: After copying in a new sentiment_model.pkl, re-label every existing comment with python manage.py reanalyze_sentiment --force.
-
Batch Re-Analysis: Built-in admin utility to re-run predictions across historical entries.
-
Comment Sentiment: The classifier reads only the comment and stores the result in comment_sentiment. A comment the model cannot classify stays Pending for manual review.
-
Final Sentiment (rating + comment): sentiment combines the rating with the comment's sentiment (feedback.services.combine_sentiment). The dashboard, reports, filters, and email use this value; the word cloud uses comment_sentiment.
| Rating | Comment Positive | Comment Neutral | Comment Negative |
|---|
| Very Satisfactory | Positive | Neutral | Negative |
| Satisfactory | Positive | Neutral | Negative |
| Unsatisfactory | Neutral | Negative | Negative |
A Negative comment is always Negative. Pending and N/A pass through unchanged, so the rating alone never produces a sentiment.
-
Deploying this change: Run python manage.py migrate, then python manage.py reanalyze_sentiment --force so existing entries get their final sentiment.
Administrative Dashboard and Management
- Key Metrics: Interactive gauges displaying total submissions and satisfaction trends.
- Response Handling: Allows administrative personnel to:
- Categorize entries into Complaint, Suggestion, Compliment, or Concern.
- Update progress status (Pending -> Reviewed -> Resolved).
- Attach administrative follow-up notes/replies.
- Action History Logs: Detailed, timeline-based status audit history logs tracking the exact operator and timestamp of every change.
Reports and Analytics
- Dynamic Timeframes: Aggregates feedback metrics dynamically across Daily, Weekly, Monthly, Quarterly, and Yearly schedules.
- Category Breakdowns: Tracks volume trends of Compliments, Suggestions, Complaints, and Concerns.
- Satisfaction Scores: Computes percentage scores to evaluate agency efficiency.
Enterprise-Grade Auditing and Backups
- Subprocess-Safe Backup Utilities: Executes safe InnoDB snapshot-based mysqldump and mysql clients.
- Zero-Exposure Credentials: Employs short-lived 0600 permission configuration option files (--defaults-extra-file) to hide database passwords from ps aux and process command histories.
- Safety Auto-Backups: Creates a pre-restoration rollback copy automatically whenever a backup upload is initiated.
Technology Stack
- Framework: Django 6.0.6 (Python 3.10+)
- Database: MySQL (Production), SQLite (Alternative/Dev)
- Machine Learning: scikit-learn, joblib, NLTK
- Analytics and Charts: Chart.js (via CDN)
- Styling and CSS: Tailwind CSS (CDN-driven), Material Icons
- Static Assets Serving: WhiteNoise
Setup and Installation
Prerequisites
- Python 3.10 or higher
- MySQL Server (if using default config) or change the settings database to SQLite for local development.
1. Clone the Repository and Configure Directory
git clone <your-repo-url>
cd philhealth-sentiment-analysis
2. Set Up Virtual Environment and Dependencies
# Create virtual environment
python -m venv venv
# Activate on Windows
.\venv\Scripts\activate
# Install requirements
pip install -r requirements.txt
3. Environment Configuration
Create a .env file in the root directory:
SECRET_KEY=your-django-secret-key
DEBUG=True
DB_NAME=philhealth_feedback
DB_USER=root
DB_PASSWORD=your_mysql_password
DB_HOST=127.0.0.1
DB_PORT=3306
BACKUP_DIR=backups
4. Database Setup and Migrations
Before running migrations, make sure your MySQL database philhealth_feedback exists.
python manage.py migrate
5. Create a Superuser
python manage.py createsuperuser
6. Run the Server
python manage.py runserver
Visit the application:
- Public Form:
http://127.0.0.1:8000/
- Admin Login and Dashboard:
http://127.0.0.1:8000/dashboard/
Project Structure
philhealth-sentiment-analysis/
│
├── assets/ # Portfolio screenshots and images
│ └── .gitkeep # Preserves directory in git
│
├── backups/ # Database backups target location
│
├── feedback/ # Public Feedback Submission App
│ ├── ml/ # ML Model, Stemmer and Stopwords files
│ │ ├── sentiment_model.pkl
│ │ └── stopwords.txt
│ ├── models.py # FeedbackEntry, FeedbackConfiguration models
│ ├── services.py # Sentiment Analysis and pre-processing logic
│ └── views.py # Public submit APIs
│
├── feedback_admin/ # Administrative Dashboard App
│ ├── backup_utils.py # JSON fixture backup and restore utilities
│ ├── context_processors.py# Global template stats (e.g. pending items)
│ ├── templates/ # Dashboard, responses, analytics HTML templates
│ └── views.py # Management and reporting logic
│
├── philhealth_feedback/ # Django core settings and routing
│ ├── settings.py
│ └── urls.py
│
├── static/ # Static assets
├── templates/ # Main theme and base layouts
├── requirements.txt # Python packages list
└── manage.py # Django CLI execution entry point
