Spaces:
Sleeping
Sleeping
🏗️ 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)