Upload folder using huggingface_hub

.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

@@ -1,35 +1 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,51 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+env/
+venv/
+ENV/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# FastAPI
+*.db
+*.sqlite
+*.sqlite3
+
+# Uploads
+app/static/uploads/*
+!app/static/uploads/.gitkeep
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+.env.local
+
+# Logs
+*.log

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,54 @@
+# ============================================
+# Dockerfile for Hugging Face Spaces (Docker SDK)
+# Optimized for FastAPI + Heavy ML Model (>500MB)
+# ============================================
+
+FROM python:3.10-slim
+
+# 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"]

FIX_OOM_RENDER.md

@@ -0,0 +1,150 @@
+# 🚨 URGENT FIX: Out of Memory on Render
+
+## Problem
+```
+==> Out of memory (used over 512Mi)
+```
+
+Render Free Tier has **512MB RAM limit**. PhoBERT model is too heavy to load on startup.
+
+---
+
+## ✅ Solution Applied: Lazy Loading
+
+### Changes Made
+
+**File: `app/services/ml_service.py`**
+- ✅ Model now loads **on first request** instead of on startup
+- ✅ Reduces initial memory footprint
+- ✅ Imports (torch, transformers) only when needed
+
+---
+
+## 📝 Update Render Configuration
+
+### Step 1: Change Start Command
+
+Go to Render Dashboard → Your Web Service → Settings
+
+**OLD Start Command:**
+```bash
+gunicorn main:app --workers 4 --worker-class uvicorn.workers.UvicornWorker --bind 0.0.0.0:$PORT
+```
+
+**NEW Start Command (Reduce workers from 4 → 1):**
+```bash
+gunicorn main:app --workers 1 --worker-class uvicorn.workers.UvicornWorker --bind 0.0.0.0:$PORT --timeout 120
+```
+
+### Step 2: Push Updated Code
+
+```bash
+git add app/services/ml_service.py
+git commit -m "Fix: Lazy load ML model to avoid OOM on Render"
+git push origin master
+```
+
+### Step 3: Redeploy
+
+1. Go to Render Dashboard
+2. Click **"Manual Deploy"** → **"Clear build cache & deploy"**
+3. Wait for deployment (will take 5-10 minutes)
+
+---
+
+## 🔍 Expected Behavior After Fix
+
+### On Startup (Fast):
+```
+✅ ML Service initialized (model will load on first request)
+🚀 Running in PRODUCTION mode
+✅ Database tables created successfully!
+[INFO] Starting gunicorn
+```
+
+### On First Prediction Request (Slow - 30-60 seconds):
+```
+🔄 Loading ML model (first request)...
+📍 Using device: cpu
+📦 Loading tokenizer...
+🧠 Loading PhoBERT model...
+⚙️ Loading trained weights...
+✅ Model loaded successfully!
+```
+
+### Subsequent Requests (Fast):
+Model is already loaded, predictions are instant.
+
+---
+
+## ⚠️ Important Notes
+
+### 1. First Request Will Be Slow
+- User must wait 30-60 seconds for first prediction
+- Consider adding loading spinner in frontend
+- Or call `/health` endpoint on deploy to pre-load model
+
+### 2. Free Tier Limitations
+If still getting OOM errors, consider:
+- ✅ Use quantized model (smaller size)
+- ✅ Upgrade to Starter ($7/month, 512MB → 2GB RAM)
+- ✅ Deploy model separately (separate service)
+- ✅ Use CPU-only PyTorch build
+
+### 3. Model Files Must Exist
+Ensure these files are in repository:
+- `app/services/Model/phoBERT_multi_class_tokenizer/`
+- `app/services/Model/best_phoBER.pth`
+
+---
+
+## 🧪 Test Locally First
+
+```bash
+python main.py
+```
+
+Expected output:
+```
+✅ ML Service initialized (model will load on first request)
+🔧 Development Mode: Using SQLite
+```
+
+Then test prediction endpoint - model will load on first request.
+
+---
+
+## 📊 Memory Usage Comparison
+
+| Configuration | Startup Memory | With Model Loaded |
+|---------------|----------------|-------------------|
+| **Before (Eager)** | ~450MB | ~550MB (OOM) |
+| **After (Lazy)** | ~150MB | ~450MB (OK) |
+
+---
+
+## 🆘 If Still Getting OOM
+
+### Option 1: Use Dummy Model (Testing)
+Temporarily use dummy predictions to verify deployment works:
+
+Edit `app/services/ml_service.py`:
+```python
+def predict_single(self, text: str) -> Dict[str, Any]:
+    # Skip model loading for testing
+    return {
+        'rating': 4,  # Dummy rating
+        'confidence': 0.85
+    }
+```
+
+### Option 2: Upgrade Render Plan
+- Starter: $7/month, 2GB RAM
+- Standard: $25/month, 4GB RAM
+
+### Option 3: Deploy Model Separately
+Use external ML API service (AWS Lambda, Hugging Face Inference API, etc.)
+
+---
+
+**After making these changes, try deploying again!**

HF_ARCHITECTURE_DIAGRAM.md

@@ -0,0 +1,332 @@
+# 🏗️ Hugging Face Spaces Deployment Architecture
+
+## 📊 High-Level Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    HUGGING FACE SPACES                      │
+│                     (16GB RAM - Free)                       │
+│                                                             │
+│  ┌───────────────────────────────────────────────────┐    │
+│  │              Docker Container                      │    │
+│  │              (User ID: 1000)                       │    │
+│  │                                                     │    │
+│  │  ┌─────────────────────────────────────────┐     │    │
+│  │  │         FastAPI Application              │     │    │
+│  │  │         (Port 7860)                      │     │    │
+│  │  │                                          │     │    │
+│  │  │  ┌──────────────┐  ┌──────────────┐   │     │    │
+│  │  │  │   Uvicorn    │  │  PhoBERT     │   │     │    │
+│  │  │  │   Server     │  │  Model       │   │     │    │
+│  │  │  │              │  │  (~500MB)    │   │     │    │
+│  │  │  └──────────────┘  └──────────────┘   │     │    │
+│  │  │                                          │     │    │
+│  │  │  ┌──────────────┐  ┌──────────────┐   │     │    │
+│  │  │  │  Jinja2      │  │  WordCloud   │   │     │    │
+│  │  │  │  Templates   │  │  Generator   │   │     │    │
+│  │  │  └──────────────┘  └──────────────┘   │     │    │
+│  │  └─────────────────────────────────────────┘     │    │
+│  │                                                     │    │
+│  │  Environment Variables (from HF Secrets):          │    │
+│  │  - DATABASE_URL                                    │    │
+│  │  - SECRET_KEY                                      │    │
+│  └───────────────────────────────────────────────────┘    │
+└─────────────────────────────────────────────────────────────┘
+                          │
+                          │ HTTPS
+                          ▼
+              ┌────────────────────────┐
+              │        Users           │
+              │  (Web Browsers)        │
+              └────────────────────────┘
+                          │
+                          │
+                          ▼
+┌─────────────────────────────────────────────────────────────┐
+│               External PostgreSQL Database                  │
+│               (Render / Neon / Other)                       │
+│                                                             │
+│  ┌──────────────┐         ┌──────────────────────┐        │
+│  │  Users       │         │  PredictionHistory   │        │
+│  │  Table       │────────▶│  Table               │        │
+│  │              │   FK    │                      │        │
+│  └──────────────┘         └──────────────────────┘        │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 🔄 Request Flow
+
+```
+1. User visits Space URL
+   └─▶ https://huggingface.co/spaces/USERNAME/SPACE_NAME
+       │
+       ▼
+2. Hugging Face routes to Docker container (port 7860)
+       │
+       ▼
+3. Uvicorn receives HTTP request
+       │
+       ├─▶ GET /docs → Swagger UI
+       ├��▶ GET /dashboard → Jinja2 Template + TailwindCSS
+       ├─▶ POST /api/auth/login → JWT Token
+       ├─▶ POST /api/predict/single → PhoBERT Model
+       └─▶ POST /api/predict/batch → CSV Processing + WordCloud
+           │
+           ▼
+4. Database query (if needed)
+   └─▶ PostgreSQL on Render/Neon (via DATABASE_URL)
+       │
+       ▼
+5. Response returned to user
+   └─▶ JSON (API) or HTML (Pages)
+```
+
+---
+
+## 🐳 Docker Build Process
+
+```
+1. Dockerfile Instructions
+   │
+   ├─▶ FROM python:3.10-slim
+   │   └─ Base image (~150MB)
+   │
+   ├─▶ RUN useradd -m -u 1000 user
+   │   └─ Create non-root user (HF requirement)
+   │
+   ├─▶ COPY requirements.txt
+   │   └─ Copy dependencies first
+   │
+   ├─▶ RUN pip install -r requirements.txt
+   │   └─ Install packages (~2GB with PyTorch)
+   │
+   ├─▶ COPY --chown=user:user . .
+   │   └─ Copy application code
+   │
+   ├─▶ RUN chmod -R 777 /app/app/static/uploads
+   │   └─ Set write permissions
+   │
+   ├─▶ USER user
+   │   └─ Switch to non-root user
+   │
+   └─▶ CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "7860"]
+       └─ Start application
+
+Total Build Time: 5-10 minutes
+Final Image Size: ~2.5GB
+```
+
+---
+
+## 🔐 Security Layer
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      Security Features                      │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  1. Authentication Layer                                    │
+│     ├─ JWT Tokens (24h expiration)                         │
+│     ├─ Bcrypt password hashing                             │
+│     └─ OAuth2 Bearer scheme                                │
+│                                                             │
+│  2. Network Security                                        │
+│     ├─ HTTPS (provided by HF)                              │
+│     ├─ CORS configuration                                   │
+│     └─ PostgreSQL SSL (sslmode=require)                    │
+│                                                             │
+│  3. Secret Management                                       │
+│     ├─ Environment variables (HF Secrets)                  │
+│     ├─ No hardcoded credentials                            │
+│     └─ .dockerignore excludes .env                         │
+│                                                             │
+│  4. Container Security                                      │
+│     ├─ Non-root user (UID 1000)                            │
+│     ├─ Read-only filesystem (except uploads)               │
+│     └─ Minimal base image                                   │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 💾 Storage Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                   Storage Locations                         │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  Container Storage (Ephemeral - Resets on rebuild)         │
+│  ├─ /app/app/static/uploads/wordclouds/                    │
+│  │  └─ Word cloud images (temporary)                       │
+│  └─ /app/app/database/                                     │
+│     └─ SQLite fallback (dev only)                          │
+│                                                             │
+│  External Storage (Persistent)                              │
+│  └─ PostgreSQL Database (Render/Neon)                      │
+│     ├─ users table                                          │
+│     ├─ prediction_history table                            │
+│     └─ All user data & predictions                         │
+│                                                             │
+│  Future Enhancements (Optional)                             │
+│  └─ S3 / Cloudinary for file uploads                       │
+│     └─ Persistent word clouds & CSVs                       │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 🔌 Connection Flow
+
+```
+┌────────────────────────────────────────────────────────────┐
+│                Database Connection Logic                   │
+└────────────────────────────────────────────────────────────┘
+              │
+              ▼
+    ┌─────────────────────┐
+    │ app/database.py     │
+    └─────────────────────┘
+              │
+              ▼
+    ┌─────────────────────────────────────┐
+    │ Check os.getenv("DATABASE_URL")     │
+    └─────────────────────────────────────┘
+              │
+       ┌──────┴──────┐
+       │             │
+       ▼             ▼
+   ✅ Found      ❌ Not Found
+       │             │
+       │             ▼
+       │      ┌──────────────────┐
+       │      │ Use SQLite       │
+       │      │ (Local Dev)      │
+       │      └──────────────────┘
+       │
+       ▼
+┌──────────────────────────┐
+│ Fix postgres:// URL      │
+│ (replace with            │
+│  postgresql://)          │
+└──────────────────────────┘
+       │
+       ▼
+┌──────────────────────────┐
+│ Connect to PostgreSQL    │
+│ (Production on HF)       │
+└──────────────────────────┘
+```
+
+---
+
+## 📈 Scalability Considerations
+
+```
+Current Setup (Free Tier):
+├─ 16GB RAM (sufficient for >500MB model)
+├─ Shared CPU (adequate for moderate traffic)
+└─ Unlimited uptime (99.9% availability)
+
+If Scaling Needed:
+├─ Upgrade to Pro Space ($9/month)
+│  └─ Better CPU, more RAM, priority support
+├─ Database scaling
+│  └─ Upgrade PostgreSQL plan on Render/Neon
+├─ Add caching layer
+│  └─ Redis for frequent queries
+└─ Consider load balancing
+   └─ Multiple Space instances (advanced)
+```
+
+---
+
+## 🔄 Deployment Workflow
+
+```
+┌──────────────────────────────────────────────────────────┐
+│              Local Development                           │
+│  ├─ Edit code                                           │
+│  ├─ Test with SQLite                                    │
+│  └─ Commit to Git                                       │
+└──────────────────────────────────────────────────────────┘
+                      │
+                      ▼
+┌──────────────────────────────────────────────────────────┐
+│              Push to Hugging Face                        │
+│  git push origin main                                    │
+└──────────────────────────────────────────────────────────┘
+                      │
+                      ▼
+┌──────────────────────────────────────────────────────────┐
+│              HF Spaces Auto-Build                        │
+│  ├─ Pull latest code                                    │
+│  ├─ Build Docker image (5-10 min)                       │
+│  ├─ Run container on port 7860                          │
+│  └─ Inject environment variables                        │
+└──────────────────────────────────────────────────────────┘
+                      │
+                      ▼
+┌──────────────────────────────────────────────────────────┐
+│              Application Running                         │
+│  ├─ Connect to PostgreSQL                               │
+│  ├─ Load ML model into memory                           │
+│  ├─ Start Uvicorn server                                │
+│  └─ Ready to serve requests                             │
+└──────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 📊 Resource Usage
+
+```
+Component            Memory      CPU      Disk
+─────────────────────────────────────────────────
+Base Image           ~150MB      -        ~150MB
+Python Dependencies  ~2GB        -        ~2GB
+PhoBERT Model        ~500MB      High     ~500MB
+Application Code     ~50MB       Low      ~50MB
+Runtime Data         ~100MB      Medium   ~100MB
+─────────────────────────────────────────────────
+TOTAL (approx)       ~2.8GB      -        ~2.8GB
+
+Hugging Face Provides: 16GB RAM (plenty of headroom)
+```
+
+---
+
+## 🎯 Key Architectural Decisions
+
+### Why Docker SDK?
+✅ Heavy ML model (>500MB) needs more than 512MB RAM
+✅ Full control over environment
+✅ 16GB RAM on free tier
+
+### Why External Database?
+✅ Container is ephemeral (resets on rebuild)
+✅ PostgreSQL provides persistence
+✅ Easy to scale independently
+
+### Why Port 7860?
+✅ Hugging Face Spaces requirement
+✅ Auto-routed by HF infrastructure
+✅ HTTPS provided automatically
+
+### Why Non-Root User?
+✅ Security best practice
+✅ Hugging Face Spaces requirement
+✅ UID 1000 is standard
+
+---
+
+**This architecture provides:**
+- ✅ High availability (99.9% uptime)
+- ✅ Sufficient resources (16GB RAM)
+- ✅ Secure deployment (JWT, SSL, non-root)
+- ✅ Persistent storage (external DB)
+- ✅ Cost-effective (free tier)

HF_DEPLOYMENT_CHECKLIST.md

@@ -0,0 +1,292 @@
+# ✅ Hugging Face Spaces Deployment Checklist
+
+## Pre-Deployment (Local Setup)
+
+### 1. Database Preparation
+- [ ] Create external PostgreSQL database (Render/Neon)
+- [ ] Test database connection locally
+- [ ] Run database migrations (if any)
+- [ ] Create initial admin user (optional)
+
+### 2. Code Preparation
+- [ ] Review `Dockerfile` (port 7860, user permissions)
+- [ ] Verify `requirements.txt` has all dependencies
+- [ ] Check `database.py` hybrid connection logic
+- [ ] Test application locally with Docker
+- [ ] Generate strong `SECRET_KEY`
+
+### 3. Files to Push
+- [ ] `Dockerfile` (CRITICAL)
+- [ ] `requirements.txt`
+- [ ] `main.py`
+- [ ] `app/` directory (all modules)
+- [ ] `README_HF_SPACE.md` (rename to README.md)
+- [ ] `.dockerignore`
+
+### 4. Files to EXCLUDE
+- [ ] `.env` files (secrets)
+- [ ] `env/` or `venv/` directories
+- [ ] `__pycache__/` directories
+- [ ] Local `.db` files
+- [ ] `app/static/uploads/` temporary files
+
+---
+
+## Hugging Face Spaces Setup
+
+### 1. Create New Space
+- [ ] Go to https://huggingface.co/new-space
+- [ ] Choose a memorable Space name
+- [ ] Select **Docker** SDK
+- [ ] Choose **CPU Basic** (16GB RAM - Free Tier)
+- [ ] Set visibility (Public/Private)
+- [ ] Click **Create Space**
+
+### 2. Configure Environment Variables
+Navigate to **Settings** → **Repository Secrets**
+
+**Required Secrets:**
+- [ ] Add `DATABASE_URL`
+  ```
+  postgresql://user:pass@host:port/database
+  ```
+- [ ] Add `SECRET_KEY`
+  ```
+  (generated random string, 32+ chars)
+  ```
+
+**Verify:**
+- [ ] Secrets show as `***` (hidden)
+- [ ] No typos in variable names
+- [ ] DATABASE_URL starts with `postgresql://`
+
+---
+
+## Deployment
+
+### 1. Push Code to HF Space
+```bash
+# Clone your Space repository
+git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE
+cd YOUR_SPACE
+
+# Copy project files
+# (Exclude env/, __pycache__, .db files)
+
+# IMPORTANT: Rename README
+cp README_HF_SPACE.md README.md
+
+# Initialize git (if needed)
+git init
+git remote add origin https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE
+
+# Commit and push
+git add .
+git commit -m "Initial deployment to Hugging Face Spaces"
+git push -u origin main
+```
+
+### 2. Monitor Build
+- [ ] Go to your Space URL
+- [ ] Click **Logs** tab
+- [ ] Watch Docker build process
+- [ ] Wait for "Running on http://0.0.0.0:7860" message
+- [ ] Build time: ~5-10 minutes
+
+### 3. Expected Build Stages
+```
+✅ Building Docker image...
+✅ Installing dependencies from requirements.txt...
+✅ Downloading PyTorch & Transformers (~2GB)...
+✅ Creating user 'user' (UID 1000)...
+✅ Setting permissions...
+✅ Starting uvicorn server...
+✅ Application running on port 7860
+```
+
+---
+
+## Post-Deployment Verification
+
+### 1. Check Application Status
+- [ ] Space shows "Running" status (green)
+- [ ] No errors in Logs tab
+- [ ] Access Space URL (opens app)
+
+### 2. Test Database Connection
+Expected log message:
+```
+🚀 Production Mode: Using PostgreSQL
+```
+
+If you see this instead:
+```
+🔧 Development Mode: Using SQLite
+```
+→ DATABASE_URL is missing or incorrect
+
+### 3. Test Core Functionality
+- [ ] Access `/docs` (Swagger UI loads)
+- [ ] Register a new user
+- [ ] Login successfully
+- [ ] Access dashboard
+- [ ] Make a single prediction
+- [ ] Upload CSV for batch prediction
+- [ ] View prediction history
+- [ ] Word cloud generates
+- [ ] Charts display correctly
+
+### 4. Security Verification
+- [ ] Cannot access protected routes without JWT
+- [ ] Passwords are hashed (check database)
+- [ ] JWT tokens expire after 24 hours
+- [ ] HTTPS is enabled (HF provides this)
+
+---
+
+## Troubleshooting
+
+### Issue: Build Failed
+**Check:**
+- [ ] Dockerfile syntax errors
+- [ ] Missing dependencies in requirements.txt
+- [ ] Python version compatibility
+- [ ] Check Logs for specific error
+
+### Issue: "Application startup failed"
+**Check:**
+- [ ] DATABASE_URL is set correctly
+- [ ] Database is accessible (not firewalled)
+- [ ] SECRET_KEY is set
+- [ ] Port 7860 is used in CMD
+
+### Issue: "502 Bad Gateway"
+**Check:**
+- [ ] App is still starting (wait 2-3 min)
+- [ ] Heavy model loading in progress
+- [ ] Check Logs for crash/errors
+
+### Issue: Database Connection Error
+**Check:**
+- [ ] DATABASE_URL format is correct
+- [ ] Database host is reachable
+- [ ] Username/password are correct
+- [ ] Database allows external connections
+
+### Issue: JWT Token Invalid
+**Check:**
+- [ ] SECRET_KEY is set correctly
+- [ ] SECRET_KEY hasn't changed
+- [ ] Token hasn't expired (24h)
+- [ ] Clear browser localStorage
+
+---
+
+## Maintenance
+
+### Regular Tasks
+- [ ] Monitor Space usage (CPU/Memory)
+- [ ] Check application logs weekly
+- [ ] Rotate SECRET_KEY every 90 days
+- [ ] Backup PostgreSQL database regularly
+- [ ] Update dependencies monthly
+
+### Updating the App
+```bash
+# Make changes locally
+git add .
+git commit -m "Update: description"
+git push
+
+# HF will automatically rebuild
+# Monitor Logs tab for build status
+```
+
+### Scaling Considerations
+If you exceed Free Tier limits:
+- [ ] Upgrade to **Pro** Space (better hardware)
+- [ ] Consider upgrading database plan
+- [ ] Implement caching (Redis)
+- [ ] Optimize model loading
+
+---
+
+## Performance Optimization
+
+### For Heavy Models
+- [ ] Use model quantization (reduces size)
+- [ ] Cache model in memory (don't reload)
+- [ ] Use CPU inference (GPU costs more)
+- [ ] Implement request queuing
+
+### For High Traffic
+- [ ] Add rate limiting
+- [ ] Implement Redis caching
+- [ ] Use CDN for static files
+- [ ] Optimize database queries
+- [ ] Add connection pooling
+
+---
+
+## Security Hardening
+
+### Production Checklist
+- [ ] Use strong SECRET_KEY (32+ chars)
+- [ ] Enable DATABASE SSL (sslmode=require)
+- [ ] Implement rate limiting
+- [ ] Add CORS restrictions
+- [ ] Log all authentication attempts
+- [ ] Implement password strength requirements
+- [ ] Add 2FA (future enhancement)
+- [ ] Regular security audits
+
+---
+
+## Rollback Plan
+
+If deployment fails:
+
+### Option 1: Revert Git Commit
+```bash
+git revert HEAD
+git push
+```
+
+### Option 2: Delete and Recreate Space
+1. Delete current Space
+2. Create new Space with same name
+3. Re-add environment variables
+4. Push working version
+
+### Option 3: Use Previous Docker Image
+HF keeps previous builds for Pro users
+
+---
+
+## Success Criteria
+
+Deployment is successful when:
+- ✅ Space status is "Running"
+- ✅ No errors in Logs
+- ✅ PostgreSQL connection established
+- ✅ All API endpoints respond
+- ✅ Frontend loads correctly
+- ✅ Users can register and login
+- ✅ Predictions work (single + batch)
+- ✅ Visualizations generate
+- ✅ JWT authentication works
+
+---
+
+## Support Resources
+
+- 📖 [Hugging Face Spaces Docs](https://huggingface.co/docs/hub/spaces-overview)
+- 📖 [Docker SDK Guide](https://huggingface.co/docs/hub/spaces-sdks-docker)
+- 📖 [FastAPI Documentation](https://fastapi.tiangolo.com)
+- 📖 [SQLAlchemy Docs](https://docs.sqlalchemy.org)
+- 💬 [HF Community Forum](https://discuss.huggingface.co)
+
+---
+
+**Last Updated:** December 2025
+**Version:** 1.0.0

HF_ENV_VARIABLES.md

@@ -0,0 +1,177 @@
+# 🔐 Hugging Face Spaces Environment Variables
+
+## Required Secrets (Add in Settings → Repository Secrets)
+
+### 1. DATABASE_URL
+**Purpose:** PostgreSQL connection string for external database
+
+**Format:**
+```
+DATABASE_URL=postgresql://username:password@host:port/database
+```
+
+**Real Examples:**
+
+**Render PostgreSQL:**
+```
+DATABASE_URL=postgresql://myuser:mypass123@dpg-abcd1234.oregon-postgres.render.com/mydb
+```
+
+**Neon PostgreSQL:**
+```
+DATABASE_URL=postgresql://myuser:mypass123@ep-xyz789.us-east-2.aws.neon.tech/mydb?sslmode=require
+```
+
+**⚠️ Important:**
+- MUST start with `postgresql://` (NOT `postgres://`)
+- The app auto-converts `postgres://` → `postgresql://`
+- Include port if different from 5432
+- Add `?sslmode=require` for secure connections
+
+---
+
+### 2. SECRET_KEY
+**Purpose:** JWT token signing and session security
+
+**Format:**
+```
+SECRET_KEY=your-super-secret-random-string-min-32-characters
+```
+
+**How to Generate:**
+```bash
+# Method 1: Using Python
+python -c "import secrets; print(secrets.token_urlsafe(32))"
+
+# Method 2: Using OpenSSL
+openssl rand -base64 32
+
+# Method 3: Using pwgen
+pwgen -s 64 1
+```
+
+**Example Output:**
+```
+SECRET_KEY=xK7mP9vR2nQ5wT8yU4eL6hG3jN0bM1cF5sA9dH2kV7pW4qX8zR6tY3nM5
+```
+
+**⚠️ Security Rules:**
+- NEVER commit to Git
+- Minimum 32 characters
+- Use cryptographically secure random generation
+- Different for each environment (dev/staging/prod)
+
+---
+
+## Optional Environment Variables
+
+### PORT (Pre-configured)
+**Default:** `7860` (Required by Hugging Face Spaces)
+**DO NOT CHANGE** - The Dockerfile is already configured
+
+### PYTHONUNBUFFERED (Pre-configured)
+**Default:** `1`
+**Purpose:** Real-time log output in HF Spaces
+
+---
+
+## How to Add Secrets in Hugging Face Spaces
+
+1. **Navigate to Settings:**
+   - Go to your Space: `https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE`
+   - Click **Settings** (gear icon)
+
+2. **Add Repository Secrets:**
+   - Scroll to **Repository Secrets** section
+   - Click **New Secret**
+   
+3. **Add DATABASE_URL:**
+   - Name: `DATABASE_URL`
+   - Value: `postgresql://user:pass@host:port/db`
+   - Click **Add Secret**
+
+4. **Add SECRET_KEY:**
+   - Name: `SECRET_KEY`
+   - Value: (your generated secret key)
+   - Click **Add Secret**
+
+5. **Verify:**
+   - Secrets should show as `***` (hidden)
+   - They will be injected at runtime
+   - NOT visible in logs
+
+---
+
+## Verification Checklist
+
+After adding secrets, verify:
+
+- [ ] `DATABASE_URL` starts with `postgresql://`
+- [ ] `DATABASE_URL` includes username and password
+- [ ] `DATABASE_URL` has correct host and port
+- [ ] `SECRET_KEY` is at least 32 characters
+- [ ] `SECRET_KEY` is randomly generated
+- [ ] Secrets are marked as **hidden** in Settings
+- [ ] No secrets are in Git repository
+
+---
+
+## Testing Database Connection
+
+**Before deploying**, test your database URL locally:
+
+```bash
+# Test with psql (if installed)
+psql "postgresql://user:pass@host:port/db"
+
+# Test with Python
+python -c "
+from sqlalchemy import create_engine
+url = 'postgresql://user:pass@host:port/db'
+engine = create_engine(url)
+with engine.connect() as conn:
+    print('✅ Connection successful!')
+"
+```
+
+---
+
+## Troubleshooting
+
+### Error: "could not translate host name"
+**Cause:** Invalid host in DATABASE_URL
+**Fix:** Verify host from your database provider
+
+### Error: "password authentication failed"
+**Cause:** Wrong username or password
+**Fix:** Check credentials in your database dashboard
+
+### Error: "no pg_hba.conf entry for host"
+**Cause:** Database firewall blocks external connections
+**Fix:** Whitelist all IPs (0.0.0.0/0) in database settings
+
+### Error: "JWT token invalid"
+**Cause:** SECRET_KEY mismatch or expired token
+**Fix:** Ensure SECRET_KEY is consistent and not changed
+
+---
+
+## Security Best Practices
+
+✅ **DO:**
+- Use HF Spaces Secrets for sensitive data
+- Generate strong random keys
+- Use SSL for database connections (`sslmode=require`)
+- Rotate SECRET_KEY periodically
+- Use different keys per environment
+
+❌ **DON'T:**
+- Hardcode secrets in code
+- Commit `.env` files to Git
+- Share SECRET_KEY publicly
+- Use weak/predictable keys
+- Reuse keys across projects
+
+---
+
+**Last Updated:** December 2025

HF_MIGRATION_SUMMARY.md

@@ -0,0 +1,314 @@
+# 📦 Hugging Face Spaces Migration - Complete Summary
+
+## ✅ Migration Completed Successfully
+
+Your FastAPI application has been fully prepared for deployment on **Hugging Face Spaces** with Docker SDK.
+
+---
+
+## 📁 Files Created/Modified
+
+### 🆕 New Files Created
+
+1. **`Dockerfile`** ⭐ CRITICAL
+   - Optimized for Hugging Face Spaces
+   - Uses `python:3.10-slim` base image
+   - Creates non-root user (UID 1000)
+   - Exposes port 7860 (HF requirement)
+   - Proper permissions for write directories
+
+2. **`.dockerignore`**
+   - Excludes unnecessary files from Docker build
+   - Reduces image size
+   - Speeds up build time
+
+3. **`HUGGING_FACE_DEPLOYMENT.md`**
+   - Complete deployment guide
+   - Step-by-step instructions
+   - Troubleshooting section
+   - Security checklist
+
+4. **`HF_ENV_VARIABLES.md`**
+   - Detailed guide for environment variables
+   - How to generate SECRET_KEY
+   - Database URL formats
+   - Security best practices
+
+5. **`HF_DEPLOYMENT_CHECKLIST.md`**
+   - Pre-deployment checklist
+   - Build monitoring steps
+   - Post-deployment verification
+   - Troubleshooting guide
+
+6. **`README_HF_SPACE.md`**
+   - README for Hugging Face Space page
+   - Contains YAML frontmatter for HF
+   - User-facing documentation
+
+7. **`test_docker_local.py`**
+   - Python script to test Docker setup locally
+   - Verifies build and runtime
+   - Tests endpoints
+   - Auto-cleanup
+
+### 🔄 Files Modified
+
+1. **`requirements.txt`**
+   - ✅ Removed `gunicorn` (not needed for Docker)
+   - ✅ Removed `argon2-cffi` (using bcrypt)
+   - ✅ Kept `psycopg2-binary` for PostgreSQL
+   - ✅ Adjusted version constraints for compatibility
+   - ✅ Added `aiofiles` for async file operations
+
+2. **`app/database.py`** ✅ Already Correct
+   - Hybrid connection logic present
+   - Auto-converts `postgres://` → `postgresql://`
+   - Falls back to SQLite for local dev
+
+3. **`app/config.py`** ✅ Already Correct
+   - Reads `SECRET_KEY` from environment
+   - Reads `DATABASE_URL` from environment
+   - Has fallback values for local dev
+
+---
+
+## 🔐 Required Environment Variables
+
+You MUST add these in Hugging Face Spaces **Settings** → **Repository Secrets**:
+
+### 1. DATABASE_URL (REQUIRED)
+```
+DATABASE_URL=postgresql://username:password@host:port/database
+```
+
+**Example (Render):**
+```
+DATABASE_URL=postgresql://myuser:mypass@dpg-abc123.oregon-postgres.render.com/mydb
+```
+
+**Example (Neon):**
+```
+DATABASE_URL=postgresql://myuser:mypass@ep-xyz789.us-east-2.aws.neon.tech/mydb?sslmode=require
+```
+
+### 2. SECRET_KEY (REQUIRED)
+```
+SECRET_KEY=your-super-secret-random-string-minimum-32-characters
+```
+
+**Generate with:**
+```bash
+python -c "import secrets; print(secrets.token_urlsafe(32))"
+```
+
+---
+
+## 🚀 Deployment Steps
+
+### Step 1: Create Hugging Face Space
+1. Go to https://huggingface.co/new-space
+2. Name your Space (e.g., `product-rating-prediction`)
+3. Select **Docker** SDK
+4. Choose **CPU Basic** (16GB RAM - Free)
+5. Click **Create Space**
+
+### Step 2: Add Environment Variables
+1. Go to Space **Settings**
+2. Scroll to **Repository Secrets**
+3. Add `DATABASE_URL` (your PostgreSQL connection string)
+4. Add `SECRET_KEY` (your generated key)
+
+### Step 3: Prepare Code
+```bash
+# In your project directory
+# Rename README for HF Space
+copy README_HF_SPACE.md README.md
+
+# Remove unnecessary files
+rmdir /s /q env
+rmdir /s /q __pycache__
+del /q app\database\*.db
+```
+
+### Step 4: Push to Hugging Face
+```bash
+# Clone your Space repo
+git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE
+cd YOUR_SPACE
+
+# Copy all project files (except excluded ones)
+# Use .dockerignore as reference for what to exclude
+
+# Commit and push
+git add .
+git commit -m "Initial deployment"
+git push origin main
+```
+
+### Step 5: Monitor Build
+1. Go to your Space URL
+2. Click **Logs** tab
+3. Watch for successful build
+4. Wait for "Running on http://0.0.0.0:7860"
+
+---
+
+## 🧪 Test Locally First (RECOMMENDED)
+
+Before deploying to Hugging Face, test locally:
+
+### Option 1: Automated Test Script
+```bash
+# Set environment variables (optional)
+set DATABASE_URL=postgresql://user:pass@host/db
+set SECRET_KEY=your-secret-key
+
+# Run test script
+python test_docker_local.py
+```
+
+### Option 2: Manual Docker Test
+```bash
+# Build image
+docker build -t rating-prediction .
+
+# Run container
+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
+```
+
+---
+
+## 📊 Key Differences from Render
+
+| Feature | Render | Hugging Face Spaces |
+|---------|--------|---------------------|
+| **Deployment** | Web Service | Docker SDK |
+| **Port** | Auto-assigned | 7860 (fixed) |
+| **Start Command** | Procfile | Dockerfile CMD |
+| **RAM** | 512MB (Free) | 16GB (Free) |
+| **Database** | Managed PostgreSQL | External (your choice) |
+| **User** | root | user (UID 1000) |
+| **Build** | Automatic | Dockerfile |
+
+---
+
+## 🎯 Critical Configuration Points
+
+### ✅ Port 7860
+The Dockerfile MUST use port 7860:
+```dockerfile
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "7860"]
+```
+
+### ✅ Non-Root User
+The Dockerfile MUST create and switch to user:
+```dockerfile
+RUN useradd -m -u 1000 user
+USER user
+```
+
+### ✅ Write Permissions
+Directories that need write access:
+```dockerfile
+RUN chmod -R 777 /app/app/static/uploads
+RUN chmod -R 777 /app/app/database
+```
+
+### ✅ Database URL
+Your app correctly handles both:
+- `postgresql://` (standard)
+- `postgres://` (auto-converted)
+
+---
+
+## 🔍 Verification Checklist
+
+After deployment, verify:
+
+- [ ] Space status shows "Running" (green)
+- [ ] Logs show: "🚀 Production Mode: Using PostgreSQL"
+- [ ] Access `/docs` (Swagger UI loads)
+- [ ] Can register a new user
+- [ ] Can login and get JWT token
+- [ ] Dashboard loads correctly
+- [ ] Single prediction works
+- [ ] Batch CSV upload works
+- [ ] Word cloud generates
+- [ ] Charts display
+
+---
+
+## 🐛 Common Issues & Solutions
+
+### Issue: "Application startup failed"
+**Solution:** Check DATABASE_URL in Settings → Secrets
+
+### Issue: "Database connection refused"
+**Solution:** Ensure PostgreSQL allows external connections
+
+### Issue: "502 Bad Gateway"
+**Solution:** Wait 2-3 minutes for model loading
+
+### Issue: "Permission denied" errors
+**Solution:** Verify user permissions in Dockerfile
+
+---
+
+## 📚 Documentation Reference
+
+1. **`HUGGING_FACE_DEPLOYMENT.md`** - Full deployment guide
+2. **`HF_ENV_VARIABLES.md`** - Environment variables details
+3. **`HF_DEPLOYMENT_CHECKLIST.md`** - Step-by-step checklist
+4. **`README_HF_SPACE.md`** - Space homepage content
+5. **`test_docker_local.py`** - Local testing script
+
+---
+
+## 🎉 Success Criteria
+
+Your deployment is successful when:
+
+✅ Docker image builds without errors
+✅ Container starts on port 7860
+✅ PostgreSQL connection established
+✅ All API endpoints respond
+✅ Authentication works (register/login)
+✅ Predictions complete successfully
+✅ Visualizations generate correctly
+
+---
+
+## 🆘 Support & Resources
+
+- 📖 [HF Spaces Docker Guide](https://huggingface.co/docs/hub/spaces-sdks-docker)
+- 📖 [FastAPI Documentation](https://fastapi.tiangolo.com)
+- 💬 [HF Community Forum](https://discuss.huggingface.co)
+
+---
+
+## 🔄 Next Steps
+
+1. ✅ Create external PostgreSQL database (Render/Neon)
+2. ✅ Generate SECRET_KEY
+3. ✅ Test Docker build locally (optional but recommended)
+4. ✅ Create Hugging Face Space
+5. ✅ Add environment variables
+6. ✅ Push code to HF Space
+7. ✅ Monitor build and verify deployment
+8. ✅ Test application functionality
+9. ✅ Share your Space with users! 🎉
+
+---
+
+**Migration completed on:** December 1, 2025
+**Target Platform:** Hugging Face Spaces (Docker SDK)
+**Status:** ✅ Ready for Deployment
+
+---
+
+**Good luck with your deployment! 🚀**

HF_QUICK_REFERENCE.md

@@ -0,0 +1,163 @@
+# 🚀 Hugging Face Spaces - Quick Reference Card
+
+## ⚡ Quick Deploy (5 Steps)
+
+```bash
+# 1. Create Space on HF
+https://huggingface.co/new-space → Docker SDK → CPU Basic
+
+# 2. Add Secrets (Settings → Repository Secrets)
+DATABASE_URL = postgresql://user:pass@host:port/db
+SECRET_KEY = <generate with: python -c "import secrets; print(secrets.token_urlsafe(32))">
+
+# 3. Clone Space repo
+git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE
+cd YOUR_SPACE
+
+# 4. Copy project files
+# Copy all except: env/, __pycache__/, *.db, .env
+
+# 5. Push
+git add .
+git commit -m "Initial deployment"
+git push origin main
+```
+
+---
+
+## 🔐 Environment Variables
+
+| Variable | Required | Example |
+|----------|----------|---------|
+| `DATABASE_URL` | ✅ Yes | `postgresql://user:pass@host:5432/db` |
+| `SECRET_KEY` | ✅ Yes | `xK7mP9vR2nQ5wT8yU4eL6hG3jN0bM...` |
+
+---
+
+## 📋 Critical Files Checklist
+
+```
+✅ Dockerfile (port 7860, user 1000)
+✅ requirements.txt (no gunicorn)
+✅ main.py
+✅ app/ directory
+✅ .dockerignore
+✅ README.md (from README_HF_SPACE.md)
+```
+
+---
+
+## 🐳 Dockerfile Must-Haves
+
+```dockerfile
+# ✅ Port 7860 (HF requirement)
+EXPOSE 7860
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "7860"]
+
+# ✅ User ID 1000 (HF requirement)
+RUN useradd -m -u 1000 user
+USER user
+
+# ✅ Write permissions
+RUN chmod -R 777 /app/app/static/uploads
+```
+
+---
+
+## 🧪 Test Locally
+
+```bash
+# Build
+docker build -t test .
+
+# Run
+docker run -p 7860:7860 \
+  -e DATABASE_URL="postgresql://..." \
+  -e SECRET_KEY="..." \
+  test
+
+# Access
+http://localhost:7860
+```
+
+---
+
+## 🔍 Verify Deployment
+
+```
+✅ Space shows "Running" status
+✅ Logs show: "🚀 Production Mode: Using PostgreSQL"
+✅ Access /docs (Swagger UI)
+✅ Can register and login
+✅ Predictions work
+```
+
+---
+
+## 🐛 Common Errors
+
+| Error | Fix |
+|-------|-----|
+| App startup failed | Check DATABASE_URL in Secrets |
+| 502 Bad Gateway | Wait 2-3 min for model loading |
+| Permission denied | Check Dockerfile user permissions |
+| Database refused | Allow external connections in DB |
+
+---
+
+## 📊 Key Differences: Render vs HF
+
+| | Render | Hugging Face |
+|-|--------|--------------|
+| RAM | 512MB | 16GB |
+| Port | Auto | 7860 (fixed) |
+| Deploy | Procfile | Dockerfile |
+| User | root | user (1000) |
+
+---
+
+## 📚 Documentation Files
+
+- `HUGGING_FACE_DEPLOYMENT.md` - Full guide
+- `HF_ENV_VARIABLES.md` - Secrets setup
+- `HF_DEPLOYMENT_CHECKLIST.md` - Step-by-step
+- `HF_MIGRATION_SUMMARY.md` - Overview
+
+---
+
+## 🆘 Emergency Commands
+
+```bash
+# View logs
+# Go to Space → Logs tab
+
+# Rebuild
+git commit --allow-empty -m "Rebuild"
+git push
+
+# Rollback
+git revert HEAD
+git push
+```
+
+---
+
+## ✅ Success Indicators
+
+```
+INFO:     Started server process [1]
+INFO:     Uvicorn running on http://0.0.0.0:7860
+🚀 Production Mode: Using PostgreSQL
+```
+
+---
+
+## 🔗 Important Links
+
+- Create Space: https://huggingface.co/new-space
+- HF Docs: https://huggingface.co/docs/hub/spaces-sdks-docker
+- FastAPI Docs: https://fastapi.tiangolo.com
+
+---
+
+**Print this for quick reference during deployment! 📄**

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

@@ -1,10 +1,253 @@
----
-title: Predict Rating
-emoji: 🏆
-colorFrom: gray
-colorTo: blue
-sdk: docker
-pinned: false
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Vietnamese Product Rating Prediction System
+
+## 🎯 Project Overview
+A full-stack web application that predicts sentiment ratings (1-5 stars) for Vietnamese product reviews using Machine Learning.
+
+**Built for:** Introduction to Machine Learning - University Project  
+**Tech Stack:** FastAPI + Jinja2 + TailwindCSS + SQLite + Chart.js
+
+---
+
+## 📁 Project Structure
+
+```
+PredictRating/
+├── app/
+│   ├── database/              # SQLite database storage
+│   ├── routers/              # API route handlers
+│   │   ├── auth.py           # Authentication endpoints
+│   │   ├── prediction.py     # Prediction endpoints
+│   │   └── dashboard.py      # Frontend routes
+│   ├── services/             # Business logic
+│   │   ├── auth_service.py   # JWT & password handling
+│   │   ├── ml_service.py     # ML prediction (DUMMY - replace with your model)
+│   │   └── visualization_service.py  # WordCloud & charts
+│   ├── static/               # Static files (CSS, JS, uploads)
+│   │   └── uploads/
+│   │       └── wordclouds/   # Generated word cloud images
+│   ├── templates/            # Jinja2 HTML templates
+│   │   ├── base.html         # Base layout
+│   │   ├── login.html        # Login page
+│   │   ├── register.html     # Registration page
+│   │   └── dashboard.html    # Main prediction interface
+│   ├── config.py             # Configuration settings
+│   ├── database.py           # Database connection
+│   ├── models.py             # SQLAlchemy models (User, PredictionHistory)
+│   └── schemas.py            # Pydantic validation schemas
+├── main.py                   # FastAPI application entry point
+└── requirements.txt          # Python dependencies
+```
+
+---
+
+## 🚀 Setup Instructions
+
+### 1. Install Dependencies
+
+```bash
+pip install -r requirements.txt
+```
+
+### 2. Run the Application
+
+```bash
+python main.py
+```
+
+The server will start at: **http://localhost:8000**
+
+### 3. Access the Application
+
+- **Frontend Dashboard:** http://localhost:8000/dashboard
+- **API Documentation (Swagger UI):** http://localhost:8000/docs  ⭐ **SHOW THIS TO YOUR TEACHER**
+- **Alternative API Docs (ReDoc):** http://localhost:8000/redoc
+
+---
+
+## 📚 API Documentation (Swagger UI)
+
+FastAPI automatically generates **interactive API documentation** at `/docs`.
+
+### How to Access:
+1. Run the application
+2. Open browser: **http://localhost:8000/docs**
+3. You'll see all API endpoints with:
+   - Request/response schemas
+   - Try it out functionality
+   - Authentication support
+
+### Key API Endpoints:
+
+#### Authentication
+- `POST /api/auth/register` - Register new user
+- `POST /api/auth/login` - Login (get JWT token)
+- `GET /api/auth/me` - Get current user info
+
+#### Predictions
+- `POST /api/predict/single` - Predict single comment
+- `POST /api/predict/batch` - Predict batch from CSV
+- `GET /api/predict/history` - Get prediction history
+
+---
+
+## 🎓 How to Use (User Journey)
+
+### Step 1: Register/Login
+1. Go to http://localhost:8000/login
+2. Register a new account or login
+3. You'll be redirected to the dashboard
+
+### Step 2: Select Product
+- Choose a target product from the dropdown list
+
+### Step 3A: Single Comment Prediction
+1. Click "Single Comment" tab
+2. Enter a Vietnamese product review
+3. Click "Predict Rating"
+4. See the predicted rating (1-5 stars) with confidence score
+
+### Step 3B: Batch CSV Prediction
+1. Click "Upload CSV" tab
+2. Upload a CSV file with a `Comment` column
+3. Click "Predict Batch"
+4. View results:
+   - **Bar Chart:** Rating distribution (how many 1⭐, 2⭐, etc.)
+   - **Word Cloud:** Most frequent words in comments
+   - **Table:** All predictions with confidence scores
+   - **Download:** Export results as CSV with `Predicted_Rating` column
+
+---
+
+## 🔧 Replace Dummy ML Model
+
+The current `ml_service.py` uses a **DUMMY** prediction function. Replace it with your real model:
+
+### File: `app/services/ml_service.py`
+
+```python
+class MLPredictionService:
+    def __init__(self):
+        # TODO: Load your trained model
+        self.model = load_model('path/to/your/model.h5')  # Example
+        self.tokenizer = load_tokenizer('path/to/tokenizer.pkl')
+    
+    def predict_single(self, text: str) -> Dict[str, any]:
+        # TODO: Implement your preprocessing
+        preprocessed = self.preprocess(text)
+        
+        # TODO: Make prediction with your model
+        prediction = self.model.predict(preprocessed)
+        rating = self.postprocess(prediction)  # Convert to 1-5
+        
+        return {
+            'rating': rating,
+            'confidence': prediction.max()
+        }
+```
+
+---
+
+## 📊 Database Schema
+
+### Users Table
+- `id`: Primary key
+- `username`: Unique username
+- `email`: Unique email
+- `hashed_password`: Bcrypt hashed password
+- `created_at`: Registration timestamp
+
+### Prediction History Table
+- `id`: Primary key
+- `user_id`: Foreign key to Users
+- `product_name`: Product name
+- `comment`: Original comment
+- `predicted_rating`: Predicted rating (1-5)
+- `confidence_score`: Confidence (0-1)
+- `prediction_type`: 'single' or 'batch'
+- `created_at`: Prediction timestamp
+
+---
+
+## 🎨 Features
+
+✅ **Authentication:** JWT-based secure login/registration  
+✅ **Single Prediction:** Predict one comment at a time  
+✅ **Batch Prediction:** Upload CSV and predict multiple comments  
+✅ **Visualization:**
+  - Bar chart for rating distribution  
+  - Word cloud for frequent words  
+✅ **History Tracking:** All predictions saved to database  
+✅ **CSV Export:** Download results with predicted ratings  
+✅ **Responsive UI:** TailwindCSS mobile-friendly design  
+✅ **API Documentation:** Auto-generated Swagger UI  
+
+---
+
+## 🏆 Bonus Points for Teacher Demo
+
+1. **Show Swagger UI** at `/docs` - Automatic API documentation ⭐
+2. **Demonstrate:**
+   - User registration/login flow
+   - Single comment prediction
+   - CSV batch upload with visualizations
+   - Download CSV results
+3. **Explain:**
+   - Clean separation of concerns (routers, services, models)
+   - RESTful API design
+   - JWT authentication
+   - Database relationships
+
+---
+
+## 📝 CSV File Format
+
+Your CSV file should have at least a `Comment` column:
+
+```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"
+```
+
+After prediction, you'll get:
+
+```csv
+Comment,Predicted_Rating,Confidence
+"Sản phẩm rất tốt, đóng gói cẩn thận",5,0.95
+"Chất lượng kém, không như mô tả",1,0.88
+"Giao hàng nhanh, sản phẩm ổn",4,0.92
+```
+
+---
+
+## 🔐 Security Notes
+
+- Change `SECRET_KEY` in `app/config.py` before deployment
+- Passwords are hashed using bcrypt
+- JWT tokens expire after 24 hours
+- CORS is enabled for development (configure for production)
+
+---
+
+## 🐛 Troubleshooting
+
+### Issue: "Import errors" when running
+**Solution:** Make sure all dependencies are installed:
+```bash
+pip install -r requirements.txt
+```
+
+### Issue: "Database errors"
+**Solution:** Delete `app/database/rating_prediction.db` and restart the app to recreate tables
+
+### Issue: "Word cloud doesn't display"
+**Solution:** Check that `app/static/uploads/wordclouds/` directory exists
+
+---
+
+## 📧 Support
+
+For questions about the project structure or implementation, refer to the code comments or consult your instructor.
+
+**Good luck with your project presentation! 🎓**

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!**

TESTING_GUIDE.md

@@ -0,0 +1,287 @@
+# 🧪 Testing Guide - Step by Step
+
+## Pre-requisites
+```bash
+# Make sure dependencies are installed
+pip install -r requirements.txt
+
+# Start the server
+python main.py
+```
+
+Server should start at: **http://localhost:8000**
+
+---
+
+## ✅ Test 1: Access Swagger UI (API Documentation)
+
+### Steps:
+1. Open browser: **http://localhost:8000/docs**
+2. You should see:
+   - "Vietnamese Product Rating Prediction API" title
+   - Three sections: Authentication, Prediction, Dashboard
+   - All endpoints listed with descriptions
+
+### What to show teacher:
+- This is **automatic API documentation** (bonus points!)
+- Click any endpoint to see request/response schemas
+- Click "Try it out" to test endpoints interactively
+
+**Status:** ✅ PASS / ❌ FAIL
+
+---
+
+## ✅ Test 2: User Registration
+
+### Steps:
+1. Go to: **http://localhost:8000/register**
+2. Fill in:
+   - Username: `testuser1`
+   - Email: `test@example.com`
+   - Password: `password123`
+3. Click "Register"
+4. Should redirect to login page
+
+### Expected Result:
+- Green success message appears
+- Redirects to `/login` after 1.5 seconds
+
+**Status:** ✅ PASS / ❌ FAIL
+
+---
+
+## ✅ Test 3: User Login
+
+### Steps:
+1. Go to: **http://localhost:8000/login**
+2. Enter:
+   - Username: `testuser1`
+   - Password: `password123`
+3. Click "Login"
+
+### Expected Result:
+- Green "Login successful!" message
+- Redirects to `/dashboard`
+- You see username in top-right corner
+
+**Status:** ✅ PASS / ❌ FAIL
+
+---
+
+## ✅ Test 4: Single Comment Prediction
+
+### Steps:
+1. On dashboard, select a product from dropdown (e.g., "Điện thoại iPhone 15 Pro Max")
+2. Make sure "Single Comment" tab is active
+3. Enter Vietnamese comment:
+   ```
+   Sản phẩm rất tốt, chất lượng cao, đóng gói cẩn thận. Rất hài lòng!
+   ```
+4. Click "Predict Rating"
+
+### Expected Result:
+- Green result box appears below
+- Shows predicted rating (1-5)
+- Shows confidence percentage
+- Shows star rating (⭐⭐⭐⭐⭐)
+
+**Status:** ✅ PASS / ❌ FAIL
+
+---
+
+## ✅ Test 5: Batch CSV Prediction
+
+### Steps:
+1. Select a product from dropdown
+2. Click "Upload CSV" tab
+3. Click "Choose File" and select `sample_comments.csv`
+4. File name should display: "Selected: sample_comments.csv"
+5. Click "Predict Batch"
+
+### Expected Result:
+- Results section appears with 3 components:
+
+**A) Bar Chart:**
+- Shows distribution of ratings (1⭐ to 5⭐)
+- Colored bars (red for 1-star, green for 5-star)
+
+**B) Word Cloud:**
+- Image showing frequent Vietnamese words
+- Larger words appear more frequently in comments
+
+**C) Results Table:**
+- Shows all comments with predicted ratings
+- Each row has: Comment | Rating | Confidence
+
+**Status:** ✅ PASS / ❌ FAIL
+
+---
+
+## ✅ Test 6: Download CSV Results
+
+### Steps:
+1. After batch prediction (Test 5), scroll to results table
+2. Click "Download CSV" button (green button, top-right of table)
+
+### Expected Result:
+- CSV file downloads automatically
+- Filename format: `predictions_[timestamp].csv`
+- File contains columns: `Comment`, `Predicted_Rating`, `Confidence`
+
+### Verify downloaded file:
+- Open in Excel/Notepad
+- Should have all 20 comments from `sample_comments.csv`
+- Each has a predicted rating and confidence score
+
+**Status:** ✅ PASS / ❌ FAIL
+
+---
+
+## ✅ Test 7: Test Swagger UI Endpoints
+
+### Steps:
+1. Go to: **http://localhost:8000/docs**
+2. Find "POST /api/auth/login" endpoint
+3. Click "Try it out"
+4. Enter:
+   ```json
+   username: testuser1
+   password: password123
+   ```
+5. Click "Execute"
+
+### Expected Result:
+- Response Code: 200
+- Response body contains:
+  ```json
+  {
+    "access_token": "eyJ0eXAiOiJKV1Q...",
+    "token_type": "bearer"
+  }
+  ```
+
+### Test authenticated endpoint:
+1. Copy the `access_token` value
+2. Click "Authorize" button (top-right, with lock icon)
+3. Paste token in "Value" field: `Bearer YOUR_TOKEN_HERE`
+4. Click "Authorize" then "Close"
+5. Try "GET /api/auth/me" endpoint
+6. Click "Try it out" → "Execute"
+
+### Expected Result:
+- Response Code: 200
+- Shows your user info (username, email, etc.)
+
+**Status:** ✅ PASS / ❌ FAIL
+
+---
+
+## ✅ Test 8: Logout
+
+### Steps:
+1. On dashboard, click "Logout" button (top-right, red button)
+
+### Expected Result:
+- Redirects to `/login` page
+- Token is cleared from browser storage
+
+**Status:** ✅ PASS / ❌ FAIL
+
+---
+
+## ✅ Test 9: Protected Route (Authentication Check)
+
+### Steps:
+1. After logout, try to access: **http://localhost:8000/dashboard**
+2. Open browser console (F12)
+
+### Expected Result:
+- JavaScript checks for token
+- Redirects back to `/login` because no token exists
+
+**Status:** ✅ PASS / ❌ FAIL
+
+---
+
+## ✅ Test 10: Database Persistence
+
+### Steps:
+1. Stop the server (Ctrl+C)
+2. Start it again: `python main.py`
+3. Go to login page
+4. Login with previous credentials (`testuser1` / `password123`)
+
+### Expected Result:
+- Login works (user data persisted in database)
+- Dashboard loads successfully
+
+**Status:** ✅ PASS / ❌ FAIL
+
+---
+
+## 🐛 Troubleshooting
+
+### Error: "Module not found"
+```bash
+pip install -r requirements.txt
+```
+
+### Error: "Port 8000 already in use"
+- Kill other process using port 8000
+- Or change port in `main.py`: `uvicorn.run(..., port=8001)`
+
+### Error: "Database is locked"
+- Close all instances of the application
+- Delete `app/database/rating_prediction.db`
+- Restart application (will create new database)
+
+### Word cloud doesn't show
+- Check folder exists: `app/static/uploads/wordclouds/`
+- Check server console for errors
+
+### CSV upload fails
+- Ensure CSV has "Comment" column (case-sensitive)
+- Check CSV is UTF-8 encoded
+- Make sure comments are not empty
+
+---
+
+## 📊 Test Results Summary
+
+| Test | Description | Status |
+|------|-------------|--------|
+| 1 | Swagger UI Access | ⬜ |
+| 2 | User Registration | ⬜ |
+| 3 | User Login | ⬜ |
+| 4 | Single Prediction | ⬜ |
+| 5 | Batch CSV Prediction | ⬜ |
+| 6 | CSV Download | ⬜ |
+| 7 | Swagger API Testing | ⬜ |
+| 8 | Logout | ⬜ |
+| 9 | Auth Protection | ⬜ |
+| 10 | Database Persistence | ⬜ |
+
+Fill in: ✅ PASS / ❌ FAIL / ⚠️ PARTIAL
+
+---
+
+## 🎯 Demo Checklist for Teacher
+
+Before presenting, make sure:
+
+- [ ] Server is running (`python main.py`)
+- [ ] You can access Swagger UI (http://localhost:8000/docs)
+- [ ] You have a test account ready
+- [ ] `sample_comments.csv` is available
+- [ ] You understand the architecture (routers, services, models)
+- [ ] You can explain how to replace dummy ML model
+
+### Demo Flow:
+1. **Show Swagger UI** - explain automatic generation (bonus!)
+2. **Register → Login** - show JWT authentication
+3. **Single prediction** - demonstrate UI
+4. **Batch CSV** - show visualizations (chart + word cloud)
+5. **Download CSV** - export results
+6. **Explain architecture** - separation of concerns
+
+Good luck! 🎓

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,252 @@
+"""
+Prediction Router
+Handles single and batch predictions
+"""
+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
+)
+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()
+
+
+@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
+    
+    - **product_name**: Name of the product
+    - **comment**: Vietnamese product review text
+    
+    Returns predicted rating (1-5 stars) with confidence score
+    """
+    # Make prediction
+    prediction = ml_service.predict_single(request.comment)
+    
+    # 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
+    }
+
+
+@router.post("/batch", response_model=BatchPredictionResponse)
+async def predict_batch(
+    product_name: str = Form(...),
+    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
+    
+    - **product_name**: Name of the product
+    - **file**: CSV file with 'Comment' column
+    
+    Returns predictions with visualization data (wordcloud, distribution chart)
+    """
+    # 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
+        predictions = ml_service.predict_batch(comments)
+        
+        # Save to history
+        for pred in predictions:
+            history = PredictionHistory(
+                user_id=current_user.id,
+                product_name=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()}"
+        }
+    
+    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)}"
+        )

app/schemas.py

@@ -0,0 +1,70 @@
+"""
+Pydantic Schemas for Request/Response Validation
+"""
+from pydantic import BaseModel, EmailStr, Field
+from typing import Optional, List
+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
+
+class SinglePredictionResponse(BaseModel):
+    predicted_rating: int
+    confidence_score: float
+    comment: str
+
+class BatchPredictionResponse(BaseModel):
+    total_predictions: int
+    rating_distribution: dict
+    wordcloud_url: str
+    results: List[dict]
+    csv_download_url: str
+    pdf_download_url: str
+
+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

app/services/Model/phoBERT_multi_class_tokenizer/added_tokens.json

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

app/services/Model/phoBERT_multi_class_tokenizer/special_tokens_map.json

@@ -0,0 +1,9 @@
+{
+  "bos_token": "<s>",
+  "cls_token": "<s>",
+  "eos_token": "</s>",
+  "mask_token": "<mask>",
+  "pad_token": "<pad>",
+  "sep_token": "</s>",
+  "unk_token": "<unk>"
+}

app/services/Model/phoBERT_multi_class_tokenizer/tokenizer_config.json

@@ -0,0 +1,55 @@
+{
+  "added_tokens_decoder": {
+    "0": {
+      "content": "<s>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "1": {
+      "content": "<pad>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "2": {
+      "content": "</s>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "3": {
+      "content": "<unk>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "64000": {
+      "content": "<mask>",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    }
+  },
+  "bos_token": "<s>",
+  "clean_up_tokenization_spaces": false,
+  "cls_token": "<s>",
+  "eos_token": "</s>",
+  "extra_special_tokens": {},
+  "mask_token": "<mask>",
+  "model_max_length": 1000000000000000019884624838656,
+  "pad_token": "<pad>",
+  "sep_token": "</s>",
+  "tokenizer_class": "PhobertTokenizer",
+  "unk_token": "<unk>"
+}

app/services/__init__.py

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

app/services/auth_service.py

@@ -0,0 +1,85 @@
+"""
+Authentication Service
+Password hashing and JWT token generation
+"""
+from datetime import datetime, timedelta
+from typing import Optional
+from passlib.context import CryptContext
+from jose import JWTError, jwt
+from fastapi import Depends, HTTPException, status
+from fastapi.security import OAuth2PasswordBearer
+from sqlalchemy.orm import Session
+
+from app.config import SECRET_KEY, ALGORITHM, ACCESS_TOKEN_EXPIRE_MINUTES
+from app.database import get_db
+from app.models import User
+from app.schemas import TokenData
+
+# Password hashing (using argon2 instead of bcrypt for Python 3.13 compatibility)
+pwd_context = CryptContext(schemes=["argon2"], deprecated="auto")
+
+# OAuth2 scheme
+oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/api/auth/login")
+
+
+def verify_password(plain_password: str, hashed_password: str) -> bool:
+    """Verify a password against a hash"""
+    return pwd_context.verify(plain_password, hashed_password)
+
+
+def get_password_hash(password: str) -> str:
+    """Hash a password"""
+    # Bcrypt has a 72 byte limit, truncate if necessary
+    if len(password.encode('utf-8')) > 72:
+        password = password[:72]
+    return pwd_context.hash(password)
+
+
+def create_access_token(data: dict, expires_delta: Optional[timedelta] = None):
+    """Create JWT access token"""
+    to_encode = data.copy()
+    if expires_delta:
+        expire = datetime.utcnow() + expires_delta
+    else:
+        expire = datetime.utcnow() + timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES)
+    
+    to_encode.update({"exp": expire})
+    encoded_jwt = jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)
+    return encoded_jwt
+
+
+def authenticate_user(db: Session, username: str, password: str):
+    """Authenticate user with username and password"""
+    user = db.query(User).filter(User.username == username).first()
+    if not user:
+        return False
+    if not verify_password(password, user.hashed_password):
+        return False
+    return user
+
+
+async def get_current_user(
+    token: str = Depends(oauth2_scheme),
+    db: Session = Depends(get_db)
+) -> User:
+    """Get current authenticated user from JWT token"""
+    credentials_exception = HTTPException(
+        status_code=status.HTTP_401_UNAUTHORIZED,
+        detail="Could not validate credentials",
+        headers={"WWW-Authenticate": "Bearer"},
+    )
+    
+    try:
+        payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
+        username: str = payload.get("sub")
+        if username is None:
+            raise credentials_exception
+        token_data = TokenData(username=username)
+    except JWTError:
+        raise credentials_exception
+    
+    user = db.query(User).filter(User.username == token_data.username).first()
+    if user is None:
+        raise credentials_exception
+    
+    return user

app/services/ml_service.py

@@ -0,0 +1,153 @@
+"""
+ML Prediction Service with LAZY LOADING & REMOTE MODEL FETCHING
+"""
+import os
+from typing import List, Dict, Any, Optional
+# [QUAN TRỌNG] Import thư viện để tải model từ kho riêng
+from huggingface_hub import hf_hub_download
+
+# Only set HF cache for local development
+if not os.getenv("RENDER") and not os.getenv("SPACE_ID"):
+    os.environ['HF_HOME'] = 'G:/huggingface_cache'
+
+class MLPredictionService:
+    """
+    ML Service with lazy loading.
+    Fetches heavy model weights from external Hugging Face Model Repo
+    to bypass the 1GB limit of Space Git Repo.
+    """
+
+    def __init__(self):
+        """Initialize service without loading model (lazy loading)"""
+        # Model components
+        self.model: Optional[Any] = None
+        self.tokenizer: Optional[Any] = None
+        self.device: Optional[str] = None
+        self.model_loaded = False
+        
+        # [SỬA ĐỔI] Không set đường dẫn cứng ở đây nữa vì file không còn ở máy
+        # Chúng ta sẽ định nghĩa Repo ID chứa model ở đây
+        self.MODEL_REPO_ID = "vtdung23/my-phobert-models"
+        self.MODEL_FILENAME = "best_phoBER.pth"
+        
+        print("✅ ML Service initialized (Model will download & load on first request)")
+    
+    def _load_model(self):
+        """Load model and tokenizer (called on first request)"""
+        if self.model_loaded:
+            return
+        
+        print("🔄 Loading ML model (first request)...")
+        
+        # Import heavy dependencies only when needed
+        import torch
+        from transformers import AutoTokenizer, RobertaForSequenceClassification
+        
+        # Determine device
+        self.device = "cuda" if torch.cuda.is_available() else "cpu"
+        print(f"📍 Using device: {self.device}")
+        
+        # [SỬA ĐỔI 1] Load Tokenizer từ gốc vinai/phobert-base
+        # Vì folder tokenizer local đã bị xóa, ta load thẳng từ thư viện gốc cho an toàn
+        print("📦 Loading tokenizer from vinai/phobert-base...")
+        self.tokenizer = AutoTokenizer.from_pretrained("vinai/phobert-base", use_fast=False)
+        
+        # [SỬA ĐỔI 2] Tải file weights từ Kho Model riêng về
+        print(f"⬇️ Downloading weights from repo: {self.MODEL_REPO_ID}...")
+        try:
+            model_path = hf_hub_download(
+                repo_id=self.MODEL_REPO_ID,
+                filename=self.MODEL_FILENAME,
+                repo_type="model" # Quan trọng: báo đây là kho Model
+            )
+            print(f"✅ Downloaded weights to: {model_path}")
+        except Exception as e:
+            print(f"❌ Error downloading model: {e}")
+            raise e
+
+        # Load model architecture
+        print("🧠 Loading PhoBERT architecture...")
+        self.model = RobertaForSequenceClassification.from_pretrained(
+            "vinai/phobert-base",
+            num_labels=5, # Đảm bảo số này khớp với lúc bạn train (0,1,2,3,4 hay 1-5?)
+            problem_type="single_label_classification"
+        )
+        
+        # Load fine-tuned weights
+        print("⚙️ Loading trained weights into architecture...")
+        state_dict = torch.load(model_path, map_location=self.device, weights_only=False)
+        self.model.load_state_dict(state_dict)
+        
+        # Set to evaluation mode and move to device
+        self.model.eval()
+        self.model.to(self.device)
+        
+        self.model_loaded = True
+        print("✅ Model loaded successfully and ready to serve!")
+            
+    def predict_single(self, text: str) -> Dict[str, Any]:
+        """Predict rating for a single comment"""
+        # Lazy load model on first request
+        self._load_model()
+        
+        import torch
+        import torch.nn.functional as F
+
+        # 1. Vietnamese preprocessing
+        processed_text = self.preprocess(text)
+
+        # 2. Tokenize
+        encoded = self.tokenizer(
+            processed_text,
+            padding=True,
+            truncation=True,
+            max_length=256,
+            return_tensors="pt"
+        )
+        
+        # Move tensors to device
+        encoded = {k: v.to(self.device) for k, v in encoded.items()}
+
+        # 3. Inference
+        with torch.no_grad():
+            outputs = self.model(**encoded)
+            logits = outputs.logits
+            probs = F.softmax(logits, dim=1)
+
+        # 4. Get prediction + confidence
+        predicted_class = torch.argmax(probs, dim=1).item()
+        confidence = probs[0][predicted_class].item()
+
+        # 5. Convert 0-based label -> rating 1-5
+        # (Giả sử model train label 0 tương ứng 1 sao)
+        rating = predicted_class + 1
+
+        return {
+            'rating': rating,
+            'confidence': confidence
+        }
+    
+    def predict_batch(self, texts: List[str]) -> List[Dict[str, any]]:
+        """Predict ratings for multiple comments"""
+        results = []
+        for text in texts:
+            # Có thể tối ưu bằng cách batch tokenize, nhưng loop đơn giản cho an toàn
+            prediction = self.predict_single(text)
+            results.append({
+                'text': text,
+                'rating': prediction['rating'],
+                'confidence': prediction['confidence']
+            })
+        return results
+    
+    def preprocess(self, text: str) -> str:
+        """Preprocess Vietnamese text"""
+        from underthesea import word_tokenize
+        text = word_tokenize(text, format="text")
+        return text
+
+# Singleton instance
+ml_service = MLPredictionService()
+
+def get_ml_service() -> MLPredictionService:
+    return ml_service

app/services/report_service.py

@@ -0,0 +1,301 @@
+"""
+Report Service
+Generate PDF reports for batch predictions
+"""
+import io
+from typing import List, Dict
+from datetime import datetime
+from pathlib import Path
+from reportlab.lib.pagesizes import letter, A4
+from reportlab.lib.styles import getSampleStyleSheet, ParagraphStyle
+from reportlab.lib.units import inch
+from reportlab.platypus import (
+    SimpleDocTemplate, Paragraph, Spacer, Table, TableStyle, 
+    PageBreak, Image, Preformatted
+)
+from reportlab.lib import colors
+from reportlab.lib.enums import TA_CENTER, TA_LEFT, TA_RIGHT
+from reportlab.pdfbase import pdfmetrics
+from reportlab.pdfbase.ttfonts import TTFont
+import matplotlib
+matplotlib.use('Agg')
+import matplotlib.pyplot as plt
+from io import BytesIO
+from PIL import Image as PILImage
+
+from app.config import WORDCLOUD_DIR
+
+
+class ReportService:
+    """Service for generating PDF reports"""
+    
+    def __init__(self):
+        self.styles = getSampleStyleSheet()
+        self._setup_custom_styles()
+        self._setup_fonts()
+    
+    def _setup_fonts(self):
+        """Setup fonts for Vietnamese character support"""
+        try:
+            # Try to use DejaVu font which supports Vietnamese characters
+            pdfmetrics.registerFont(TTFont('DejaVu', '/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf'))
+            # Register bold variant
+            pdfmetrics.registerFont(TTFont('DejaVuBold', '/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf'))
+        except Exception as e:
+            # If fonts not found, continue with default fonts
+            print(f"Warning: Could not load Vietnamese fonts: {e}")
+    
+    def _setup_custom_styles(self):
+        """Setup custom paragraph styles"""
+        # Use DejaVu font for Vietnamese support, fallback to Helvetica
+        font_name = 'DejaVu'
+        font_name_bold = 'DejaVuBold'
+        
+        self.styles.add(ParagraphStyle(
+            name='CustomTitle',
+            parent=self.styles['Heading1'],
+            fontSize=24,
+            textColor=colors.HexColor('#4F46E5'),
+            spaceAfter=30,
+            alignment=TA_CENTER,
+            fontName=font_name_bold
+        ))
+        
+        self.styles.add(ParagraphStyle(
+            name='CustomHeading',
+            parent=self.styles['Heading2'],
+            fontSize=14,
+            textColor=colors.HexColor('#4F46E5'),
+            spaceAfter=12,
+            fontName=font_name_bold
+        ))
+        
+        self.styles.add(ParagraphStyle(
+            name='CustomNormal',
+            parent=self.styles['Normal'],
+            fontSize=10,
+            spaceAfter=6,
+            fontName=font_name
+        ))
+    
+    def generate_rating_distribution_chart(self) -> tuple:
+        """
+        Generate a matplotlib chart for rating distribution
+        
+        Returns:
+            tuple: (buffer, filename)
+        """
+        pass
+    
+    def generate_pdf_report(
+        self,
+        predictions: List[Dict],
+        distribution: Dict[int, int],
+        wordcloud_path: str,
+        username: str,
+        filename: str = None
+    ) -> bytes:
+        """
+        Generate comprehensive PDF report for batch predictions
+        
+        Args:
+            predictions: List of prediction results with 'text', 'rating', 'confidence'
+            distribution: Rating distribution dict {rating: count}
+            wordcloud_path: Path to generated wordcloud image (URL or file path)
+            username: Username for the report
+            filename: Optional custom filename
+            
+        Returns:
+            bytes: PDF file content
+        """
+        # Create PDF in memory
+        pdf_buffer = io.BytesIO()
+        
+        # Create document
+        doc = SimpleDocTemplate(
+            pdf_buffer,
+            pagesize=A4,
+            rightMargin=0.75*inch,
+            leftMargin=0.75*inch,
+            topMargin=0.75*inch,
+            bottomMargin=0.75*inch
+        )
+        
+        # Build document content
+        story = []
+        
+        # Title
+        title = Paragraph(
+            "Prediction Report",
+            self.styles['CustomTitle']
+        )
+        story.append(title)
+        story.append(Spacer(1, 0.3*inch))
+        
+        # Report info
+        timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+        info_text = f"<b>Generated by:</b> {username}<br/><b>Date:</b> {timestamp}"
+        story.append(Paragraph(info_text, self.styles['CustomNormal']))
+        story.append(Spacer(1, 0.3*inch))
+        
+        # Summary section
+        total_predictions = len(predictions)
+        avg_confidence = sum(p.get('confidence', 0) for p in predictions) / total_predictions if predictions else 0
+        
+        summary_heading = Paragraph("Summary", self.styles['CustomHeading'])
+        story.append(summary_heading)
+        
+        summary_data = [
+            ['Metric', 'Value'],
+            ['Total Predictions', str(total_predictions)],
+            ['Average Confidence', f'{avg_confidence:.2%}'],
+        ]
+        
+        summary_table = Table(summary_data, colWidths=[3*inch, 2*inch])
+        summary_table.setStyle(TableStyle([
+            ('BACKGROUND', (0, 0), (-1, 0), colors.HexColor('#4F46E5')),
+            ('TEXTCOLOR', (0, 0), (-1, 0), colors.whitesmoke),
+            ('ALIGN', (0, 0), (-1, -1), 'CENTER'),
+            ('FONTNAME', (0, 0), (-1, 0), 'DejaVuBold'),
+            ('FONTSIZE', (0, 0), (-1, 0), 12),
+            ('BOTTOMPADDING', (0, 0), (-1, 0), 12),
+            ('BACKGROUND', (0, 1), (-1, -1), colors.beige),
+            ('GRID', (0, 0), (-1, -1), 1, colors.black),
+            ('FONTNAME', (0, 1), (-1, -1), 'DejaVu'),
+            ('FONTSIZE', (0, 1), (-1, -1), 10)
+        ]))
+        story.append(summary_table)
+        story.append(Spacer(1, 0.3*inch))
+        
+        # Rating Distribution section
+        dist_heading = Paragraph("Rating Distribution", self.styles['CustomHeading'])
+        story.append(dist_heading)
+        
+        dist_data = [['Rating', 'Count', 'Percentage']]
+        
+        # Normalize distribution keys to integers (they might come as strings from JSON)
+        normalized_dist = {}
+        for key, value in distribution.items():
+            try:
+                int_key = int(key)
+                normalized_dist[int_key] = int(value)
+            except (ValueError, TypeError):
+                pass
+        
+        total = sum(normalized_dist.values())
+        
+        for rating in range(1, 6):
+            count = normalized_dist.get(rating, 0)
+            percentage = (count / total * 100) if total > 0 else 0
+            # Use star character ★ instead of emoji
+            stars = "★" * rating
+            dist_data.append([
+                f"{stars}",
+                str(count),
+                f"{percentage:.1f}%"
+            ])
+        
+        dist_table = Table(dist_data, colWidths=[1.5*inch, 1.5*inch, 1.5*inch])
+        dist_table.setStyle(TableStyle([
+            ('BACKGROUND', (0, 0), (-1, 0), colors.HexColor('#4F46E5')),
+            ('TEXTCOLOR', (0, 0), (-1, 0), colors.whitesmoke),
+            ('ALIGN', (0, 0), (-1, -1), 'CENTER'),
+            ('FONTNAME', (0, 0), (-1, 0), 'DejaVuBold'),
+            ('FONTSIZE', (0, 0), (-1, 0), 11),
+            ('BOTTOMPADDING', (0, 0), (-1, 0), 12),
+            ('BACKGROUND', (0, 1), (-1, -1), colors.lightgrey),
+            ('GRID', (0, 0), (-1, -1), 1, colors.black),
+            ('FONTNAME', (0, 1), (-1, -1), 'DejaVu'),
+            ('FONTSIZE', (0, 1), (-1, -1), 10)
+        ]))
+        story.append(dist_table)
+        story.append(Spacer(1, 0.3*inch))
+        
+        # Word Cloud section
+        if wordcloud_path:
+            wc_heading = Paragraph("Word Cloud Analysis", self.styles['CustomHeading'])
+            story.append(wc_heading)
+            
+            try:
+                # Convert URL to file path if needed
+                file_path = wordcloud_path
+                if wordcloud_path.startswith('/'):
+                    # It's a URL path, convert to file path
+                    file_path = str(WORDCLOUD_DIR / wordcloud_path.split('/')[-1])
+                
+                if Path(file_path).exists():
+                    img = Image(file_path, width=5*inch, height=2.5*inch)
+                    story.append(img)
+                    story.append(Spacer(1, 0.2*inch))
+                    wc_text = Paragraph(
+                        "<i>Larger words indicate higher frequency in the comments</i>",
+                        self.styles['CustomNormal']
+                    )
+                    story.append(wc_text)
+            except Exception as e:
+                print(f"Warning: Could not include word cloud: {e}")
+            
+            story.append(Spacer(1, 0.3*inch))
+        
+        # Page break before detailed results
+        story.append(PageBreak())
+        
+        # Detailed Results section
+        results_heading = Paragraph("Detailed Results", self.styles['CustomHeading'])
+        story.append(results_heading)
+        story.append(Spacer(1, 0.2*inch))
+        
+        # Results table
+        results_data = [['Comment', 'Rating', 'Confidence']]
+        
+        for pred in predictions:
+            comment = pred.get('text', '')
+            rating = pred.get('rating', 0)
+            confidence = pred.get('confidence', 0)
+            
+            # Create wrapped comment - let ReportLab handle wrapping
+            comment_paragraph = Paragraph(comment, self.styles['CustomNormal'])
+            
+            # Use star character ★ instead of emoji
+            stars = "★" * rating
+            
+            results_data.append([
+                comment_paragraph,
+                f"{stars}",
+                f"{confidence:.2%}"
+            ])
+        
+        # Create table with adjusted column widths - wider comment column for wrapping
+        results_table = Table(results_data, colWidths=[3.5*inch, 0.8*inch, 1.2*inch])
+        results_table.setStyle(TableStyle([
+            ('BACKGROUND', (0, 0), (-1, 0), colors.HexColor('#4F46E5')),
+            ('TEXTCOLOR', (0, 0), (-1, 0), colors.whitesmoke),
+            ('ALIGN', (0, 0), (0, -1), 'LEFT'),
+            ('ALIGN', (1, 0), (-1, -1), 'CENTER'),
+            ('FONTNAME', (0, 0), (-1, 0), 'DejaVuBold'),
+            ('FONTSIZE', (0, 0), (-1, 0), 10),
+            ('BOTTOMPADDING', (0, 0), (-1, 0), 12),
+            ('BACKGROUND', (0, 1), (-1, -1), colors.lightgrey),
+            ('GRID', (0, 0), (-1, -1), 1, colors.grey),
+            ('ROWBACKGROUNDS', (0, 1), (-1, -1), [colors.white, colors.lightgrey]),
+            ('FONTNAME', (0, 1), (-1, -1), 'DejaVu'),
+            ('FONTSIZE', (0, 1), (-1, -1), 9),
+            ('VALIGN', (0, 0), (-1, -1), 'TOP'),  # Top alignment for wrapped text
+            ('LEFTPADDING', (0, 0), (-1, -1), 8),
+            ('RIGHTPADDING', (0, 0), (-1, -1), 8),
+            ('TOPPADDING', (0, 0), (-1, -1), 6),
+            ('BOTTOMPADDING', (0, 0), (-1, -1), 6),
+        ]))
+        story.append(results_table)
+        
+        # Build PDF
+        doc.build(story)
+        
+        # Get PDF bytes
+        pdf_buffer.seek(0)
+        return pdf_buffer.getvalue()
+
+
+def get_report_service() -> ReportService:
+    """Dependency injection for report service"""
+    return ReportService()

app/services/visualization_service.py

@@ -0,0 +1,125 @@
+"""
+Visualization Service
+WordCloud generation and data visualization utilities
+"""
+import os
+from typing import List, Dict
+from collections import Counter
+from wordcloud import WordCloud
+import matplotlib
+matplotlib.use('Agg')  # Use non-GUI backend
+import matplotlib.pyplot as plt
+from datetime import datetime
+from pathlib import Path
+
+from app.config import WORDCLOUD_DIR
+
+
+class VisualizationService:
+    """Service for generating visualizations"""
+    
+    def __init__(self):
+        # Vietnamese stopwords (common words to exclude)
+        self.stopwords = set([
+            'và', 'của', 'có', 'cho', 'với', 'từ', 'này', 'được',
+            'là', 'để', 'một', 'các', 'trong', 'không', 'đã', 'rất',
+            'cũng', 'nhưng', 'thì', 'bị', 'khi', 'nếu', 'như', 'về',
+            'tôi', 'bạn', 'mình', 'nó', 'họ', 'em', 'anh', 'chị',
+            'vì', 'nên', 'đến', 'lại', 'ra', 'đang', 'sẽ', 'đều',
+            'hay', 'thế', 'làm', 'được', 'rồi', 'đó', 'này', 'ở'
+        ])
+    
+    def generate_wordcloud(self, texts: List[str], filename: str = None) -> str:
+        """
+        Generate word cloud from list of texts
+        
+        Args:
+            texts: List of Vietnamese comments
+            filename: Optional custom filename
+            
+        Returns:
+            str: Path to generated word cloud image
+        """
+        # Combine all texts
+        combined_text = ' '.join(texts)
+        
+        # Generate filename if not provided
+        if filename is None:
+            timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+            filename = f"wordcloud_{timestamp}.png"
+        
+        filepath = WORDCLOUD_DIR / filename
+        
+        # Create word cloud
+        wordcloud = WordCloud(
+            width=800,
+            height=400,
+            background_color='white',
+            stopwords=self.stopwords,
+            colormap='viridis',
+            max_words=100,
+            relative_scaling=0.5,
+            min_font_size=10
+        ).generate(combined_text)
+        
+        # Save to file
+        plt.figure(figsize=(10, 5))
+        plt.imshow(wordcloud, interpolation='bilinear')
+        plt.axis('off')
+        plt.tight_layout(pad=0)
+        plt.savefig(filepath, dpi=150, bbox_inches='tight')
+        plt.close()
+        
+        # Return relative URL path
+        return f"/static/uploads/wordclouds/{filename}"
+    
+    def calculate_rating_distribution(self, ratings: List[int]) -> Dict[int, int]:
+        """
+        Calculate distribution of ratings
+        
+        Args:
+            ratings: List of ratings (1-5)
+            
+        Returns:
+            dict: {rating: count}
+        """
+        distribution = Counter(ratings)
+        
+        # Ensure all ratings 1-5 are present
+        for rating in range(1, 6):
+            if rating not in distribution:
+                distribution[rating] = 0
+        
+        return dict(sorted(distribution.items()))
+    
+    def get_top_words(self, texts: List[str], top_n: int = 20) -> List[tuple]:
+        """
+        Get most frequent words from texts
+        
+        Args:
+            texts: List of comments
+            top_n: Number of top words to return
+            
+        Returns:
+            list: [(word, count), ...]
+        """
+        # Combine and split texts
+        words = []
+        for text in texts:
+            words.extend(text.lower().split())
+        
+        # Filter stopwords
+        filtered_words = [w for w in words if w not in self.stopwords and len(w) > 2]
+        
+        # Count and return top words
+        word_counts = Counter(filtered_words)
+        return word_counts.most_common(top_n)
+
+
+# Singleton instance
+viz_service = VisualizationService()
+
+
+def get_viz_service() -> VisualizationService:
+    """Dependency to get visualization service"""
+    return viz_service

app/static/css/style.css

@@ -0,0 +1 @@
+/* Placeholder for custom CSS if needed */

