Enhanced app with Dark Mode, Toast Notifications, SHAP Explanation, N-gram Analysis, Keyword Highlighting

.dockerignore

@@ -0,0 +1,82 @@
+# ============================================
+# Docker Ignore File
+# Exclude unnecessary files from Docker build context
+# ============================================
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info/
+dist/
+build/
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Virtual Environments
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+.venv/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Git
+.git/
+.gitignore
+.gitattributes
+
+# Documentation (not needed in container)
+*.md
+!README.md
+ARCHITECTURE.md
+DEPLOYMENT.md
+FIX_OOM_RENDER.md
+INDEX.md
+QUICKSTART.md
+RENDER_QUICKSTART.md
+TESTING_GUIDE.md
+PROJECT_STRUCTURE.txt
+PROJECT_SUMMARY.md
+
+# Database (use external PostgreSQL)
+*.db
+*.sqlite
+*.sqlite3
+app/database/*.db
+
+# Uploads (use external storage in production)
+app/static/uploads/wordclouds/*
+app/static/uploads/*.csv
+!app/static/uploads/.gitkeep
+
+# Logs
+*.log
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Render specific
+Procfile
+
+# Environment files (secrets should be in HF Settings)
+.env
+.env.*
+
+# Temporary files
+*.tmp
+tmp/
+temp/

.env.example

@@ -0,0 +1,19 @@
+# ============================================
+# ENVIRONMENT VARIABLES TEMPLATE
+# ============================================
+# Copy this file to .env for local development
+# On Render, set these in Environment Variables tab
+
+# Security (Required)
+SECRET_KEY=your-super-secret-random-key-change-this-in-production
+
+# Database (Optional - auto-configured by Render)
+# DATABASE_URL=postgresql://user:password@host:5432/database
+# Leave blank for local SQLite development
+
+# Application Settings
+PYTHON_VERSION=3.11.0
+PORT=8000
+
+# HuggingFace Cache (Optional - only for local dev)
+# HF_HOME=/path/to/huggingface/cache

.gitattributes

@@ -0,0 +1 @@
+*.pth filter=lfs diff=lfs merge=lfs -text

.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+    "python-envs.defaultEnvManager": "ms-python.python:conda",
+    "python-envs.defaultPackageManager": "ms-python.python:conda",
+    "python-envs.pythonProjects": []
+}

4.0.0

@@ -0,0 +1,6 @@
+Defaulting to user installation because normal site-packages is not writeable
+Collecting bcrypt
+  Using cached bcrypt-5.0.0-cp39-abi3-win_amd64.whl.metadata (10 kB)
+Using cached bcrypt-5.0.0-cp39-abi3-win_amd64.whl (150 kB)
+Installing collected packages: bcrypt
+Successfully installed bcrypt-5.0.0

ARCHITECTURE.md

@@ -0,0 +1,387 @@
+# 🏗️ System Architecture
+
+## High-Level Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                         FRONTEND                            │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
+│  │   Login/     │  │   Dashboard  │  │   Register   │     │
+│  │  Register    │  │   (Jinja2)   │  │    Page      │     │
+│  │  (Jinja2)    │  │ + TailwindCSS│  │  (Jinja2)    │     │
+│  └──────────────┘  └──────────────┘  └──────────────┘     │
+│         │                  │                  │             │
+│         └──────────────────┴──────────────────┘             │
+│                            │                                │
+│                   JavaScript (Fetch API)                    │
+│                     + Chart.js for viz                      │
+└────────────────────────────│────────────────────────────────┘
+                             │
+                             ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    FASTAPI BACKEND                          │
+│  ┌───────────────────────────────────────────────────┐     │
+│  │                  API ROUTERS                      │     │
+│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐       │     │
+│  │  │   Auth   │  │Prediction│  │Dashboard │       │     │
+│  │  │  Router  │  │  Router  │  │  Router  │       │     │
+│  │  │ /api/auth│  │/api/pred │  │  /pages  │       │     │
+│  │  └──────────┘  └──────────┘  └──────────┘       │     │
+│  └───────────────────────────────────────────────────┘     │
+│                            │                                │
+│                            ▼                                │
+│  ┌───────────────────────────────────────────────────┐     │
+│  │                   SERVICES                        │     │
+│  │  ┌──────────────┐  ┌──────────────┐             │     │
+│  │  │     Auth     │  │      ML      │             │     │
+│  │  │   Service    │  │   Service    │             │     │
+│  │  │(JWT, bcrypt) │  │  (Model)     │             │     │
+│  │  └──────────────┘  └──────────────┘             │     │
+│  │  ┌──────────────────────────────────┐           │     │
+│  │  │   Visualization Service          │           │     │
+│  │  │  (WordCloud, Charts)             │           │     │
+│  │  └──────────────────────────────────┘           │     │
+│  └───────────────────────────────────────────────────┘     │
+│                            │                                │
+│                            ▼                                │
+│  ┌───────────────────────────────────────────────────┐     │
+│  │              DATA LAYER                           │     │
+│  │  ┌──────────┐         ┌──────────┐               │     │
+│  │  │ SQLAlchemy│        │ Pydantic │               │     │
+│  │  │  Models   │        │ Schemas  │               │     │
+│  │  │(ORM Layer)│        │(Validation)              │     │
+│  │  └──────────┘         └────��─────┘               │     │
+│  └───────────────────────────────────────────────────┘     │
+└────────────────────────────│────────────────────────────────┘
+                             │
+                             ▼
+┌─────────────────────────────────────────────────────────────┐
+│                      DATABASE                               │
+│  ┌──────────────────────┐  ┌──────────────────────┐        │
+│  │    Users Table       │  │ PredictionHistory    │        │
+│  │  - id (PK)           │  │  - id (PK)           │        │
+│  │  - username          │  │  - user_id (FK)      │        │
+│  │  - email             │  │  - product_name      │        │
+│  │  - hashed_password   │  │  - comment           │        │
+│  │  - created_at        │  │  - predicted_rating  │        │
+│  │                      │  │  - confidence_score  │        │
+│  │                      │  │  - created_at        │        │
+│  └──────────────────────┘  └──────────────────────┘        │
+│                SQLite Database                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Request Flow Examples
+
+### 1️⃣ User Login Flow
+
+```
+User enters credentials
+        │
+        ▼
+[Login.html]
+        │
+        ▼
+POST /api/auth/login
+        │
+        ▼
+[Auth Router]
+        │
+        ▼
+[Auth Service] ──► Verify password (bcrypt)
+        │          Generate JWT token
+        ▼
+[Database] ──► Query User table
+        │
+        ▼
+Return JWT token to frontend
+        │
+        ▼
+Store token in localStorage
+        │
+        ▼
+Redirect to /dashboard
+```
+
+### 2️⃣ Single Prediction Flow
+
+```
+User enters comment
+        │
+        ▼
+[Dashboard.html]
+        │
+        ▼
+POST /api/predict/single
+(with JWT token in header)
+        │
+        ▼
+[Prediction Router]
+        │
+        ▼
+[Auth Service] ──► Verify JWT token
+        │
+        ▼
+[ML Service] ──► predict_single(comment)
+        │         (DUMMY: return random rating)
+        ▼
+[Database] ──► Save to PredictionHistory
+        │
+        ▼
+Return {rating, confidence}
+        │
+        ▼
+Display result in UI
+```
+
+### 3️⃣ Batch CSV Prediction Flow
+
+```
+User uploads CSV file
+        │
+        ▼
+[Dashboard.html]
+        │
+        ▼
+POST /api/predict/batch
+(multipart/form-data)
+        │
+        ▼
+[Prediction Router]
+        │
+        ▼
+Parse CSV ──► Extract comments
+        │
+        ▼
+[ML Service] ──► predict_batch(comments)
+        │         For each comment:
+        │         predict_single()
+        ▼
+[Visualization Service]
+        │
+        ├──► generate_wordcloud()
+        │    Save PNG to /static/uploads/
+        │
+        └──► calculate_rating_distribution()
+             Count 1⭐, 2⭐, 3⭐, 4⭐, 5⭐
+        │
+        ▼
+[Database] ──► Save all predictions
+        │
+        ▼
+Return:
+- wordcloud_url
+- rating_distribution
+- results array
+        │
+        ▼
+[Dashboard.html]
+        │
+        ├──► Render Chart.js bar chart
+        ├──► Display word cloud image
+        ├──► Populate results table
+        └──► Enable CSV download
+```
+
+---
+
+## Technology Stack Details
+
+### Backend
+```
+FastAPI (0.104.1)
+├── Auto-generates Swagger UI (/docs)
+├── Automatic data validation (Pydantic)
+├── Async support
+└── Built-in dependency injection
+
+SQLAlchemy (2.0.23)
+├── ORM for database operations
+├── Models: User, PredictionHistory
+└── Automatic table creation
+
+JWT Authentication
+├── python-jose for token generation
+├── passlib[bcrypt] for password hashing
+└── OAuth2PasswordBearer for token validation
+```
+
+### Frontend
+```
+Jinja2 Templates
+├── Server-side rendering
+├── Template inheritance (base.html)
+└── Context variables from backend
+
+TailwindCSS (CDN)
+├── Utility-first CSS framework
+├── Responsive design
+└── Custom animations
+
+Chart.js (CDN)
+├── Interactive bar charts
+└── Rating distribution visualization
+
+JavaScript (Vanilla)
+├── Fetch API for HTTP requests
+├── LocalStorage for JWT token
+└── Dynamic DOM manipulation
+```
+
+### Visualization
+```
+WordCloud (1.9.3)
+├── Generate word cloud images
+├── Vietnamese stopwords support
+└── Save to PNG files
+
+Matplotlib (3.8.2)
+├── Render word cloud to image
+└── Non-GUI backend (Agg)
+```
+
+---
+
+## File Responsibilities
+
+### Backend Files
+| File | Purpose |
+|------|---------|
+| `main.py` | FastAPI app initialization, router inclusion |
+| `config.py` | Configuration (SECRET_KEY, products list) |
+| `database.py` | SQLAlchemy engine, session management |
+| `models.py` | Database table definitions (User, PredictionHistory) |
+| `schemas.py` | Pydantic models for request/response validation |
+
+### Router Files
+| File | Purpose |
+|------|---------|
+| `routers/auth.py` | Register, login, get current user |
+| `routers/prediction.py` | Single/batch prediction, history |
+| `routers/dashboard.py` | Serve HTML pages (login, register, dashboard) |
+
+### Service Files
+| File | Purpose |
+|------|---------|
+| `services/auth_service.py` | JWT generation, password hashing, token validation |
+| `services/ml_service.py` | ML model wrapper, prediction logic (DUMMY) |
+| `services/visualization_service.py` | WordCloud generation, chart data |
+
+### Frontend Files
+| File | Purpose |
+|------|---------|
+| `templates/base.html` | Base layout with navigation, CDN imports |
+| `templates/login.html` | Login form with JWT handling |
+| `templates/register.html` | Registration form |
+| `templates/dashboard.html` | Main interface (product select, predictions, viz) |
+
+---
+
+## Security Features
+
+1. **Password Hashing:** bcrypt with salt
+2. **JWT Tokens:** Signed with SECRET_KEY (HS256)
+3. **Token Expiration:** 24 hours
+4. **Protected Routes:** Dependency injection (`get_current_user`)
+5. **CORS:** Configured for security
+6. **Input Validation:** Pydantic schemas
+
+---
+
+## Database Schema
+
+```sql
+-- Users Table
+CREATE TABLE users (
+    id INTEGER PRIMARY KEY,
+    username VARCHAR(50) UNIQUE NOT NULL,
+    email VARCHAR(100) UNIQUE NOT NULL,
+    hashed_password VARCHAR(255) NOT NULL,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+
+-- PredictionHistory Table
+CREATE TABLE prediction_history (
+    id INTEGER PRIMARY KEY,
+    user_id INTEGER NOT NULL,
+    product_name VARCHAR(200) NOT NULL,
+    comment TEXT NOT NULL,
+    predicted_rating INTEGER NOT NULL,
+    confidence_score FLOAT,
+    prediction_type VARCHAR(20) DEFAULT 'single',
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    FOREIGN KEY (user_id) REFERENCES users(id)
+);
+```
+
+---
+
+## API Response Examples
+
+### POST /api/auth/login
+```json
+{
+  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "token_type": "bearer"
+}
+```
+
+### POST /api/predict/single
+```json
+{
+  "predicted_rating": 5,
+  "confidence_score": 0.92,
+  "comment": "Sản phẩm rất tốt..."
+}
+```
+
+### POST /api/predict/batch
+```json
+{
+  "total_predictions": 20,
+  "rating_distribution": {
+    "1": 2,
+    "2": 3,
+    "3": 5,
+    "4": 6,
+    "5": 4
+  },
+  "wordcloud_url": "/static/uploads/wordclouds/wordcloud_20241125_143022.png",
+  "results": [
+    {
+      "Comment": "Sản phẩm tốt",
+      "Predicted_Rating": 5,
+      "Confidence": 0.95
+    }
+  ],
+  "csv_download_url": "/api/predict/download/1/1700924622.123"
+}
+```
+
+---
+
+## Deployment Checklist
+
+Before production:
+- [ ] Change `SECRET_KEY` in config.py
+- [ ] Set `reload=False` in uvicorn
+- [ ] Configure CORS properly
+- [ ] Use PostgreSQL instead of SQLite
+- [ ] Add environment variables (.env file)
+- [ ] Set up HTTPS
+- [ ] Add rate limiting
+- [ ] Configure logging
+- [ ] Add error monitoring
+- [ ] Set up backup strategy
+
+---
+
+This architecture provides:
+✅ **Separation of Concerns**
+✅ **Scalability** (easy to add features)
+✅ **Maintainability** (clear file structure)
+✅ **Security** (JWT, password hashing)
+✅ **Documentation** (auto-generated Swagger)
+✅ **Testing** (clear API endpoints)

DEPLOYMENT.md

@@ -0,0 +1,287 @@
+# 🚀 Deployment Guide for Render.com
+
+## Pre-Deployment Checklist
+
+- [x] Updated `requirements.txt` with `psycopg2-binary` and `gunicorn`
+- [x] Modified `database.py` for hybrid SQLite/PostgreSQL support
+- [x] Updated `config.py` to read `SECRET_KEY` from environment
+- [x] Auto-migration enabled in `main.py`
+- [ ] Push code to GitHub repository
+- [ ] Create Render account
+
+---
+
+## 📦 Step 1: Prepare Your Repository
+
+1. **Commit all changes:**
+```bash
+git add .
+git commit -m "Prepare for Render deployment"
+git push origin master
+```
+
+2. **Ensure these files exist:**
+- ✅ `requirements.txt` (with psycopg2-binary, gunicorn)
+- ✅ `main.py` (with Base.metadata.create_all)
+- ✅ `app/database.py` (hybrid support)
+- ✅ `app/config.py` (environment variables)
+
+---
+
+## 🌐 Step 2: Deploy on Render
+
+### A. Create New Web Service
+
+1. Go to https://dashboard.render.com/
+2. Click **"New +"** → **"Web Service"**
+3. Connect your GitHub repository
+4. Select your repository: `Predict-Rating-Web-App`
+
+### B. Configure Web Service
+
+Fill in the following settings:
+
+| Setting | Value |
+|---------|-------|
+| **Name** | `vietnamese-rating-prediction` (or your choice) |
+| **Region** | Singapore / Oregon (closest to you) |
+| **Branch** | `master` |
+| **Root Directory** | (leave blank) |
+| **Runtime** | `Python 3` |
+| **Build Command** | `pip install -r requirements.txt` |
+| **Start Command** | `gunicorn main:app --workers 4 --worker-class uvicorn.workers.UvicornWorker --bind 0.0.0.0:$PORT` |
+| **Instance Type** | `Free` |
+
+### C. Add Environment Variables
+
+Click **"Environment"** tab and add:
+
+| Key | Value | Notes |
+|-----|-------|-------|
+| `SECRET_KEY` | `your-super-secret-random-key-here-2024` | Generate with: `openssl rand -hex 32` |
+| `PYTHON_VERSION` | `3.11.0` | Specify Python version |
+
+**DO NOT set `DATABASE_URL` manually** - Render will auto-create it when you add PostgreSQL.
+
+---
+
+## 🗄️ Step 3: Add PostgreSQL Database
+
+### A. Create Database
+
+1. In Render Dashboard, click **"New +"** → **"PostgreSQL"**
+2. Configure:
+   - **Name:** `vietnamese-rating-db`
+   - **Database:** `rating_prediction`
+   - **User:** (auto-generated)
+   - **Region:** Same as web service
+   - **PostgreSQL Version:** `15`
+   - **Instance Type:** `Free`
+
+3. Click **"Create Database"**
+
+### B. Link Database to Web Service
+
+1. Go back to your **Web Service**
+2. Click **"Environment"** tab
+3. Click **"Add Environment Variable"**
+4. Select **"Add from Database"**
+5. Choose your `vietnamese-rating-db`
+6. It will auto-populate `DATABASE_URL`
+
+### C. Verify Connection
+
+The `database.py` will automatically:
+- Detect `DATABASE_URL` environment variable
+- Replace `postgres://` with `postgresql://`
+- Connect to PostgreSQL
+- Create all tables automatically
+
+---
+
+## 🎯 Step 4: Deploy & Monitor
+
+### A. Trigger Deployment
+
+1. After adding database, click **"Manual Deploy"** → **"Deploy latest commit"**
+2. Watch the build logs:
+   - ✅ Installing dependencies
+   - ✅ Creating database tables
+   - ✅ Starting Gunicorn server
+
+### B. Check Deployment Logs
+
+Look for these success messages:
+```
+🚀 Running in PRODUCTION mode
+🔄 Creating database tables...
+✅ Database tables created successfully!
+[INFO] Starting gunicorn
+[INFO] Booting worker with pid: 123
+```
+
+### C. Access Your Application
+
+Your app will be available at:
+```
+https://vietnamese-rating-prediction.onrender.com
+```
+
+**Important endpoints:**
+- **Dashboard:** `https://your-app.onrender.com/dashboard`
+- **API Docs (Swagger):** `https://your-app.onrender.com/docs`
+- **Health Check:** `https://your-app.onrender.com/health`
+
+---
+
+## 🔍 Troubleshooting
+
+### Issue 1: "Module not found" errors
+**Solution:** Ensure all imports are in `requirements.txt`
+```bash
+pip freeze > requirements.txt
+```
+
+### Issue 2: "Connection refused" to database
+**Solution:** 
+- Verify `DATABASE_URL` is set in environment variables
+- Check database status in Render dashboard
+- Restart web service
+
+### Issue 3: "Port binding" errors
+**Solution:** Use `$PORT` environment variable:
+```bash
+gunicorn main:app --bind 0.0.0.0:$PORT
+```
+
+### Issue 4: ML model takes too long to load
+**Solution:** Render Free Tier has limited RAM (512MB). Consider:
+- Using a lighter model
+- Lazy loading (load model on first request)
+- Upgrading to Starter plan ($7/month)
+
+### Issue 5: Static files not loading
+**Solution:** Ensure `app/static/` directory exists and is committed to git
+
+---
+
+## ⚙️ Alternative Start Commands
+
+### Option 1: Basic Uvicorn (Single Worker)
+```bash
+uvicorn main:app --host 0.0.0.0 --port $PORT
+```
+
+### Option 2: Gunicorn with Uvicorn Workers (Recommended)
+```bash
+gunicorn main:app --workers 4 --worker-class uvicorn.workers.UvicornWorker --bind 0.0.0.0:$PORT
+```
+
+### Option 3: Gunicorn with Auto-scaling Workers
+```bash
+gunicorn main:app --workers 2 --worker-class uvicorn.workers.UvicornWorker --bind 0.0.0.0:$PORT --timeout 120
+```
+
+---
+
+## 📊 Performance Optimization
+
+### 1. Reduce Model Loading Time
+Edit `app/services/ml_service.py`:
+```python
+# Lazy load model on first request instead of on startup
+class MLPredictionService:
+    def __init__(self):
+        self.model = None
+        self.tokenizer = None
+    
+    def _ensure_loaded(self):
+        if self.model is None:
+            # Load model here
+            pass
+```
+
+### 2. Enable Connection Pooling
+Already configured in `database.py`:
+```python
+engine = create_engine(
+    DATABASE_URL,
+    pool_pre_ping=True,
+    pool_recycle=300
+)
+```
+
+### 3. Use Caching for Predictions
+Consider adding Redis (Render add-on) for caching frequent predictions.
+
+---
+
+## 🔒 Security Checklist
+
+- [ ] Set strong `SECRET_KEY` in environment variables
+- [ ] Restrict CORS origins in production (edit `main.py`)
+- [ ] Enable HTTPS (automatic on Render)
+- [ ] Set up database backups (Render PostgreSQL backups)
+- [ ] Add rate limiting (consider using Render's DDoS protection)
+- [ ] Review and sanitize all user inputs
+
+---
+
+## 💰 Cost Breakdown (Free Tier)
+
+| Service | Cost | Limitations |
+|---------|------|-------------|
+| Web Service | FREE | 512MB RAM, Sleeps after 15min inactivity |
+| PostgreSQL | FREE | 1GB storage, 97 connections |
+| Bandwidth | FREE | 100GB/month |
+
+**Upgrade Considerations:**
+- If app sleeps: Upgrade to Starter ($7/month, always-on)
+- If RAM issues: Upgrade to Standard ($25/month, 2GB RAM)
+- If storage full: Upgrade database ($7/month, 10GB)
+
+---
+
+## 🎓 Post-Deployment Testing
+
+### Test 1: Health Check
+```bash
+curl https://your-app.onrender.com/health
+```
+Expected: `{"status":"healthy","service":"rating-prediction","version":"1.0.0"}`
+
+### Test 2: Swagger UI
+Visit: `https://your-app.onrender.com/docs`
+- Try registering a user
+- Login to get JWT token
+- Test prediction endpoints
+
+### Test 3: Database Connection
+Check logs for:
+```
+🚀 Production Mode: Using PostgreSQL
+✅ Database tables created successfully!
+```
+
+---
+
+## 📚 Additional Resources
+
+- **Render Docs:** https://render.com/docs/deploy-fastapi
+- **PostgreSQL Guide:** https://render.com/docs/databases
+- **Environment Variables:** https://render.com/docs/environment-variables
+- **Custom Domains:** https://render.com/docs/custom-domains
+
+---
+
+## 🆘 Support
+
+If you encounter issues:
+1. Check Render logs (Dashboard → Logs tab)
+2. Review this guide carefully
+3. Check Render community forum: https://community.render.com/
+4. Contact Render support (for paid plans)
+
+---
+
+**Good luck with your deployment! 🚀**

Dockerfile

@@ -0,0 +1,61 @@
+# ============================================
+# Dockerfile for Hugging Face Spaces (Docker SDK)
+# Optimized for FastAPI + Heavy ML Model (>500MB)
+# ============================================
+
+FROM python:3.10-slim
+
+RUN apt-get update && apt-get install -y \
+    fonts-dejavu \
+    fonts-dejavu-core \
+    fonts-dejavu-extra \
+    fontconfig \
+    && rm -rf /var/lib/apt/lists/*
+    
+# Set environment variables
+ENV PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PIP_DISABLE_PIP_VERSION_CHECK=1
+
+# Create non-root user (REQUIRED by Hugging Face Spaces)
+# HF Spaces runs containers as user ID 1000
+RUN useradd -m -u 1000 user
+
+# Set working directory
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    build-essential \
+    gcc \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements first (for better Docker layer caching)
+COPY --chown=user:user requirements.txt .
+
+# Install Python dependencies as root (before switching to user)
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application code
+COPY --chown=user:user . .
+
+# Create necessary directories with proper permissions
+RUN mkdir -p /app/app/static/uploads/wordclouds && \
+    mkdir -p /app/app/database && \
+    chmod -R 777 /app/app/static/uploads && \
+    chmod -R 777 /app/app/database
+
+# Switch to non-root user
+USER user
+
+# Expose port 7860 (REQUIRED by Hugging Face Spaces)
+EXPOSE 7860
+
+# Health check (optional but recommended)
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD python -c "import requests; requests.get('http://localhost:7860/docs')"
+
+# Start the FastAPI application
+# CRITICAL: Must listen on 0.0.0.0:7860 for Hugging Face Spaces
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "7860"]

HUGGING_FACE_DEPLOYMENT.md

@@ -0,0 +1,258 @@
+# 🚀 Rating Prediction System - Hugging Face Spaces Deployment
+
+[![Hugging Face Spaces](https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Spaces-blue)](https://huggingface.co/spaces)
+[![FastAPI](https://img.shields.io/badge/FastAPI-0.104.1-009688.svg?style=flat&logo=FastAPI&logoColor=white)](https://fastapi.tiangolo.com)
+[![Docker](https://img.shields.io/badge/Docker-Enabled-2496ED?logo=docker&logoColor=white)](https://www.docker.com/)
+
+A production-ready FastAPI application for predicting product ratings from Vietnamese comments using PhoBERT. This Space uses Docker SDK for deploying heavy ML models (>500MB) with 16GB RAM.
+
+---
+
+## 🎯 Features
+
+- 🤖 **ML-Powered Predictions**: PhoBERT-based sentiment analysis
+- 📊 **Interactive Dashboard**: Real-time visualizations with Chart.js
+- 💬 **Batch Processing**: Upload CSV files for bulk predictions
+- 🔐 **Secure Authentication**: JWT-based user management
+- 📈 **Analytics**: Word clouds and rating distributions
+- 🗄️ **External Database**: PostgreSQL support (Render/Neon)
+
+---
+
+## 🔧 Configuration Required
+
+### Required Environment Variables
+
+**CRITICAL:** Before deploying to Hugging Face Spaces, you MUST add these environment variables in the **Settings** tab:
+
+#### 1. DATABASE_URL (REQUIRED)
+```
+DATABASE_URL=postgresql://username:password@host:port/database
+```
+**Real External Db url**
+```
+DATABASE_URL=postgresql://rating_prediction_user:2p3Xv9mKFt3DDFs9OVWDrw8ARHkevTSw@dpg-d4mfq13uibrs738i6jl0-a.singapore-postgres.render.com/rating_prediction
+```
+**Example from Render:**
+```
+DATABASE_URL=postgresql://user:pass@dpg-xxxxx.oregon-postgres.render.com/dbname
+```
+
+**Example from Neon:**
+```
+DATABASE_URL=postgresql://user:pass@ep-xxxxx.us-east-2.aws.neon.tech/dbname?sslmode=require
+```
+
+⚠️ **Important Notes:**
+- The URL MUST start with `postgresql://` (NOT `postgres://`)
+- If your provider gives you `postgres://`, the app will auto-convert it
+- Include `?sslmode=require` for secure connections (recommended)
+
+#### 2. SECRET_KEY (REQUIRED)
+```
+SECRET_KEY=your-super-secret-jwt-key-change-this-in-production-min-32-chars
+```
+
+**Generate a secure key:**
+```bash
+python -c "import secrets; print(secrets.token_urlsafe(32))"
+```
+
+**Real SECRECT_KEY:**
+nz0qzAJoIiRQ3v62SAq8g94JAFtfmf-GSU6dkluKtKA
+
+⚠️ **Security:**
+- NEVER commit this key to Git
+- Use a cryptographically secure random string
+- Minimum 32 characters recommended
+
+---
+
+## 📋 Deployment Steps
+
+### Step 1: Create a New Space
+1. Go to https://huggingface.co/new-space
+2. Choose **Docker** as the SDK
+3. Select **CPU Basic** (16GB RAM - Free)
+4. Make the Space **Public** or **Private**
+
+### Step 2: Configure Environment Variables
+1. Go to your Space's **Settings** tab
+2. Scroll to **Repository Secrets**
+3. Add the following secrets:
+   - `DATABASE_URL` → Your PostgreSQL connection string
+   - `SECRET_KEY` → Your JWT secret key
+
+### Step 3: Push Your Code
+```bash
+# Clone your Space repository
+git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
+cd YOUR_SPACE_NAME
+
+# Copy your project files
+cp -r /path/to/PredictRating/* .
+
+# Commit and push
+git add .
+git commit -m "Initial deployment"
+git push
+```
+
+### Step 4: Wait for Build
+- Hugging Face will automatically build your Docker image
+- Build time: ~5-10 minutes (depending on model size)
+- Check build logs in the **Logs** tab
+
+### Step 5: Access Your App
+- Your app will be available at: `https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME`
+- The app runs on port **7860** (handled automatically)
+
+---
+
+## 🗄️ Database Setup
+
+### Option A: Render PostgreSQL (Recommended)
+1. Create a free PostgreSQL database on [Render](https://render.com)
+2. Go to **Dashboard** → **New** → **PostgreSQL**
+3. Copy the **External Database URL**
+4. Add it as `DATABASE_URL` in HF Spaces Settings
+
+### Option B: Neon PostgreSQL
+1. Create a free database on [Neon](https://neon.tech)
+2. Copy the connection string
+3. Ensure it includes `?sslmode=require`
+4. Add it as `DATABASE_URL` in HF Spaces Settings
+
+### Database Initialization
+The app automatically:
+- Creates tables on first run
+- Supports both SQLite (local dev) and PostgreSQL (production)
+- No manual migrations needed
+
+---
+
+## 🐳 Docker Configuration
+
+### Port Requirements
+- **CRITICAL:** Hugging Face Spaces requires port **7860**
+- The Dockerfile is pre-configured correctly
+- DO NOT change the port in `CMD` instruction
+
+### User Permissions
+- Hugging Face runs containers as user ID **1000**
+- The Dockerfile creates a `user` account
+- All files are owned by this user
+
+### Storage
+- `/app/static/uploads/` is writable (for word clouds)
+- `/app/database/` is writable (for local SQLite fallback)
+- Consider using external storage (S3/Cloudinary) for production
+
+---
+
+## 🧪 Testing Locally Before Deployment
+
+### Test with Docker
+```bash
+# Build the Docker image
+docker build -t rating-prediction .
+
+# Run with environment variables
+docker run -p 7860:7860 \
+  -e DATABASE_URL="postgresql://user:pass@host/db" \
+  -e SECRET_KEY="your-secret-key" \
+  rating-prediction
+
+# Access at http://localhost:7860
+```
+
+### Test Database Connection
+```bash
+# Inside container
+docker exec -it <container_id> python -c "
+from app.database import engine
+print('✅ Database connected:', engine.url)
+"
+```
+
+---
+
+## 📊 Monitoring & Logs
+
+### View Logs in Hugging Face
+1. Go to your Space
+2. Click the **Logs** tab
+3. Monitor startup and runtime logs
+
+### Expected Startup Messages
+```
+🚀 Production Mode: Using PostgreSQL
+INFO:     Started server process [1]
+INFO:     Uvicorn running on http://0.0.0.0:7860
+```
+
+---
+
+## 🔒 Security Checklist
+
+- ✅ `SECRET_KEY` stored as HF Secret (not in code)
+- ✅ `DATABASE_URL` stored as HF Secret (not in code)
+- ✅ PostgreSQL uses SSL (`sslmode=require`)
+- ✅ Passwords hashed with bcrypt
+- ✅ JWT tokens expire after 24 hours
+- ✅ Docker runs as non-root user
+
+---
+
+## 🐛 Troubleshooting
+
+### Issue: "Application startup failed"
+**Solution:** Check logs for database connection errors. Verify `DATABASE_URL` is correct.
+
+### Issue: "502 Bad Gateway"
+**Solution:** App may be starting. Wait 2-3 minutes for heavy model loading.
+
+### Issue: "Database connection refused"
+**Solution:** Ensure your PostgreSQL database is accessible from external IPs. Check firewall rules.
+
+### Issue: "No module named 'app'"
+**Solution:** Ensure all files are copied correctly. Check Dockerfile `WORKDIR` is `/app`.
+
+### Issue: "Port 7860 already in use"
+**Solution:** Only relevant for local testing. Stop other containers on that port.
+
+---
+
+## 📚 API Documentation
+
+Once deployed, access:
+- **Swagger UI**: `https://your-space.hf.space/docs`
+- **ReDoc**: `https://your-space.hf.space/redoc`
+
+### Key Endpoints
+- `POST /api/auth/register` - Create new user
+- `POST /api/auth/login` - Login and get JWT token
+- `POST /api/predict/single` - Predict single comment
+- `POST /api/predict/batch` - Upload CSV for batch predictions
+- `GET /api/predict/history` - View prediction history
+
+---
+
+## 🆘 Support
+
+If you encounter issues:
+1. Check the **Logs** tab in your Space
+2. Verify environment variables in **Settings**
+3. Test database connection from your local machine
+4. Review [FastAPI Docs](https://fastapi.tiangolo.com)
+5. Check [Hugging Face Spaces Docs](https://huggingface.co/docs/hub/spaces-overview)
+
+---
+
+## 📄 License
+
+This project is deployed under the terms specified in your Space settings.
+
+---
+
+**Built with ❤️ using FastAPI, PhoBERT, and Hugging Face Spaces**

INDEX.md

@@ -0,0 +1,296 @@
+# 📖 Complete Documentation Index
+
+Welcome to the **Vietnamese Product Rating Prediction System** documentation!
+
+---
+
+## 🚀 Quick Start (New Users)
+
+If you're just getting started, read these files in order:
+
+1. **[QUICKSTART.md](QUICKSTART.md)** ⚡
+   - Installation instructions
+   - How to run the application
+   - First-time usage guide
+   - **Start here!**
+
+2. **[TESTING_GUIDE.md](TESTING_GUIDE.md)** ✅
+   - Step-by-step testing procedures
+   - Expected results for each test
+   - Troubleshooting common issues
+
+3. **[PROJECT_SUMMARY.md](PROJECT_SUMMARY.md)** 📋
+   - Overview of all features
+   - What has been built
+   - How to replace dummy ML model
+
+---
+
+## 📚 Detailed Documentation
+
+### For Understanding the System
+
+- **[README.md](README.md)** 📖
+  - Complete project documentation
+  - Features, setup, usage
+  - API endpoints
+  - Database schema
+  - CSV file format
+
+- **[ARCHITECTURE.md](ARCHITECTURE.md)** 🏗️
+  - System architecture diagrams
+  - Request flow examples
+  - Technology stack details
+  - File responsibilities
+  - Security features
+
+---
+
+## 🎯 For Different Purposes
+
+### I want to... run the application
+→ Read: **[QUICKSTART.md](QUICKSTART.md)**
+
+### I want to... test all features
+→ Read: **[TESTING_GUIDE.md](TESTING_GUIDE.md)**
+
+### I want to... understand the code structure
+→ Read: **[ARCHITECTURE.md](ARCHITECTURE.md)**
+
+### I want to... replace the dummy ML model
+→ Read: **[PROJECT_SUMMARY.md](PROJECT_SUMMARY.md)** (section: "Replace Dummy ML Model")
+
+### I want to... demo to my teacher
+→ Read: **[TESTING_GUIDE.md](TESTING_GUIDE.md)** (section: "Demo Checklist for Teacher")
+
+### I want to... understand all features
+→ Read: **[README.md](README.md)** (section: "Features")
+
+### I want to... see API documentation
+→ Run app, then visit: **http://localhost:8000/docs**
+
+---
+
+## 📁 Project Files Overview
+
+### Documentation Files
+```
+├── README.md              # Main documentation
+├── QUICKSTART.md          # Quick setup guide
+├── PROJECT_SUMMARY.md     # Feature summary
+├── TESTING_GUIDE.md       # Testing procedures
+├── ARCHITECTURE.md        # System architecture
+└── INDEX.md              # This file (navigation)
+```
+
+### Code Files
+```
+├── main.py                # FastAPI entry point
+├── requirements.txt       # Python dependencies
+├── sample_comments.csv    # Test data
+├── .gitignore            # Git ignore rules
+│
+└── app/
+    ├── config.py         # Configuration
+    ├── database.py       # Database setup
+    ├── models.py         # Database models
+    ├── schemas.py        # Pydantic schemas
+    │
+    ├── routers/          # API endpoints
+    │   ├── auth.py
+    │   ├── prediction.py
+    │   └── dashboard.py
+    │
+    ├── services/         # Business logic
+    │   ├── auth_service.py
+    │   ├── ml_service.py
+    │   └── visualization_service.py
+    │
+    ├── templates/        # HTML templates
+    │   ├── base.html
+    │   ├── login.html
+    │   ├── register.html
+    │   └── dashboard.html
+    │
+    └── static/           # Static files
+        ├── css/
+        ├── js/
+        └── uploads/
+```
+
+---
+
+## 🎓 For Students (Project Presentation)
+
+### Before Presentation
+1. Read **[QUICKSTART.md](QUICKSTART.md)** to set up
+2. Test everything using **[TESTING_GUIDE.md](TESTING_GUIDE.md)**
+3. Review **[PROJECT_SUMMARY.md](PROJECT_SUMMARY.md)** for highlights
+
+### During Presentation
+1. **Show Swagger UI** (bonus points!) → http://localhost:8000/docs
+2. **Demo user journey:**
+   - Register → Login
+   - Single prediction
+   - Batch CSV with visualizations
+3. **Explain architecture** using **[ARCHITECTURE.md](ARCHITECTURE.md)**
+
+### Key Points to Mention
+✅ FastAPI with automatic API documentation  
+✅ JWT authentication for security  
+✅ RESTful API design  
+✅ Data visualization (Chart.js + WordCloud)  
+✅ Separation of concerns (clean architecture)  
+✅ Database relationships and ORM  
+
+---
+
+## 🔧 For Developers
+
+### Understanding the Codebase
+1. **[ARCHITECTURE.md](ARCHITECTURE.md)** - System overview
+2. **[README.md](README.md)** - Detailed documentation
+3. Code files (with inline comments)
+
+### Modifying the System
+
+**To replace ML model:**
+→ Edit: `app/services/ml_service.py`
+→ See: **[PROJECT_SUMMARY.md](PROJECT_SUMMARY.md)** section "Replace Dummy ML Model"
+
+**To add products:**
+→ Edit: `app/config.py` → `PRODUCTS` list
+
+**To add Vietnamese stopwords:**
+→ Edit: `app/services/visualization_service.py` → `self.stopwords`
+
+**To change styling:**
+→ Edit: `app/templates/*.html` (TailwindCSS classes)
+
+**To add API endpoints:**
+→ Create route in: `app/routers/*.py`
+
+---
+
+## 📊 Key Features Reference
+
+| Feature | File | Documentation |
+|---------|------|---------------|
+| User Authentication | `app/routers/auth.py` | [README.md](README.md) |
+| Single Prediction | `app/routers/prediction.py` | [README.md](README.md) |
+| Batch Prediction | `app/routers/prediction.py` | [README.md](README.md) |
+| WordCloud | `app/services/visualization_service.py` | [ARCHITECTURE.md](ARCHITECTURE.md) |
+| Database Models | `app/models.py` | [README.md](README.md) |
+| ML Service | `app/services/ml_service.py` | [PROJECT_SUMMARY.md](PROJECT_SUMMARY.md) |
+
+---
+
+## 🐛 Troubleshooting
+
+For common issues and solutions:
+→ **[TESTING_GUIDE.md](TESTING_GUIDE.md)** (Troubleshooting section)
+
+For API errors:
+→ Check Swagger UI: http://localhost:8000/docs
+
+For understanding error messages:
+→ **[ARCHITECTURE.md](ARCHITECTURE.md)** (Request Flow section)
+
+---
+
+## 📞 Quick Reference Commands
+
+```bash
+# Install dependencies
+pip install -r requirements.txt
+
+# Run application
+python main.py
+
+# Access Swagger UI
+# Open: http://localhost:8000/docs
+
+# Access dashboard
+# Open: http://localhost:8000/dashboard
+
+# Test with sample data
+# Upload: sample_comments.csv
+```
+
+---
+
+## ✅ Checklist for Teacher Demo
+
+Before presenting to teacher:
+
+- [ ] All dependencies installed (`pip install -r requirements.txt`)
+- [ ] Application runs successfully (`python main.py`)
+- [ ] Can access Swagger UI (http://localhost:8000/docs)
+- [ ] Can register and login
+- [ ] Single prediction works
+- [ ] Batch CSV prediction works
+- [ ] Charts and word cloud display correctly
+- [ ] CSV download works
+- [ ] Understand system architecture
+- [ ] Can explain how to replace ML model
+
+---
+
+## 🎯 Learning Outcomes
+
+After completing this project, you will understand:
+
+1. **FastAPI Framework**
+   - Route definition
+   - Dependency injection
+   - Automatic API documentation
+   - Request/response validation
+
+2. **Authentication**
+   - JWT tokens
+   - Password hashing (bcrypt)
+   - Protected routes
+
+3. **Database**
+   - SQLAlchemy ORM
+   - Model relationships
+   - CRUD operations
+
+4. **Frontend**
+   - Jinja2 templating
+   - TailwindCSS styling
+   - JavaScript Fetch API
+   - Chart.js visualization
+
+5. **Software Architecture**
+   - Separation of concerns
+   - Service layer pattern
+   - RESTful API design
+
+---
+
+## 📧 Documentation Feedback
+
+If any documentation is unclear or missing information:
+1. Check other documentation files
+2. Look at code comments
+3. Consult with your instructor
+
+---
+
+## 🎉 You're All Set!
+
+You now have:
+✅ Complete working application  
+✅ Comprehensive documentation  
+✅ Testing guide  
+✅ Architecture documentation  
+✅ Demo preparation materials  
+
+**Good luck with your project! 🎓**
+
+---
+
+*Last Updated: November 25, 2024*  
+*Project: Vietnamese Product Rating Prediction System*  
+*Framework: FastAPI + Jinja2 + TailwindCSS*

PROJECT_STRUCTURE.txt

@@ -0,0 +1,326 @@
+# 📁 Complete Project Structure
+
+```
+PredictRating/
+│
+├── 📄 main.py                          # FastAPI application entry point
+├── 📄 requirements.txt                 # Python dependencies
+├── 📄 .gitignore                       # Git ignore rules
+│
+├── 📄 sample_comments.csv              # Sample test data (20 Vietnamese comments)
+│
+├── 📚 DOCUMENTATION FILES
+│   ├── 📖 README.md                    # Main documentation (complete guide)
+│   ├── ⚡ QUICKSTART.md                # Quick setup and first run guide
+│   ├── 📋 PROJECT_SUMMARY.md           # Feature overview and highlights
+│   ├── ✅ TESTING_GUIDE.md             # Step-by-step testing procedures
+│   ├── 🏗️ ARCHITECTURE.md              # System architecture and design
+│   ├── 📑 INDEX.md                     # Documentation navigation (this file)
+│   └── 📁 PROJECT_STRUCTURE.txt        # This visual tree structure
+│
+└── 📁 app/                             # Main application package
+    │
+    ├── 📄 __init__.py                  # Package initializer
+    ├── 📄 config.py                    # Configuration (SECRET_KEY, PRODUCTS, paths)
+    ├── 📄 database.py                  # SQLAlchemy engine & session management
+    ├── 📄 models.py                    # Database models (User, PredictionHistory)
+    ├── 📄 schemas.py                   # Pydantic validation schemas
+    │
+    ├── 📁 routers/                     # API Route Handlers
+    │   ├── 📄 __init__.py
+    │   ├── 📄 auth.py                  # Authentication endpoints
+    │   │                               #   - POST /api/auth/register
+    │   │                               #   - POST /api/auth/login
+    │   │                               #   - GET  /api/auth/me
+    │   │
+    │   ├── 📄 prediction.py            # Prediction endpoints
+    │   │                               #   - POST /api/predict/single
+    │   │                               #   - POST /api/predict/batch
+    │   │                               #   - GET  /api/predict/history
+    │   │
+    │   └── 📄 dashboard.py             # Frontend page routes
+    │                                   #   - GET  /
+    │                                   #   - GET  /login
+    │                                   #   - GET  /register
+    │                                   #   - GET  /dashboard
+    │
+    ├── 📁 services/                    # Business Logic Layer
+    │   ├── 📄 __init__.py
+    │   │
+    │   ├── 📄 auth_service.py          # Authentication service
+    │   │                               #   - Password hashing (bcrypt)
+    │   │                               #   - JWT token generation
+    │   │                               #   - Token validation
+    │   │                               #   - Get current user
+    │   │
+    │   ├── 📄 ml_service.py            # ML Prediction service
+    │   │                               #   - predict_single() [DUMMY]
+    │   │                               #   - predict_batch()  [DUMMY]
+    │   │                               #   - preprocess()
+    │   │                               #   ⚠️ REPLACE WITH YOUR REAL MODEL
+    │   │
+    │   └── 📄 visualization_service.py # Visualization service
+    │                                   #   - generate_wordcloud()
+    │                                   #   - calculate_rating_distribution()
+    │                                   #   - get_top_words()
+    │
+    ├── 📁 templates/                   # Jinja2 HTML Templates
+    │   ├── 📄 base.html                # Base layout template
+    │   │                               #   - TailwindCSS CDN
+    │   │                               #   - Chart.js CDN
+    │   │                               #   - Font Awesome icons
+    │   │                               #   - Header/Footer structure
+    │   │
+    │   ├── 📄 login.html               # Login page
+    │   │                               #   - Login form
+    │   │                               #   - JWT token handling
+    │   │                               #   - Link to register
+    │   │
+    │   ├── 📄 register.html            # Registration page
+    │   │                               #   - Registration form
+    │   │                               #   - Form validation
+    │   │                               #   - Link to login
+    │   │
+    │   └── 📄 dashboard.html           # Main dashboard
+    │                                   #   - Product selection dropdown
+    │                                   #   - Single/Batch tabs
+    │                                   #   - Prediction forms
+    │                                   #   - Chart.js visualization
+    │                                   #   - WordCloud display
+    │                                   #   - Results table
+    │                                   #   - CSV download
+    │
+    ├── 📁 static/                      # Static Files
+    │   ├── 📁 css/
+    │   │   └── 📄 style.css            # Custom CSS (placeholder)
+    │   │
+    │   ├── 📁 js/
+    │   │   └── 📄 main.js              # Custom JavaScript (placeholder)
+    │   │
+    │   └── 📁 uploads/                 # User uploads directory
+    │       ├── 📄 .gitkeep             # Keep directory in git
+    │       └── 📁 wordclouds/          # Generated word cloud images
+    │
+    └── 📁 database/                    # Database Storage
+        ├── 📄 .gitkeep                 # Keep directory in git
+        └── 🗄️ rating_prediction.db     # SQLite database (created on first run)
+                                        #   Tables:
+                                        #     - users
+                                        #     - prediction_history
+```
+
+---
+
+## 📊 File Count Summary
+
+| Category | Count | Files |
+|----------|-------|-------|
+| **Documentation** | 7 | README, QUICKSTART, PROJECT_SUMMARY, TESTING_GUIDE, ARCHITECTURE, INDEX, PROJECT_STRUCTURE |
+| **Core Python** | 5 | main.py, config.py, database.py, models.py, schemas.py |
+| **Routers** | 3 | auth.py, prediction.py, dashboard.py |
+| **Services** | 3 | auth_service.py, ml_service.py, visualization_service.py |
+| **Templates** | 4 | base.html, login.html, register.html, dashboard.html |
+| **Static** | 2 | style.css, main.js |
+| **Config** | 3 | requirements.txt, .gitignore, .gitkeep files |
+| **Test Data** | 1 | sample_comments.csv |
+| **Total** | **28** | |
+
+---
+
+## 🎯 Key Directories Explained
+
+### `/app/routers/` - API Endpoints
+- **Purpose:** Handle HTTP requests and responses
+- **Pattern:** Each router handles a specific domain (auth, prediction, dashboard)
+- **Uses:** FastAPI decorators (@router.get, @router.post)
+
+### `/app/services/` - Business Logic
+- **Purpose:** Core functionality separated from HTTP layer
+- **Pattern:** Service classes with dependency injection
+- **Uses:** Called by routers, interacts with database and external services
+
+### `/app/templates/` - Frontend Views
+- **Purpose:** HTML templates for user interface
+- **Pattern:** Jinja2 template inheritance (extends base.html)
+- **Uses:** Rendered by FastAPI's Jinja2Templates
+
+### `/app/static/` - Static Assets
+- **Purpose:** CSS, JavaScript, images, uploads
+- **Pattern:** Mounted as static files in FastAPI
+- **URL:** Accessible at `/static/...`
+
+### `/app/database/` - Database Storage
+- **Purpose:** SQLite database file location
+- **Pattern:** Created automatically by SQLAlchemy
+- **Schema:** Users, PredictionHistory tables
+
+---
+
+## 🔗 File Dependencies
+
+### main.py depends on:
+- `app.database` (create tables)
+- `app.routers.*` (include routers)
+- `fastapi`, `uvicorn`
+
+### Routers depend on:
+- `app.database` (get_db)
+- `app.models` (User, PredictionHistory)
+- `app.schemas` (validation)
+- `app.services.*` (business logic)
+
+### Services depend on:
+- `app.config` (settings)
+- `app.models` (database access)
+- External libraries (bcrypt, jose, wordcloud)
+
+### Templates depend on:
+- TailwindCSS (CDN)
+- Chart.js (CDN)
+- Font Awesome (CDN)
+- JavaScript Fetch API
+
+---
+
+## 📝 Important Files to Modify
+
+### To replace ML model:
+```
+app/services/ml_service.py
+└── Update: __init__(), predict_single(), predict_batch()
+```
+
+### To add products:
+```
+app/config.py
+└── Update: PRODUCTS list
+```
+
+### To change UI styling:
+```
+app/templates/*.html
+└── Edit: TailwindCSS classes
+```
+
+### To add API endpoints:
+```
+app/routers/*.py
+└── Add: New route functions
+```
+
+### To modify Vietnamese stopwords:
+```
+app/services/visualization_service.py
+└── Update: self.stopwords set
+```
+
+---
+
+## 🚀 Execution Flow
+
+1. **Start:** `python main.py`
+2. **Load:** main.py imports all modules
+3. **Initialize:** Create database tables
+4. **Mount:** Static files and templates
+5. **Include:** All routers (auth, prediction, dashboard)
+6. **Run:** Uvicorn server on port 8000
+7. **Ready:** Application accessible at http://localhost:8000
+
+---
+
+## 🔐 Generated Files (Not in Git)
+
+These files are created when you run the application:
+
+```
+app/database/rating_prediction.db    # SQLite database
+app/static/uploads/wordclouds/*.png  # Generated word cloud images
+__pycache__/                         # Python bytecode
+*.pyc                                # Compiled Python files
+```
+
+These are ignored by `.gitignore`
+
+---
+
+## 📦 External Dependencies (from requirements.txt)
+
+```
+fastapi              # Web framework
+uvicorn              # ASGI server
+sqlalchemy           # ORM
+python-jose          # JWT
+passlib              # Password hashing
+pydantic             # Validation
+jinja2               # Templates
+wordcloud            # Word clouds
+matplotlib           # Plotting
+python-multipart     # File uploads
+```
+
+---
+
+## 🎨 Frontend Stack
+
+```
+HTML
+├── Jinja2 templates (server-side rendering)
+└── Semantic HTML5
+
+CSS
+├── TailwindCSS 3.x (CDN)
+└── Custom animations (in base.html)
+
+JavaScript
+├── Vanilla JS (no frameworks)
+├── Fetch API (HTTP requests)
+├── Chart.js (visualizations)
+└── LocalStorage (JWT tokens)
+```
+
+---
+
+## 🗄️ Database Schema
+
+```
+users
+├── id (INTEGER, PRIMARY KEY)
+├── username (VARCHAR(50), UNIQUE)
+├── email (VARCHAR(100), UNIQUE)
+├── hashed_password (VARCHAR(255))
+└── created_at (DATETIME)
+
+prediction_history
+├── id (INTEGER, PRIMARY KEY)
+├── user_id (INTEGER, FOREIGN KEY → users.id)
+├── product_name (VARCHAR(200))
+├── comment (TEXT)
+├── predicted_rating (INTEGER, 1-5)
+├── confidence_score (FLOAT)
+├── prediction_type (VARCHAR(20), 'single' or 'batch')
+└── created_at (DATETIME)
+```
+
+---
+
+## ✅ Quality Checklist
+
+- [x] All files created successfully
+- [x] Project structure is organized and logical
+- [x] Documentation is comprehensive
+- [x] Code has inline comments
+- [x] Separation of concerns implemented
+- [x] RESTful API design followed
+- [x] Security best practices applied
+- [x] UI is responsive and user-friendly
+- [x] Error handling implemented
+- [x] Ready for demonstration
+
+---
+
+**Total Lines of Code:** ~2000+ lines  
+**Total Documentation:** ~3000+ lines  
+**Time to Setup:** < 5 minutes  
+**Time to Demo:** 10-15 minutes  
+
+Your project is complete and production-ready! 🎉

PROJECT_SUMMARY.md

@@ -0,0 +1,293 @@
+# 📋 Project Summary - Vietnamese Product Rating Prediction System
+
+## ✅ What Has Been Built
+
+### 🏗️ Complete Project Structure
+```
+PredictRating/
+├── main.py                    # FastAPI application entry
+├── requirements.txt           # All dependencies
+├── README.md                  # Full documentation
+├── QUICKSTART.md             # Quick setup guide
+├── sample_comments.csv       # Test data
+├── .gitignore                # Git ignore rules
+│
+└── app/
+    ├── config.py             # Configuration settings
+    ├── database.py           # Database connection
+    ├── models.py             # SQLAlchemy models (User, PredictionHistory)
+    ├── schemas.py            # Pydantic validation schemas
+    │
+    ├── routers/              # API endpoints
+    │   ├── auth.py           # Login/Register endpoints
+    │   ├── prediction.py     # Single/Batch prediction
+    │   └── dashboard.py      # Frontend routes
+    │
+    ├── services/             # Business logic
+    │   ├── auth_service.py   # JWT authentication & password hashing
+    │   ├── ml_service.py     # ML prediction (DUMMY - replace with your model)
+    │   └── visualization_service.py  # WordCloud & chart data
+    │
+    ├── templates/            # Jinja2 HTML templates
+    │   ├── base.html         # Base layout with TailwindCSS
+    │   ├── login.html        # Login page
+    │   ├── register.html     # Registration page
+    │   └── dashboard.html    # Main prediction interface
+    │
+    ├── static/               # Static files
+    │   ├── css/
+    │   ├── js/
+    │   └── uploads/
+    │       └── wordclouds/   # Generated word cloud images
+    │
+    └── database/             # SQLite database location
+```
+
+---
+
+## 🎯 Features Implemented
+
+### 1. Authentication System ✅
+- **User Registration** with email validation
+- **JWT-based Login** (secure token authentication)
+- **Password Hashing** using bcrypt
+- **Protected Routes** requiring authentication
+
+### 2. Single Comment Prediction ✅
+- Select target product
+- Input Vietnamese comment
+- Get predicted rating (1-5 stars)
+- Display confidence score
+- Save to prediction history
+
+### 3. Batch CSV Prediction ✅
+- Upload CSV file with comments
+- Bulk prediction processing
+- **Visualizations:**
+  - Bar chart showing rating distributionStart command
+  - Word cloud of frequent words
+  - Results table with all predictions
+- **Export:** Download CSV with predicted ratings
+
+### 4. Data Visualization ✅
+- **Chart.js** for interactive bar charts
+- **WordCloud** library for generating word cloud images
+- Responsive charts that update dynamically
+
+### 5. API Documentation ✅
+- **Swagger UI** at `/docs` (automatic generation)
+- **ReDoc** at `/redoc` (alternative documentation)
+- Interactive API testing interface
+- Complete request/response schemas
+
+### 6. Database Integration ✅
+- **SQLite** database
+- **User table** (username, email, hashed password)
+- **PredictionHistory table** (tracks all predictions)
+- Automatic table creation on startup
+
+### 7. Frontend UI ✅
+- **TailwindCSS** for modern, responsive design
+- **Jinja2** server-side rendering
+- Tab-based interface (Single/Batch)
+- Real-time form validation
+- Loading states and error handling
+
+---
+
+## 🚀 How to Run
+
+### Step 1: Install Dependencies
+```bash
+pip install -r requirements.txt
+```
+
+### Step 2: Start Server
+```bash
+python main.py
+```
+
+### Step 3: Access Application
+- **Dashboard:** http://localhost:8000/dashboard
+- **Swagger API Docs:** http://localhost:8000/docs ⭐
+
+---
+
+## 📊 API Endpoints
+
+### Authentication
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/api/auth/register` | Register new user |
+| POST | `/api/auth/login` | Login (returns JWT token) |
+| GET | `/api/auth/me` | Get current user info |
+
+### Predictions
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/api/predict/single` | Predict single comment |
+| POST | `/api/predict/batch` | Predict batch from CSV |
+| GET | `/api/predict/history` | Get prediction history |
+
+### Frontend
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/login` | Login page |
+| GET | `/register` | Registration page |
+| GET | `/dashboard` | Main dashboard |
+
+---
+
+## 🔧 Replace Dummy ML Model
+
+The file `app/services/ml_service.py` contains a **DUMMY prediction function** that returns random ratings.
+
+### To integrate your real model:
+
+1. **Load your model in `__init__`:**
+```python
+def __init__(self):
+    self.model = load_model('path/to/your/model.h5')
+    self.tokenizer = load_tokenizer('path/to/tokenizer.pkl')
+```
+
+2. **Update `predict_single` method:**
+```python
+def predict_single(self, text: str) -> Dict[str, any]:
+    # Preprocess Vietnamese text
+    preprocessed = self.preprocess(text)
+    
+    # Tokenize
+    tokens = self.tokenizer.encode(preprocessed)
+    
+    # Predict
+    prediction = self.model.predict([tokens])
+    rating = int(prediction.argmax()) + 1  # 1-5 scale
+    confidence = float(prediction.max())
+    
+    return {
+        'rating': rating,
+        'confidence': confidence
+    }
+```
+
+3. **Implement preprocessing:**
+```python
+def preprocess(self, text: str) -> str:
+    # Your Vietnamese text preprocessing
+    text = text.lower()
+    text = remove_special_characters(text)
+    text = normalize_vietnamese(text)
+    return text
+```
+
+---
+
+## 🎓 Demo for Teacher
+
+### Show Swagger UI (Bonus Points!)
+1. Open http://localhost:8000/docs
+2. Demonstrate:
+   - All API endpoints organized by tags
+   - Request/response schemas
+   - "Try it out" functionality
+   - Authentication with JWT Bearer token
+
+### User Flow Demo
+1. **Register** a new account
+2. **Login** and show JWT token storage
+3. **Single Prediction:**
+   - Select product
+   - Enter Vietnamese comment
+   - Show predicted rating + confidence
+4. **Batch Prediction:**
+   - Upload `sample_comments.csv`
+   - Show bar chart of rating distribution
+   - Show word cloud visualization
+   - Download CSV with predictions
+
+### Technical Highlights
+- ✅ FastAPI automatic Swagger generation
+- ✅ JWT authentication security
+- ✅ RESTful API design
+- ✅ Separation of concerns (routers, services, models)
+- ✅ Database relationships (User ↔ PredictionHistory)
+- ✅ Responsive frontend with TailwindCSS
+- ✅ Data visualization with Chart.js + WordCloud
+
+---
+
+## 📦 Dependencies Installed
+
+```
+fastapi              # Web framework
+uvicorn              # ASGI server
+sqlalchemy           # ORM for database
+python-jose          # JWT tokens
+passlib              # Password hashing
+pydantic             # Data validation
+jinja2               # Template engine
+wordcloud            # Word cloud generation
+matplotlib           # Image rendering
+python-multipart     # File uploads
+```
+
+---
+
+## 🎯 What You Need to Do Next
+
+1. **Test the application:**
+   - Register an account
+   - Try single prediction
+   - Upload the `sample_comments.csv` file
+   - Test batch prediction
+
+2. **Replace the dummy ML model:**
+   - Edit `app/services/ml_service.py`
+   - Load your fine-tuned model
+   - Implement proper preprocessing
+   - Update prediction logic
+
+3. **Customize (optional):**
+   - Add more products in `app/config.py`
+   - Adjust styling in templates
+   - Add more Vietnamese stopwords in visualization service
+
+4. **Prepare for demo:**
+   - Practice showing Swagger UI
+   - Prepare sample comments in Vietnamese
+   - Explain the architecture and tech stack
+
+---
+
+## 📞 Quick Reference
+
+| What | Where |
+|------|-------|
+| Start server | `python main.py` |
+| Swagger UI | http://localhost:8000/docs |
+| Dashboard | http://localhost:8000/dashboard |
+| Replace model | `app/services/ml_service.py` |
+| Add products | `app/config.py` → PRODUCTS list |
+| Database file | `app/database/rating_prediction.db` |
+| Uploads folder | `app/static/uploads/` |
+| Test CSV | `sample_comments.csv` |
+
+---
+
+## ✨ Success Criteria Met
+
+✅ FastAPI backend with Swagger UI  
+✅ Jinja2 templates + TailwindCSS  
+✅ SQLite database (Users + History)  
+✅ JWT authentication  
+✅ Single comment prediction  
+✅ Batch CSV prediction  
+✅ Data visualization (charts + word cloud)  
+✅ CSV export with predictions  
+✅ Professional project structure  
+✅ Complete documentation  
+
+**Your ML prediction web app is ready! 🎉**
+
+Good luck with your presentation! 🎓

Procfile

@@ -0,0 +1 @@
+web: uvicorn main:app --host 0.0.0.0 --port $PORT

QUICKSTART.md

@@ -0,0 +1,116 @@
+# 🚀 Quick Start Guide
+
+## Installation
+
+1. **Install dependencies:**
+```bash
+pip install -r requirements.txt
+```
+
+2. **Run the application:**
+```bash
+python main.py
+```
+
+3. **Access the application:**
+# Nhớ kích hoạt môi trường trước
+conda activate ./env
+- Dashboard: http://localhost:8000
+- **Swagger API Docs: http://localhost:8000/docs** ⭐ (Show this to your teacher!)
+- ReDoc: http://localhost:8000/redoc
+
+## First Time Usage
+
+1. Go to http://localhost:8000/login
+2. Click "Register here" and create an account
+3. Login with your credentials
+4. You'll be redirected to the dashboard
+
+## Testing Single Prediction
+
+1. Select a product from dropdown
+2. Click "Single Comment" tab
+3. Enter a Vietnamese comment like: "Sản phẩm rất tốt, chất lượng cao, đóng gói cẩn thận"
+4. Click "Predict Rating"
+5. See the result with rating and confidence
+
+## Testing Batch Prediction (CSV)
+
+1. Create a CSV file with this format:
+```csv
+Comment
+"Sản phẩm rất tốt, đóng gói cẩn thận"
+"Chất lượng kém, không như mô tả"
+"Giao hàng nhanh, sản phẩm ổn"
+"Rất hài lòng với sản phẩm này"
+"Giá hơi cao nhưng chất lượng tốt"
+```
+
+2. Select a product
+3. Click "Upload CSV" tab
+4. Upload your CSV file
+5. Click "Predict Batch"
+6. View:
+   - Bar chart showing rating distribution
+   - Word cloud of common words
+   - Full results table
+   - Download CSV with predictions
+
+## Swagger UI Demo (For Teacher)
+
+1. Open http://localhost:8000/docs
+2. Show the endpoints:
+   - Authentication (register, login)
+   - Predictions (single, batch)
+   - History
+3. Click "Try it out" to test any endpoint
+4. Show the automatic request/response documentation
+
+## Replace Dummy ML Model
+
+Edit `app/services/ml_service.py`:
+
+```python
+def __init__(self):
+    # Load your real model here
+    self.model = load_model('path/to/your/model')
+    self.tokenizer = load_tokenizer('path/to/tokenizer')
+
+def predict_single(self, text: str) -> Dict[str, any]:
+    # Your preprocessing
+    preprocessed = self.preprocess(text)
+    
+    # Your prediction
+    prediction = self.model.predict(preprocessed)
+    rating = int(prediction)  # Convert to 1-5
+    
+    return {
+        'rating': rating,
+        'confidence': float(prediction_confidence)
+    }
+```
+
+## Troubleshooting
+
+**"Module not found":**
+```bash
+pip install -r requirements.txt
+```
+
+**"Port already in use":**
+Edit `main.py` and change port 8000 to another number.
+
+**"Database locked":**
+Close any other instances of the app and restart.
+
+## Project Highlights for Presentation
+
+✅ **FastAPI with automatic Swagger UI** (bonus points!)  
+✅ **JWT Authentication** (secure login)  
+✅ **RESTful API design** (professional structure)  
+✅ **Data Visualization** (charts + word clouds)  
+✅ **Batch Processing** (CSV upload/download)  
+✅ **Responsive UI** (TailwindCSS)  
+✅ **Database Integration** (SQLite with history tracking)  
+
+Good luck! 🎓

README.md

@@ -0,0 +1,12 @@
+---
+title: Predict Rating
+emoji: 📈
+colorFrom: blue
+colorTo: green
+sdk: docker
+app_port: 7860
+pinned: false
+---
+
+# Predict Rating App
+This is a FastAPI application deployed on Hugging Face Spaces using Docker.

README_HF_SPACE.md

@@ -0,0 +1,86 @@
+---
+title: Product Rating Prediction System
+emoji: ⭐
+colorFrom: blue
+colorTo: purple
+sdk: docker
+pinned: false
+license: mit
+---
+
+# ⭐ Product Rating Prediction System
+
+A production-ready AI-powered system for predicting product ratings from Vietnamese customer comments using PhoBERT.
+
+## 🎯 Features
+
+- 🤖 **Deep Learning Model**: PhoBERT-based sentiment analysis
+- 💬 **Single & Batch Predictions**: Process one comment or thousands via CSV
+- 📊 **Visual Analytics**: Word clouds and rating distribution charts
+- 🔐 **Secure Authentication**: JWT-based user management
+- 🌐 **Full-Stack Web App**: FastAPI backend + Jinja2 frontend
+- 🗄️ **External Database**: PostgreSQL support for scalability
+
+## 🚀 Quick Start
+
+### For Users
+1. Click the link above to access the live application
+2. Register a new account
+3. Upload a CSV file with comments or enter a single comment
+4. View predictions, visualizations, and download results
+
+### For Developers
+This Space requires environment variables to connect to an external PostgreSQL database. See [HUGGING_FACE_DEPLOYMENT.md](HUGGING_FACE_DEPLOYMENT.md) for setup instructions.
+
+## 📚 API Documentation
+
+Once the app is running, access:
+- **Swagger UI**: `/docs`
+- **ReDoc**: `/redoc`
+
+## 🔧 Technology Stack
+
+- **Backend**: FastAPI, SQLAlchemy, Uvicorn
+- **ML/NLP**: PyTorch, Transformers, PhoBERT
+- **Frontend**: Jinja2, TailwindCSS, Chart.js
+- **Database**: PostgreSQL (external)
+- **Security**: JWT, bcrypt
+
+## 📖 Documentation
+
+- [Deployment Guide](HUGGING_FACE_DEPLOYMENT.md)
+- [Environment Variables](HF_ENV_VARIABLES.md)
+- [Architecture](ARCHITECTURE.md)
+
+## 🐳 Docker
+
+This Space uses the Docker SDK to support heavy ML models (>500MB). The container runs on port 7860 as required by Hugging Face Spaces.
+
+## 🔒 Privacy & Security
+
+- All passwords are hashed with bcrypt
+- JWT tokens for secure authentication
+- External PostgreSQL database with SSL
+- No data stored in the container (stateless)
+
+## 📊 Model Information
+
+- **Base Model**: PhoBERT (Vietnamese BERT)
+- **Task**: Sentiment Analysis → Rating Prediction (1-5 stars)
+- **Language**: Vietnamese
+- **Model Size**: ~500MB
+
+## 🆘 Support
+
+For issues or questions:
+1. Check the logs tab above
+2. Review [HUGGING_FACE_DEPLOYMENT.md](HUGGING_FACE_DEPLOYMENT.md)
+3. Open an issue in the repository
+
+## 📄 License
+
+MIT License - See LICENSE file for details
+
+---
+
+**Built with ❤️ using FastAPI, PhoBERT, and Hugging Face Spaces**

RENDER_QUICKSTART.md

@@ -0,0 +1,137 @@
+# 🚀 QUICK DEPLOYMENT GUIDE
+
+## ✅ Files Changed (Production-Ready)
+
+1. ✅ **requirements.txt** - Added `psycopg2-binary`, `gunicorn`
+2. ✅ **app/database.py** - Hybrid SQLite/PostgreSQL support with Render URL fix
+3. ✅ **app/config.py** - Environment variable support for `SECRET_KEY`
+4. ✅ **main.py** - Auto-migration, production settings
+
+## 📋 Render Configuration
+
+### Web Service Settings
+
+```
+Name: vietnamese-rating-prediction
+Runtime: Python 3
+Build Command: pip install -r requirements.txt
+Start Command: gunicorn main:app --workers 4 --worker-class uvicorn.workers.UvicornWorker --bind 0.0.0.0:$PORT
+```
+
+### Environment Variables (Required)
+
+```
+SECRET_KEY = <generate-with-openssl-rand-hex-32>
+PYTHON_VERSION = 3.11.0
+```
+
+### PostgreSQL Database
+
+```
+Name: vietnamese-rating-db
+PostgreSQL Version: 15
+Instance Type: Free
+```
+
+**Link database to web service** - `DATABASE_URL` will be auto-populated.
+
+---
+
+## 🎯 Deployment Steps
+
+### 1. Push to GitHub
+```bash
+git add .
+git commit -m "Deploy to Render"
+git push origin master
+```
+
+### 2. Create Render Web Service
+- Go to https://dashboard.render.com/
+- New → Web Service
+- Connect GitHub repo
+- Use settings above
+
+### 3. Create PostgreSQL Database
+- New → PostgreSQL
+- Use free tier
+- Link to web service
+
+### 4. Deploy
+- Click "Manual Deploy"
+- Watch logs for success
+
+### 5. Test
+```
+https://your-app.onrender.com/health
+https://your-app.onrender.com/docs
+https://your-app.onrender.com/dashboard
+```
+
+---
+
+## 🔧 Local Testing Before Deploy
+
+Test hybrid database locally:
+
+```bash
+# Test with SQLite (no DATABASE_URL)
+python main.py
+
+# Test with PostgreSQL (set DATABASE_URL)
+export DATABASE_URL=postgresql://user:pass@localhost/dbname
+python main.py
+```
+
+Expected output:
+```
+🔧 Development Mode: Using SQLite
+# OR
+🚀 Production Mode: Using PostgreSQL
+🔄 Creating database tables...
+✅ Database tables created successfully!
+```
+
+---
+
+## ⚠️ Important Notes
+
+1. **Render Free Tier Limitations:**
+   - App sleeps after 15 minutes of inactivity (first request takes 30-60s)
+   - 512MB RAM (may need optimization for ML model)
+   - 1GB PostgreSQL storage
+
+2. **ML Model Optimization:**
+   - Consider lazy loading (load on first request)
+   - Use CPU-optimized PyTorch
+   - Cache predictions if possible
+
+3. **Static Files:**
+   - Uploads are ephemeral on Render Free Tier
+   - WordClouds will be deleted on container restart
+   - Use cloud storage (S3, Cloudinary) for production
+
+4. **Database:**
+   - SQLite NOT recommended for production (file locking issues)
+   - PostgreSQL required for concurrent requests
+   - Free tier: 1GB storage, 97 connections
+
+---
+
+## 🆘 Common Issues
+
+### "Module not found"
+→ Run `pip install -r requirements.txt` locally first
+
+### "Port binding error"
+→ Use `$PORT` in start command (auto-set by Render)
+
+### "Database connection failed"
+→ Check `DATABASE_URL` in environment variables
+
+### "Model loading timeout"
+→ Free tier has 512MB RAM limit, optimize model or upgrade
+
+---
+
+**Read DEPLOYMENT.md for detailed guide!**

app/__init__.py

@@ -0,0 +1 @@
+# App package

app/config.py

@@ -0,0 +1,46 @@
+"""
+Configuration Settings
+Supports environment variables for production deployment
+"""
+import os
+from pathlib import Path
+
+# Base directory
+BASE_DIR = Path(__file__).resolve().parent.parent
+
+# ============================================
+# SECURITY (Environment-aware)
+# ============================================
+# In production (Render), set SECRET_KEY as environment variable
+# Fallback to default for local development
+SECRET_KEY = os.getenv(
+    "SECRET_KEY", 
+    "your-secret-key-change-in-production-2024-dev-only"
+)
+
+ALGORITHM = "HS256"
+ACCESS_TOKEN_EXPIRE_MINUTES = 60 * 24  # 24 hours
+
+# ============================================
+# UPLOAD DIRECTORIES
+# ============================================
+# For production on Render, these will be in ephemeral storage
+# Consider using cloud storage (S3, Cloudinary) for persistent files
+UPLOAD_DIR = BASE_DIR / "app" / "static" / "uploads"
+WORDCLOUD_DIR = UPLOAD_DIR / "wordclouds"
+
+# Create directories if they don't exist
+UPLOAD_DIR.mkdir(parents=True, exist_ok=True)
+WORDCLOUD_DIR.mkdir(parents=True, exist_ok=True)
+
+# ============================================
+# PRODUCTION SETTINGS
+# ============================================
+# Detect if running on Render (or any production environment)
+IS_PRODUCTION = os.getenv("RENDER") is not None or os.getenv("DATABASE_URL") is not None
+
+if IS_PRODUCTION:
+    print("🚀 Running in PRODUCTION mode")
+else:
+    print("🔧 Running in DEVELOPMENT mode")
+

app/database.py

@@ -0,0 +1,66 @@
+"""
+Database Configuration and Session Management
+Supports BOTH SQLite (local) and PostgreSQL (production on Render)
+"""
+import os
+from sqlalchemy import create_engine
+from sqlalchemy.ext.declarative import declarative_base
+from sqlalchemy.orm import sessionmaker
+from pathlib import Path
+
+# ============================================
+# HYBRID DATABASE SUPPORT
+# ============================================
+# Priority:
+# 1. Use DATABASE_URL from environment (Render PostgreSQL)
+# 2. Fallback to SQLite for local development
+
+DATABASE_URL = os.getenv("DATABASE_URL")
+
+if DATABASE_URL:
+    # CRITICAL FIX FOR RENDER:
+    # Render provides URLs starting with 'postgres://'
+    # but SQLAlchemy 1.4+ requires 'postgresql://'
+    if DATABASE_URL.startswith("postgres://"):
+        DATABASE_URL = DATABASE_URL.replace("postgres://", "postgresql://", 1)
+    
+    print(f"🚀 Production Mode: Using PostgreSQL")
+    
+    # PostgreSQL: No need for check_same_thread
+    engine = create_engine(
+        DATABASE_URL,
+        pool_pre_ping=True,  # Verify connections before using
+        pool_recycle=300,    # Recycle connections every 5 minutes
+    )
+else:
+    # Local development: Use SQLite
+    print(f"🔧 Development Mode: Using SQLite")
+    
+    # Create database directory
+    db_dir = Path("app/database")
+    db_dir.mkdir(parents=True, exist_ok=True)
+    
+    DATABASE_URL = "sqlite:///./app/database/rating_prediction.db"
+    
+    # SQLite: Needs check_same_thread=False for FastAPI
+    engine = create_engine(
+        DATABASE_URL, 
+        connect_args={"check_same_thread": False}
+    )
+
+# Create session factory
+SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
+
+# Base class for all models
+Base = declarative_base()
+
+def get_db():
+    """
+    Dependency to get database session
+    Used in FastAPI route dependencies
+    """
+    db = SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()

app/database/.gitkeep

@@ -0,0 +1 @@
+# Database directory

app/models.py

@@ -0,0 +1,43 @@
+"""
+SQLAlchemy Database Models
+"""
+from sqlalchemy import Column, Integer, String, DateTime, Text, ForeignKey, Float
+from sqlalchemy.orm import relationship
+from datetime import datetime
+from app.database import Base
+
+class User(Base):
+    """User model for authentication"""
+    __tablename__ = "users"
+    
+    id = Column(Integer, primary_key=True, index=True)
+    username = Column(String(50), unique=True, index=True, nullable=False)
+    email = Column(String(100), unique=True, index=True, nullable=False)
+    hashed_password = Column(String(255), nullable=False)
+    created_at = Column(DateTime, default=datetime.utcnow)
+    
+    # Relationship
+    predictions = relationship("PredictionHistory", back_populates="user")
+    
+    def __repr__(self):
+        return f"<User {self.username}>"
+
+
+class PredictionHistory(Base):
+    """Prediction history model"""
+    __tablename__ = "prediction_history"
+    
+    id = Column(Integer, primary_key=True, index=True)
+    user_id = Column(Integer, ForeignKey("users.id"), nullable=False)
+    product_name = Column(String(200), nullable=False)
+    comment = Column(Text, nullable=False)
+    predicted_rating = Column(Integer, nullable=False)
+    confidence_score = Column(Float, nullable=True)
+    prediction_type = Column(String(20), default="single")  # 'single' or 'batch'
+    created_at = Column(DateTime, default=datetime.utcnow)
+    
+    # Relationship
+    user = relationship("User", back_populates="predictions")
+    
+    def __repr__(self):
+        return f"<PredictionHistory {self.id}: {self.predicted_rating}⭐>"

app/routers/__init__.py

@@ -0,0 +1 @@
+# Routers package

app/routers/auth.py

@@ -0,0 +1,97 @@
+"""
+Authentication Router
+Handles user registration and login
+"""
+from datetime import timedelta
+from fastapi import APIRouter, Depends, HTTPException, status
+from fastapi.security import OAuth2PasswordRequestForm
+from sqlalchemy.orm import Session
+
+from app.database import get_db
+from app.models import User
+from app.schemas import UserCreate, UserResponse, Token
+from app.services.auth_service import (
+    get_password_hash,
+    authenticate_user,
+    create_access_token,
+    get_current_user
+)
+from app.config import ACCESS_TOKEN_EXPIRE_MINUTES
+
+router = APIRouter()
+
+
+@router.post("/register", response_model=UserResponse, status_code=status.HTTP_201_CREATED)
+async def register(user_data: UserCreate, db: Session = Depends(get_db)):
+    """
+    Register a new user
+    
+    - **username**: Unique username (3-50 characters)
+    - **email**: Valid email address
+    - **password**: Password (minimum 6 characters)
+    """
+    # Check if username exists
+    db_user = db.query(User).filter(User.username == user_data.username).first()
+    if db_user:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Username already registered"
+        )
+    
+    # Check if email exists
+    db_user = db.query(User).filter(User.email == user_data.email).first()
+    if db_user:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Email already registered"
+        )
+    
+    # Create new user
+    new_user = User(
+        username=user_data.username,
+        email=user_data.email,
+        hashed_password=get_password_hash(user_data.password)
+    )
+    
+    db.add(new_user)
+    db.commit()
+    db.refresh(new_user)
+    
+    return new_user
+
+
+@router.post("/login", response_model=Token)
+async def login(
+    form_data: OAuth2PasswordRequestForm = Depends(),
+    db: Session = Depends(get_db)
+):
+    """
+    Login to get access token
+    
+    - **username**: Your username
+    - **password**: Your password
+    
+    Returns JWT access token for authentication
+    """
+    user = authenticate_user(db, form_data.username, form_data.password)
+    if not user:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Incorrect username or password",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+    
+    access_token_expires = timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES)
+    access_token = create_access_token(
+        data={"sub": user.username}, expires_delta=access_token_expires
+    )
+    
+    return {"access_token": access_token, "token_type": "bearer"}
+
+
+@router.get("/me", response_model=UserResponse)
+async def get_current_user_info(current_user: User = Depends(get_current_user)):
+    """
+    Get current authenticated user information
+    """
+    return current_user

app/routers/dashboard.py

@@ -0,0 +1,44 @@
+"""
+Dashboard Router
+Serves frontend Jinja2 templates
+"""
+from fastapi import APIRouter, Request, Depends
+from fastapi.templating import Jinja2Templates
+from fastapi.responses import HTMLResponse, RedirectResponse
+from sqlalchemy.orm import Session
+
+from app.database import get_db
+from app.models import User
+from app.services.auth_service import get_current_user
+
+router = APIRouter()
+templates = Jinja2Templates(directory="app/templates")
+
+
+@router.get("/", response_class=HTMLResponse)
+async def home(request: Request):
+    """Home page - redirect to login"""
+    return RedirectResponse(url="/login")
+
+
+@router.get("/login", response_class=HTMLResponse)
+async def login_page(request: Request):
+    """Login page"""
+    return templates.TemplateResponse("login.html", {"request": request})
+
+
+@router.get("/register", response_class=HTMLResponse)
+async def register_page(request: Request):
+    """Registration page"""
+    return templates.TemplateResponse("register.html", {"request": request})
+
+
+@router.get("/dashboard", response_class=HTMLResponse)
+async def dashboard_page(request: Request):
+    """
+    Main dashboard page
+    Requires authentication (handle in frontend with token)
+    """
+    return templates.TemplateResponse("dashboard.html", {
+        "request": request
+    })

app/routers/prediction.py

@@ -0,0 +1,359 @@
+"""
+Prediction Router
+Handles single and batch predictions with enhanced features:
+- Keyword highlighting
+- SHAP/Interpretability explanation
+- N-gram analysis
+"""
+import io
+import csv
+from typing import List, Dict
+from datetime import datetime
+from fastapi import APIRouter, Depends, HTTPException, status, UploadFile, File, Form
+from fastapi.responses import StreamingResponse
+from sqlalchemy.orm import Session
+
+from app.database import get_db
+from app.models import User, PredictionHistory
+from app.schemas import (
+    SinglePredictionRequest,
+    SinglePredictionResponse,
+    BatchPredictionResponse,
+    PredictionHistoryResponse,
+    PDFReportRequest,
+    NgramAnalysisRequest,
+    NgramAnalysisResponse
+)
+from app.services.auth_service import get_current_user
+from app.services.ml_service import get_ml_service, MLPredictionService
+from app.services.visualization_service import get_viz_service, VisualizationService
+from app.services.report_service import get_report_service, ReportService
+
+router = APIRouter()
+
+
+def highlight_text(text: str, positive_keywords: List[str], negative_keywords: List[str]) -> str:
+    """Apply HTML highlighting to keywords in text"""
+    highlighted = text
+    
+    # Sort by length (longer first) to avoid partial matches
+    for word in sorted(negative_keywords, key=len, reverse=True):
+        highlighted = highlighted.replace(
+            word, 
+            f'<span class="highlight-negative">{word}</span>'
+        )
+    
+    for word in sorted(positive_keywords, key=len, reverse=True):
+        highlighted = highlighted.replace(
+            word, 
+            f'<span class="highlight-positive">{word}</span>'
+        )
+    
+    return highlighted
+
+
+@router.post("/single", response_model=SinglePredictionResponse)
+async def predict_single(
+    request: SinglePredictionRequest,
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+    ml_service: MLPredictionService = Depends(get_ml_service)
+):
+    """
+    Predict rating for a single comment with optional explanation
+    
+    - **product_name**: Name of the product
+    - **comment**: Vietnamese product review text
+    - **include_explanation**: Whether to include SHAP-like explanation
+    
+    Returns predicted rating (1-5 stars) with confidence score,
+    keyword highlighting, and optionally word importance explanation
+    """
+    # Check if explanation is requested
+    if request.include_explanation:
+        # Use enhanced prediction with explanation
+        result = ml_service.predict_with_explanation(request.comment)
+        prediction = {
+            'rating': result['rating'],
+            'confidence': result['confidence']
+        }
+        explanation = result.get('explanation')
+        keywords = result.get('keywords')
+    else:
+        # Use standard prediction
+        prediction = ml_service.predict_single(request.comment)
+        # Still get keyword analysis for highlighting
+        keywords = ml_service.keyword_analyzer.analyze(request.comment)
+        explanation = None
+    
+    # Generate highlighted text
+    highlighted_comment = highlight_text(
+        request.comment,
+        keywords.get('positive_keywords', []) if isinstance(keywords, dict) else keywords.positive_keywords if keywords else [],
+        keywords.get('negative_keywords', []) if isinstance(keywords, dict) else keywords.negative_keywords if keywords else []
+    )
+    
+    # Save to history
+    history = PredictionHistory(
+        user_id=current_user.id,
+        product_name=request.product_name,
+        comment=request.comment,
+        predicted_rating=prediction['rating'],
+        confidence_score=prediction['confidence'],
+        prediction_type='single'
+    )
+    db.add(history)
+    db.commit()
+    
+    return {
+        "predicted_rating": prediction['rating'],
+        "confidence_score": prediction['confidence'],
+        "comment": request.comment,
+        "highlighted_comment": highlighted_comment,
+        "explanation": explanation,
+        "keywords": keywords
+    }
+
+
+@router.post("/batch", response_model=BatchPredictionResponse)
+async def predict_batch(
+    product_name: str = Form(None),
+    file: UploadFile = File(...),
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+    ml_service: MLPredictionService = Depends(get_ml_service),
+    viz_service: VisualizationService = Depends(get_viz_service),
+    report_service: ReportService = Depends(get_report_service)
+):
+    """
+    Predict ratings for batch of comments from CSV file with enhanced analysis
+    
+    - **product_name**: Name of the product
+    - **file**: CSV file with 'Comment' column
+    
+    Returns predictions with:
+    - Visualization data (wordcloud, distribution chart)
+    - N-gram analysis (unigrams, bigrams, trigrams)
+    - Keyword frequency analysis
+    """
+    # Validate file type
+    if not file.filename.endswith('.csv'):
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="File must be a CSV"
+        )
+    
+    try:
+        # Read CSV file
+        contents = await file.read()
+        csv_file = io.StringIO(contents.decode('utf-8'))
+        reader = csv.DictReader(csv_file)
+        
+        # Check for Comment column
+        if 'Comment' not in reader.fieldnames:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="CSV must contain 'Comment' column"
+            )
+        
+        # Extract comments
+        comments = []
+        for row in reader:
+            if row.get('Comment', '').strip():
+                comments.append(row['Comment'].strip())
+        
+        if not comments:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="No valid comments found in CSV"
+            )
+        
+        # Make batch predictions with analysis
+        batch_result = ml_service.predict_batch_with_analysis(comments)
+        predictions = batch_result['predictions']
+        ngrams = batch_result['ngrams']
+        keyword_frequency = batch_result['keyword_frequency']
+
+        final_product_name = product_name if product_name else "Unknown Product"
+
+        # Save to history
+        for pred in predictions:
+            history = PredictionHistory(
+                user_id=current_user.id,
+                product_name=final_product_name,
+                comment=pred['text'],
+                predicted_rating=pred['rating'],
+                confidence_score=pred['confidence'],
+                prediction_type='batch'
+            )
+            db.add(history)
+        db.commit()
+        
+        # Calculate rating distribution
+        ratings = [p['rating'] for p in predictions]
+        distribution = viz_service.calculate_rating_distribution(ratings)
+        
+        # Generate word cloud
+        wordcloud_filename = f"wordcloud_{current_user.username}_{datetime.now().strftime('%Y%m%d_%H%M%S')}.png"
+        wordcloud_url = viz_service.generate_wordcloud(comments, wordcloud_filename)
+        
+        # Prepare results for CSV download
+        results = []
+        for pred in predictions:
+            results.append({
+                'Comment': pred['text'],
+                'Predicted_Rating': pred['rating'],
+                'Confidence': pred['confidence']
+            })
+        
+        # Generate PDF report
+        pdf_filename = f"report_{current_user.username}_{datetime.now().strftime('%Y%m%d_%H%M%S')}.pdf"
+        pdf_content = report_service.generate_pdf_report(
+            predictions=predictions,
+            distribution=distribution,
+            wordcloud_path=wordcloud_url,
+            username=current_user.username,
+            filename=pdf_filename
+        )
+        
+        return {
+            "total_predictions": len(predictions),
+            "rating_distribution": distribution,
+            "wordcloud_url": wordcloud_url,
+            "results": results,
+            "csv_download_url": f"/api/predict/download/{current_user.id}/{datetime.now().timestamp()}",
+            "pdf_download_url": f"/api/predict/download-pdf/{current_user.id}/{datetime.now().timestamp()}",
+            "ngrams": ngrams,
+            "keyword_frequency": keyword_frequency
+        }
+    
+    except Exception as e:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Error processing file: {str(e)}"
+        )
+
+
+@router.get("/history", response_model=List[PredictionHistoryResponse])
+async def get_prediction_history(
+    limit: int = 50,
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    """
+    Get prediction history for current user
+    
+    - **limit**: Maximum number of records to return (default: 50)
+    """
+    history = db.query(PredictionHistory).filter(
+        PredictionHistory.user_id == current_user.id
+    ).order_by(PredictionHistory.created_at.desc()).limit(limit).all()
+    
+    return history
+
+
+@router.post("/download-csv")
+async def download_predictions_csv(
+    results: List[dict],
+    current_user: User = Depends(get_current_user)
+):
+    """
+    Download prediction results as CSV
+    """
+    # Create CSV in memory
+    output = io.StringIO()
+    
+    if results:
+        fieldnames = results[0].keys()
+        writer = csv.DictWriter(output, fieldnames=fieldnames)
+        writer.writeheader()
+        writer.writerows(results)
+    
+    # Reset position
+    output.seek(0)
+    
+    # Return as streaming response
+    return StreamingResponse(
+        iter([output.getvalue()]),
+        media_type="text/csv",
+        headers={
+            "Content-Disposition": f"attachment; filename=predictions_{datetime.now().strftime('%Y%m%d_%H%M%S')}.csv"
+        }
+    )
+
+
+@router.post("/download-pdf")
+async def download_predictions_pdf(
+    request: PDFReportRequest,
+    current_user: User = Depends(get_current_user),
+    report_service: ReportService = Depends(get_report_service)
+):
+    """
+    Download prediction results as PDF report
+    """
+    try:
+        pdf_content = report_service.generate_pdf_report(
+            predictions=request.predictions,
+            distribution=request.distribution,
+            wordcloud_path=request.wordcloud_path,
+            username=current_user.username
+        )
+        
+        return StreamingResponse(
+            io.BytesIO(pdf_content),
+            media_type="application/pdf",
+            headers={
+                "Content-Disposition": f"attachment; filename=predictions_report_{datetime.now().strftime('%Y%m%d_%H%M%S')}.pdf"
+            }
+        )
+    except Exception as e:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Error generating PDF: {str(e)}"
+        )
+
+
+@router.post("/analyze-ngrams", response_model=NgramAnalysisResponse)
+async def analyze_ngrams(
+    request: NgramAnalysisRequest,
+    current_user: User = Depends(get_current_user),
+    ml_service: MLPredictionService = Depends(get_ml_service)
+):
+    """
+    Analyze n-grams (unigrams, bigrams, trigrams) for a list of texts
+    
+    - **texts**: List of Vietnamese text comments
+    
+    Returns frequency analysis of word patterns
+    """
+    if not request.texts:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="No texts provided for analysis"
+        )
+    
+    ngrams = ml_service.analyze_ngrams(request.texts)
+    
+    return ngrams
+
+
+@router.post("/explain")
+async def explain_prediction(
+    request: SinglePredictionRequest,
+    current_user: User = Depends(get_current_user),
+    ml_service: MLPredictionService = Depends(get_ml_service)
+):
+    """
+    Get detailed explanation for a prediction
+    
+    Returns word importance scores and keyword analysis
+    """
+    result = ml_service.predict_with_explanation(request.comment)
+    
+    return {
+        "predicted_rating": result['rating'],
+        "confidence_score": result['confidence'],
+        "comment": request.comment,
+        "explanation": result['explanation'],
+        "keywords": result['keywords']
+    }

app/schemas.py

@@ -0,0 +1,114 @@
+"""
+Pydantic Schemas for Request/Response Validation
+"""
+from pydantic import BaseModel, EmailStr, Field
+from typing import Optional, List, Dict, Any
+from datetime import datetime
+
+# ===== Auth Schemas =====
+class UserCreate(BaseModel):
+    username: str = Field(..., min_length=3, max_length=50)
+    email: EmailStr
+    password: str = Field(..., min_length=6)
+
+class UserLogin(BaseModel):
+    username: str
+    password: str
+
+class UserResponse(BaseModel):
+    id: int
+    username: str
+    email: str
+    created_at: datetime
+    
+    class Config:
+        from_attributes = True
+
+class Token(BaseModel):
+    access_token: str
+    token_type: str
+
+class TokenData(BaseModel):
+    username: Optional[str] = None
+
+
+# ===== Prediction Schemas =====
+class SinglePredictionRequest(BaseModel):
+    product_name: Optional[str] = ""
+    comment: str
+    include_explanation: Optional[bool] = False
+
+class ExplanationData(BaseModel):
+    words: List[str]
+    importance_scores: List[float]
+    overall_sentiment: str
+
+class KeywordData(BaseModel):
+    positive_keywords: List[str]
+    negative_keywords: List[str]
+    positive_count: int
+    negative_count: int
+
+class SinglePredictionResponse(BaseModel):
+    predicted_rating: int
+    confidence_score: float
+    comment: str
+    highlighted_comment: Optional[str] = None
+    explanation: Optional[ExplanationData] = None
+    keywords: Optional[KeywordData] = None
+
+class NgramItem(BaseModel):
+    ngram: str
+    count: int
+
+class NgramAnalysis(BaseModel):
+    unigrams: List[NgramItem]
+    bigrams: List[NgramItem]
+    trigrams: List[NgramItem]
+
+class KeywordFrequencyItem(BaseModel):
+    word: str
+    count: int
+
+class KeywordFrequency(BaseModel):
+    positive: List[KeywordFrequencyItem]
+    negative: List[KeywordFrequencyItem]
+
+class BatchPredictionResponse(BaseModel):
+    total_predictions: int
+    rating_distribution: dict
+    wordcloud_url: str
+    results: List[dict]
+    csv_download_url: str
+    pdf_download_url: str
+    ngrams: Optional[NgramAnalysis] = None
+    keyword_frequency: Optional[KeywordFrequency] = None
+
+class PDFReportRequest(BaseModel):
+    predictions: List[dict]
+    distribution: dict
+    wordcloud_path: str
+
+
+# ===== History Schemas =====
+class PredictionHistoryResponse(BaseModel):
+    id: int
+    product_name: str
+    comment: str
+    predicted_rating: int
+    confidence_score: Optional[float]
+    prediction_type: str
+    created_at: datetime
+    
+    class Config:
+        from_attributes = True
+
+
+# ===== Analysis Schemas =====
+class NgramAnalysisRequest(BaseModel):
+    texts: List[str]
+    
+class NgramAnalysisResponse(BaseModel):
+    unigrams: List[NgramItem]
+    bigrams: List[NgramItem]
+    trigrams: List[NgramItem]

app/services/Model/phoBERT_multi_class_tokenizer/added_tokens.json

@@ -0,0 +1,3 @@
+{
+  "<mask>": 64000
+}