HF_ARCHITECTURE_DIAGRAM.md

# 🏗️ 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)