app/static/js/main.js

@@ -0,0 +1 @@
+// Placeholder for custom JavaScript if needed

app/static/uploads/.gitkeep

@@ -0,0 +1,3 @@
+# Keep this directory in git but ignore its contents
+*
+!.gitkeep

app/templates/base.html

@@ -0,0 +1,59 @@
+<!DOCTYPE html>
+<html lang="vi">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{% block title %}Vietnamese Product Rating Prediction{% endblock %}</title>
+    
+    <!-- TailwindCSS CDN -->
+    <script src="https://cdn.tailwindcss.com"></script>
+    
+    <!-- Chart.js CDN -->
+    <script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
+    
+    <!-- Font Awesome for icons -->
+    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.0/css/all.min.css">
+    
+    <style>
+        @keyframes fadeIn {
+            from { opacity: 0; transform: translateY(10px); }
+            to { opacity: 1; transform: translateY(0); }
+        }
+        .fade-in {
+            animation: fadeIn 0.3s ease-out;
+        }
+    </style>
+    
+    {% block extra_head %}{% endblock %}
+</head>
+<body class="bg-gradient-to-br from-blue-50 to-indigo-100 min-h-screen">
+    <!-- Header -->
+    <header class="bg-white shadow-md">
+        <nav class="container mx-auto px-6 py-4">
+            <div class="flex items-center justify-between">
+                <div class="flex items-center space-x-2">
+                    <i class="fas fa-star text-yellow-500 text-2xl"></i>
+                    <h1 class="text-2xl font-bold text-gray-800">Rating Predictor</h1>
+                </div>
+                
+                {% block nav_items %}{% endblock %}
+            </div>
+        </nav>
+    </header>
+    
+    <!-- Main Content -->
+    <main class="container mx-auto px-6 py-8">
+        {% block content %}{% endblock %}
+    </main>
+    
+    <!-- Footer -->
+    <footer class="bg-white mt-12 py-6">
+        <div class="container mx-auto px-6 text-center text-gray-600">
+            <p>&copy; 2024 Vietnamese Product Rating Prediction System</p>
+            <p class="text-sm mt-2">Built with FastAPI + Jinja2 + TailwindCSS</p>
+        </div>
+    </footer>
+    
+    {% block scripts %}{% endblock %}
+</body>
+</html>

app/templates/dashboard.html

@@ -0,0 +1,618 @@
+{% extends "base.html" %}
+
+{% block title %}Dashboard - Rating Predictor{% endblock %}
+
+{% block nav_items %}
+<div class="flex items-center space-x-4">
+    <span class="text-gray-700" id="username-display">
+        <i class="fas fa-user mr-2"></i><span id="current-username"></span>
+    </span>
+    <button 
+        onclick="logout()"
+        class="bg-red-500 text-white px-4 py-2 rounded-lg hover:bg-red-600 transition"
+    >
+        <i class="fas fa-sign-out-alt mr-2"></i>Logout
+    </button>
+</div>
+{% endblock %}
+
+{% block content %}
+<div class="max-w-7xl mx-auto">
+    <!-- Welcome Section -->
+    <div class="bg-white rounded-2xl shadow-lg p-6 mb-8 fade-in">
+        <h2 class="text-3xl font-bold text-gray-800 mb-2">
+            <i class="fas fa-chart-line text-indigo-600 mr-3"></i>
+            Prediction Dashboard
+        </h2>
+        <p class="text-gray-600">Dự đoán đánh giá sản phẩm từ bình luận tiếng Việt</p>
+    </div>
+    
+
+    
+    <!-- Input Mode Tabs -->
+    <div class="bg-white rounded-2xl shadow-lg p-6 mb-8">
+        <div class="flex space-x-4 mb-6 border-b">
+            <button 
+                onclick="switchTab('single')"
+                id="tab-single"
+                class="tab-button px-6 py-3 font-medium border-b-2 border-indigo-600 text-indigo-600"
+            >
+                <i class="fas fa-comment mr-2"></i>Single Comment
+            </button>
+            <button 
+                onclick="switchTab('batch')"
+                id="tab-batch"
+                class="tab-button px-6 py-3 font-medium text-gray-500 hover:text-gray-700"
+            >
+                <i class="fas fa-file-csv mr-2"></i>Upload CSV
+            </button>
+        </div>
+        
+        <!-- Single Prediction Form -->
+        <div id="single-form" class="tab-content">
+            <form id="singlePredictionForm">
+                <label class="block text-sm font-medium text-gray-700 mb-2">
+                    Enter your comment (Vietnamese):
+                </label>
+                <textarea 
+                    id="single-comment"
+                    rows="4"
+                    class="w-full px-4 py-3 border border-gray-300 rounded-lg focus:ring-2 focus:ring-indigo-500 focus:border-transparent transition"
+                    placeholder="Sản phẩm rất tốt, chất lượng cao..."
+                ></textarea>
+                
+                <button 
+                    type="submit"
+                    class="mt-4 bg-indigo-600 text-white px-6 py-3 rounded-lg hover:bg-indigo-700 transition font-medium shadow-lg"
+                >
+                    <i class="fas fa-magic mr-2"></i>Predict Rating
+                </button>
+            </form>
+            
+            <!-- Single Result -->
+            <div id="single-result" class="hidden mt-6 p-6 bg-gradient-to-r from-green-50 to-blue-50 rounded-xl border-2 border-green-200">
+                <h3 class="text-xl font-bold text-gray-800 mb-4">
+                    <i class="fas fa-star text-yellow-500 mr-2"></i>Prediction Result
+                </h3>
+                <div class="flex items-center space-x-6">
+                    <div class="text-center">
+                        <div class="text-5xl font-bold text-indigo-600" id="predicted-rating"></div>
+                        <div class="text-sm text-gray-600 mt-2">Rating</div>
+                    </div>
+                    <div class="text-center">
+                        <div class="text-3xl font-bold text-green-600" id="confidence-score"></div>
+                        <div class="text-sm text-gray-600 mt-2">Confidence</div>
+                    </div>
+                    <div class="flex-1">
+                        <div id="rating-stars" class="text-4xl"></div>
+                    </div>
+                </div>
+            </div>
+        </div>
+        
+        <!-- Batch Prediction Form -->
+        <div id="batch-form" class="tab-content hidden">
+            <form id="batchPredictionForm">
+                <label class="block text-sm font-medium text-gray-700 mb-2">
+                    <i class="fas fa-tag mr-2"></i>Product/Item Name (optional):
+                </label>
+                <input 
+                    type="text"
+                    id="batch-product-name"
+                    class="w-full px-4 py-2 border border-gray-300 rounded-lg focus:ring-2 focus:ring-indigo-500 focus:border-transparent transition mb-4"
+                    placeholder="e.g., iPhone 15, Laptop, Shoes..."
+                >
+                
+                <div class="border-2 border-dashed border-gray-300 rounded-lg p-8 text-center hover:border-indigo-500 transition">
+                    <i class="fas fa-cloud-upload-alt text-5xl text-gray-400 mb-4"></i>
+                    <label for="csv-file" class="block text-lg font-medium text-gray-700 mb-2 cursor-pointer">
+                        Upload CSV File
+                    </label>
+                    <input 
+                        type="file"
+                        id="csv-file"
+                        accept=".csv"
+                        class="hidden"
+                        onchange="displayFileName(this)"
+                    >
+                    <p class="text-sm text-gray-500 mb-2">CSV must contain a "Comment" column</p>
+                    <p id="file-name" class="text-sm font-medium text-indigo-600"></p>
+                    <label for="csv-file" class="inline-block mt-4 bg-indigo-600 text-white px-6 py-2 rounded-lg hover:bg-indigo-700 cursor-pointer transition">
+                        Choose File
+                    </label>
+                </div>
+                
+                <button 
+                    type="submit"
+                    class="mt-6 bg-indigo-600 text-white px-6 py-3 rounded-lg hover:bg-indigo-700 transition font-medium shadow-lg"
+                >
+                    <i class="fas fa-magic mr-2"></i>Predict Batch
+                </button>
+            </form>
+            
+            <!-- Batch Results -->
+            <div id="batch-results" class="hidden mt-8">
+                <div class="grid grid-cols-1 lg:grid-cols-2 gap-6 mb-6">
+                    <!-- Rating Distribution Chart -->
+                    <div class="bg-white p-6 rounded-xl shadow">
+                        <h3 class="text-lg font-bold text-gray-800 mb-4">
+                            <i class="fas fa-chart-pie text-indigo-600 mr-2"></i>Rating Distribution
+                        </h3>
+                        <canvas id="ratingChart"></canvas>
+                    </div>
+                    
+                    <!-- Word Cloud -->
+                    <div class="bg-white p-6 rounded-xl shadow">
+                        <h3 class="text-lg font-bold text-gray-800 mb-4">
+                            <i class="fas fa-cloud text-indigo-600 mr-2"></i>Word Cloud
+                        </h3>
+                        <img id="wordcloud-image" src="" alt="Word Cloud" class="w-full rounded-lg">
+                    </div>
+                </div>
+                
+                <!-- Results Table -->
+                <div class="bg-white p-6 rounded-xl shadow">
+                    <div class="flex justify-between items-center mb-4">
+                        <h3 class="text-lg font-bold text-gray-800">
+                            <i class="fas fa-table text-indigo-600 mr-2"></i>Prediction Results
+                        </h3>
+                        <div class="space-x-3">
+                            <button 
+                                onclick="downloadPDF()"
+                                class="bg-red-600 text-white px-4 py-2 rounded-lg hover:bg-red-700 transition"
+                            >
+                                <i class="fas fa-file-pdf mr-2"></i>Download PDF
+                            </button>
+                            <button 
+                                onclick="downloadCSV()"
+                                class="bg-green-600 text-white px-4 py-2 rounded-lg hover:bg-green-700 transition"
+                            >
+                                <i class="fas fa-download mr-2"></i>Download CSV
+                            </button>
+                        </div>
+                    </div>
+                    <div class="overflow-x-auto">
+                        <table class="w-full" id="results-table">
+                            <thead class="bg-gray-100">
+                                <tr>
+                                    <th class="px-4 py-3 text-left text-sm font-semibold text-gray-700">Comment</th>
+                                    <th class="px-4 py-3 text-center text-sm font-semibold text-gray-700">Rating</th>
+                                    <th class="px-4 py-3 text-center text-sm font-semibold text-gray-700">Confidence</th>
+                                </tr>
+                            </thead>
+                            <tbody id="results-tbody" class="divide-y divide-gray-200">
+                            </tbody>
+                        </table>
+                    </div>
+                </div>
+            </div>
+        </div>
+    </div>
+    
+    <!-- History Section -->
+    <div class="bg-white rounded-2xl shadow-lg p-6 mb-8">
+        <div class="flex justify-between items-center mb-6">
+            <h2 class="text-2xl font-bold text-gray-800">
+                <i class="fas fa-history text-indigo-600 mr-2"></i>Prediction History
+            </h2>
+            <button 
+                onclick="refreshHistory()"
+                class="bg-indigo-600 text-white px-4 py-2 rounded-lg hover:bg-indigo-700 transition font-medium"
+            >
+                <i class="fas fa-sync-alt mr-2"></i>Refresh
+            </button>
+        </div>
+        
+        <div class="overflow-x-auto">
+            <table class="w-full" id="history-table">
+                <thead class="bg-gray-100">
+                    <tr>
+                        <th class="px-4 py-3 text-left text-sm font-semibold text-gray-700">Date/Time</th>
+                        <th class="px-4 py-3 text-left text-sm font-semibold text-gray-700">Comment</th>
+                        <th class="px-4 py-3 text-center text-sm font-semibold text-gray-700">Rating</th>
+                        <th class="px-4 py-3 text-center text-sm font-semibold text-gray-700">Confidence</th>
+                        <th class="px-4 py-3 text-center text-sm font-semibold text-gray-700">Type</th>
+                    </tr>
+                </thead>
+                <tbody id="history-tbody" class="divide-y divide-gray-200">
+                    <tr class="text-center text-gray-500 py-8">
+                        <td colspan="6" class="px-4 py-8">Loading history...</td>
+                    </tr>
+                </tbody>
+            </table>
+        </div>
+    </div>
+</div>
+{% endblock %}
+
+{% block scripts %}
+<script>
+    // Check authentication
+    const token = localStorage.getItem('access_token');
+    const username = localStorage.getItem('username');
+    
+    if (!token) {
+        window.location.href = '/login';
+    }
+    
+    document.getElementById('current-username').textContent = username || 'User';
+    
+    // Global variables
+    let currentResults = [];
+    let currentDistribution = {};
+    let currentWordcloudUrl = '';
+    let chartInstance = null;
+    
+    // Load history on page load
+    document.addEventListener('DOMContentLoaded', () => {
+        loadHistory();
+    });
+    
+    // Logout function
+    function logout() {
+        localStorage.removeItem('access_token');
+        localStorage.removeItem('username');
+        window.location.href = '/login';
+    }
+    
+    // Tab switching
+    function switchTab(tab) {
+        const tabs = ['single', 'batch'];
+        tabs.forEach(t => {
+            const button = document.getElementById(`tab-${t}`);
+            const content = document.getElementById(`${t}-form`);
+            
+            if (t === tab) {
+                button.classList.add('border-indigo-600', 'text-indigo-600');
+                button.classList.remove('text-gray-500');
+                content.classList.remove('hidden');
+            } else {
+                button.classList.remove('border-indigo-600', 'text-indigo-600');
+                button.classList.add('text-gray-500');
+                content.classList.add('hidden');
+            }
+        });
+        
+        // Hide results when switching
+        document.getElementById('single-result').classList.add('hidden');
+        document.getElementById('batch-results').classList.add('hidden');
+    }
+    
+    // Display selected file name
+    function displayFileName(input) {
+        const fileName = input.files[0]?.name || '';
+        document.getElementById('file-name').textContent = fileName ? `Selected: ${fileName}` : '';
+    }
+    
+    // Single Prediction
+    document.getElementById('singlePredictionForm').addEventListener('submit', async (e) => {
+        e.preventDefault();
+        
+        const comment = document.getElementById('single-comment').value;
+        
+        if (!comment.trim()) {
+            alert('Please enter a comment!');
+            return;
+        }
+        
+        try {
+            const response = await fetch('/api/predict/single', {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Authorization': `Bearer ${token}`
+                },
+                body: JSON.stringify({
+                    product_name: '',
+                    comment: comment
+                })
+            });
+            
+            if (response.ok) {
+                const data = await response.json();
+                displaySingleResult(data);
+                // Reload history
+                setTimeout(() => loadHistory(), 500);
+            } else {
+                const error = await response.json();
+                alert(error.detail || 'Prediction failed');
+            }
+        } catch (error) {
+            alert('An error occurred: ' + error.message);
+        }
+    });
+    
+    function displaySingleResult(data) {
+        document.getElementById('predicted-rating').textContent = data.predicted_rating;
+        document.getElementById('confidence-score').textContent = (data.confidence_score * 100).toFixed(1) + '%';
+        
+        // Display stars
+        const stars = '⭐'.repeat(data.predicted_rating);
+        document.getElementById('rating-stars').textContent = stars;
+        
+        document.getElementById('single-result').classList.remove('hidden');
+    }
+    
+    // Batch Prediction
+    document.getElementById('batchPredictionForm').addEventListener('submit', async (e) => {
+        e.preventDefault();
+        
+        const productName = document.getElementById('batch-product-name').value || '';
+        const fileInput = document.getElementById('csv-file');
+        const file = fileInput.files[0];
+        
+        if (!file) {
+            alert('Please select a CSV file!');
+            return;
+        }
+        
+        const formData = new FormData();
+        formData.append('product_name', productName);
+        formData.append('file', file);
+        
+        try {
+            const response = await fetch('/api/predict/batch', {
+                method: 'POST',
+                headers: {
+                    'Authorization': `Bearer ${token}`
+                },
+                body: formData
+            });
+            
+            if (response.ok) {
+                const data = await response.json();
+                displayBatchResults(data);
+                // Reload history
+                setTimeout(() => loadHistory(), 500);
+            } else {
+                const error = await response.json();
+                alert(error.detail || 'Prediction failed');
+            }
+        } catch (error) {
+            alert('An error occurred: ' + error.message);
+        }
+    });
+    
+    function displayBatchResults(data) {
+        currentResults = data.results;
+        currentDistribution = data.rating_distribution;
+        currentWordcloudUrl = data.wordcloud_url;
+        
+        // Display word cloud
+        document.getElementById('wordcloud-image').src = data.wordcloud_url;
+        
+        // Create chart
+        createRatingChart(data.rating_distribution);
+        
+        // Populate table
+        const tbody = document.getElementById('results-tbody');
+        tbody.innerHTML = '';
+        
+        data.results.forEach(result => {
+            const row = `
+                <tr class="hover:bg-gray-50">
+                    <td class="px-4 py-3 text-sm text-gray-700">${result.Comment}</td>
+                    <td class="px-4 py-3 text-center">
+                        <span class="inline-block bg-indigo-100 text-indigo-800 px-3 py-1 rounded-full font-semibold">
+                            ${result.Predicted_Rating}⭐
+                        </span>
+                    </td>
+                    <td class="px-4 py-3 text-center text-sm text-gray-600">
+                        ${(result.Confidence * 100).toFixed(1)}%
+                    </td>
+                </tr>
+            `;
+            tbody.innerHTML += row;
+        });
+        
+        document.getElementById('batch-results').classList.remove('hidden');
+    }
+    
+    function createRatingChart(distribution) {
+        const ctx = document.getElementById('ratingChart').getContext('2d');
+        
+        // Destroy existing chart
+        if (chartInstance) {
+            chartInstance.destroy();
+        }
+        
+        chartInstance = new Chart(ctx, {
+            type: 'bar',
+            data: {
+                labels: ['1⭐', '2⭐', '3⭐', '4⭐', '5⭐'],
+                datasets: [{
+                    label: 'Number of Reviews',
+                    data: [
+                        distribution[1] || 0,
+                        distribution[2] || 0,
+                        distribution[3] || 0,
+                        distribution[4] || 0,
+                        distribution[5] || 0
+                    ],
+                    backgroundColor: [
+                        'rgba(239, 68, 68, 0.8)',
+                        'rgba(251, 146, 60, 0.8)',
+                        'rgba(250, 204, 21, 0.8)',
+                        'rgba(132, 204, 22, 0.8)',
+                        'rgba(34, 197, 94, 0.8)'
+                    ],
+                    borderColor: [
+                        'rgba(239, 68, 68, 1)',
+                        'rgba(251, 146, 60, 1)',
+                        'rgba(250, 204, 21, 1)',
+                        'rgba(132, 204, 22, 1)',
+                        'rgba(34, 197, 94, 1)'
+                    ],
+                    borderWidth: 2
+                }]
+            },
+            options: {
+                responsive: true,
+                maintainAspectRatio: true,
+                plugins: {
+                    legend: {
+                        display: false
+                    }
+                },
+                scales: {
+                    y: {
+                        beginAtZero: true,
+                        ticks: {
+                            stepSize: 1
+                        }
+                    }
+                }
+            }
+        });
+    }
+    
+    function downloadCSV() {
+        if (currentResults.length === 0) {
+            alert('No results to download');
+            return;
+        }
+        
+        // Create CSV content
+        const headers = ['Comment', 'Predicted_Rating', 'Confidence'];
+        const csvContent = [
+            headers.join(','),
+            ...currentResults.map(r => 
+                `"${r.Comment.replace(/"/g, '""')}",${r.Predicted_Rating},${r.Confidence}`
+            )
+        ].join('\n');
+        
+        // Create download link
+        const blob = new Blob([csvContent], { type: 'text/csv;charset=utf-8;' });
+        const link = document.createElement('a');
+        const url = URL.createObjectURL(blob);
+        
+        link.setAttribute('href', url);
+        link.setAttribute('download', `predictions_${new Date().getTime()}.csv`);
+        link.style.visibility = 'hidden';
+        
+        document.body.appendChild(link);
+        link.click();
+        document.body.removeChild(link);
+    }
+    
+    function downloadPDF() {
+        if (currentResults.length === 0) {
+            alert('No results to download');
+            return;
+        }
+        
+        try {
+            // Prepare data
+            const predictions = currentResults.map(r => ({
+                text: r.Comment,
+                rating: r.Predicted_Rating,
+                confidence: r.Confidence
+            }));
+            
+            // Send request to generate PDF
+            fetch('/api/predict/download-pdf', {
+                method: 'POST',
+                headers: {
+                    'Authorization': `Bearer ${token}`,
+                    'Content-Type': 'application/json'
+                },
+                body: JSON.stringify({
+                    predictions: predictions,
+                    distribution: currentDistribution,
+                    wordcloud_path: currentWordcloudUrl
+                })
+            })
+            .then(response => {
+                if (response.ok) {
+                    return response.blob();
+                }
+                throw new Error('Failed to generate PDF');
+            })
+            .then(blob => {
+                const url = URL.createObjectURL(blob);
+                const link = document.createElement('a');
+                link.href = url;
+                link.download = `predictions_report_${new Date().getTime()}.pdf`;
+                document.body.appendChild(link);
+                link.click();
+                document.body.removeChild(link);
+                URL.revokeObjectURL(url);
+            })
+            .catch(error => {
+                console.error('Error downloading PDF:', error);
+                alert('Error generating PDF report. Please try again.');
+            });
+        } catch (error) {
+            console.error('Error preparing PDF download:', error);
+            alert('Error preparing PDF report');
+        }
+    }
+    
+    // Load and display prediction history
+    async function loadHistory() {
+        try {
+            const response = await fetch('/api/predict/history', {
+                headers: {
+                    'Authorization': `Bearer ${token}`
+                }
+            });
+            
+            if (response.ok) {
+                const history = await response.json();
+                displayHistory(history);
+            } else {
+                console.error('Failed to load history');
+            }
+        } catch (error) {
+            console.error('Error loading history:', error);
+        }
+    }
+    
+    function displayHistory(history) {
+        const tbody = document.getElementById('history-tbody');
+        
+        if (history.length === 0) {
+            tbody.innerHTML = `
+                <tr class="text-center text-gray-500">
+                    <td colspan="5" class="px-4 py-8">
+                        <i class="fas fa-inbox text-3xl text-gray-300 mb-2"></i>
+                        <p>No prediction history yet</p>
+                    </td>
+                </tr>
+            `;
+            return;
+        }
+        
+        tbody.innerHTML = '';
+        history.forEach(item => {
+            const date = new Date(item.created_at).toLocaleString();
+            const shortComment = item.comment.length > 50 
+                ? item.comment.substring(0, 50) + '...' 
+                : item.comment;
+            const row = `
+                <tr class="hover:bg-gray-50">
+                    <td class="px-4 py-3 text-sm text-gray-600">${date}</td>
+                    <td class="px-4 py-3 text-sm text-gray-700" title="${item.comment}">${shortComment}</td>
+                    <td class="px-4 py-3 text-center">
+                        <span class="inline-block bg-indigo-100 text-indigo-800 px-3 py-1 rounded-full font-semibold text-sm">
+                            ${item.predicted_rating}⭐
+                        </span>
+                    </td>
+                    <td class="px-4 py-3 text-center text-sm text-gray-600">
+                        ${(item.confidence_score * 100).toFixed(1)}%
+                    </td>
+                    <td class="px-4 py-3 text-center text-sm">
+                        <span class="inline-block ${item.prediction_type === 'single' ? 'bg-blue-100 text-blue-800' : 'bg-green-100 text-green-800'} px-2 py-1 rounded text-xs font-semibold">
+                            ${item.prediction_type}
+                        </span>
+                    </td>
+                </tr>
+            `;
+            tbody.innerHTML += row;
+        });
+    }
+    
+    function refreshHistory() {
+        loadHistory();
+    }</script>
+{% endblock %}

app/templates/login.html

@@ -0,0 +1,118 @@
+{% extends "base.html" %}
+
+{% block title %}Login - Rating Predictor{% endblock %}
+
+{% block content %}
+<div class="flex items-center justify-center min-h-[calc(100vh-200px)]">
+    <div class="bg-white rounded-2xl shadow-xl p-8 w-full max-w-md fade-in">
+        <div class="text-center mb-8">
+            <i class="fas fa-sign-in-alt text-5xl text-indigo-600 mb-4"></i>
+            <h2 class="text-3xl font-bold text-gray-800">Đăng Nhập</h2>
+            <p class="text-gray-600 mt-2">Welcome back to Rating Predictor</p>
+        </div>
+        
+        <!-- Alert Messages -->
+        <div id="alert" class="hidden mb-4 p-4 rounded-lg"></div>
+        
+        <form id="loginForm" class="space-y-6">
+            <div>
+                <label class="block text-sm font-medium text-gray-700 mb-2">
+                    <i class="fas fa-user mr-2"></i>Username
+                </label>
+                <input 
+                    type="text" 
+                    id="username" 
+                    name="username"
+                    required
+                    class="w-full px-4 py-3 border border-gray-300 rounded-lg focus:ring-2 focus:ring-indigo-500 focus:border-transparent transition"
+                    placeholder="Enter your username"
+                >
+            </div>
+            
+            <div>
+                <label class="block text-sm font-medium text-gray-700 mb-2">
+                    <i class="fas fa-lock mr-2"></i>Password
+                </label>
+                <input 
+                    type="password" 
+                    id="password" 
+                    name="password"
+                    required
+                    class="w-full px-4 py-3 border border-gray-300 rounded-lg focus:ring-2 focus:ring-indigo-500 focus:border-transparent transition"
+                    placeholder="Enter your password"
+                >
+            </div>
+            
+            <button 
+                type="submit"
+                class="w-full bg-indigo-600 text-white py-3 rounded-lg hover:bg-indigo-700 transition font-medium shadow-lg hover:shadow-xl"
+            >
+                <i class="fas fa-sign-in-alt mr-2"></i>Login
+            </button>
+        </form>
+        
+        <div class="mt-6 text-center">
+            <p class="text-gray-600">
+                Don't have an account? 
+                <a href="/register" class="text-indigo-600 hover:text-indigo-800 font-medium">
+                    Register here
+                </a>
+            </p>
+        </div>
+    </div>
+</div>
+{% endblock %}
+
+{% block scripts %}
+<script>
+    document.getElementById('loginForm').addEventListener('submit', async (e) => {
+        e.preventDefault();
+        
+        const username = document.getElementById('username').value;
+        const password = document.getElementById('password').value;
+        const alertDiv = document.getElementById('alert');
+        
+        try {
+            // Create form data for OAuth2
+            const formData = new URLSearchParams();
+            formData.append('username', username);
+            formData.append('password', password);
+            
+            const response = await fetch('/api/auth/login', {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/x-www-form-urlencoded',
+                },
+                body: formData
+            });
+            
+            const data = await response.json();
+            
+            if (response.ok) {
+                // Save token
+                localStorage.setItem('access_token', data.access_token);
+                localStorage.setItem('username', username);
+                
+                // Show success message
+                alertDiv.className = 'mb-4 p-4 rounded-lg bg-green-100 text-green-700';
+                alertDiv.textContent = 'Login successful! Redirecting...';
+                alertDiv.classList.remove('hidden');
+                
+                // Redirect to dashboard
+                setTimeout(() => {
+                    window.location.href = '/dashboard';
+                }, 1000);
+            } else {
+                // Show error
+                alertDiv.className = 'mb-4 p-4 rounded-lg bg-red-100 text-red-700';
+                alertDiv.textContent = data.detail || 'Login failed. Please try again.';
+                alertDiv.classList.remove('hidden');
+            }
+        } catch (error) {
+            alertDiv.className = 'mb-4 p-4 rounded-lg bg-red-100 text-red-700';
+            alertDiv.textContent = 'An error occurred. Please try again.';
+            alertDiv.classList.remove('hidden');
+        }
+    });
+</script>
+{% endblock %}