Hugging Face's logo

Spaces:
webflow97
/
deployment-taskflow
Sleeping

App Files Community
deployment-taskflow / DEPLOYMENT.md
Tripagra
Deploy to Vercel: Add serverless functions, frontend, and deployment docs
964103b
preview code
|
Raw
History Blame Contribute Delete
8.45 kB

Vercel Deployment Guide

This guide walks you through deploying the Smart Escalation API to Vercel as a monorepo with both frontend and backend.

Quick Start

1. Prerequisites

2. Deploy to Vercel

Click the button below to deploy:

Deploy with Vercel

Or follow manual steps:

Step 1: Import Project

  1. Go to vercel.com
  2. Click "Add New..." → "Project"
  3. Import your GitHub repository
  4. Vercel will auto-detect the configuration from vercel.json

Step 2: Configure Environment Variables

Add these environment variables in the Vercel dashboard:

Variable Value Required
GOOGLE_API_KEY Your Gemini API key ✅ Yes
EMBEDDING_MODEL all-MiniLM-L6-v2 No (has default)
RELEVANCE_THRESHOLD 0.5 No (has default)
TOP_K_CHUNKS 3 No (has default)
LLM_MODEL gemini-1.5-flash No (has default)
LLM_TEMPERATURE 0.3 No (has default)

Important: Set these for all environments (Production, Preview, Development)

Step 3: Deploy

  1. Click "Deploy"
  2. Wait 2-3 minutes for build
  3. Visit your deployment URL

3. Test Your Deployment

  1. Visit https://your-app.vercel.app
  2. Try these test questions:
    • "How do I create a new project in TaskFlow?" (should answer)
    • "What's the weather today?" (should escalate)
  3. Check that responses appear correctly

Architecture

Monorepo Structure 

smart-escalation-api/
├── api/                    # Vercel Serverless Functions (Backend)
│   └── ask.py             # POST /api/ask endpoint
├── frontend/              # React Frontend
│   ├── src/
│   └── dist/              # Built static files
├── src/                   # Shared Python modules
│   ├── rag.py
│   ├── escalation.py
│   ├── llm_client.py
│   └── config.py
├── data/articles/         # Help articles knowledge base
├── vercel.json           # Vercel configuration
└── package.json          # Monorepo configuration

How It Works

  1. Frontend: React app built with Vite, served as static files
  2. Backend: Python serverless function at /api/ask
  3. Same Origin: Frontend calls /api/ask (no CORS needed)
  4. Automatic HTTPS: Vercel provides SSL certificates
  5. Global CDN: Fast access worldwide

Configuration

vercel.json

The vercel.json file configures:

  • Python runtime for API functions
  • Static build for frontend
  • Routing rules (API vs frontend)

Environment Variables

Set in Vercel Dashboard → Settings → Environment Variables

Required:

  • GOOGLE_API_KEY: Your Gemini API key

Optional (with defaults):

  • EMBEDDING_MODEL: Sentence transformer model
  • RELEVANCE_THRESHOLD: Escalation threshold (0-1)
  • TOP_K_CHUNKS: Number of chunks to retrieve
  • LLM_MODEL: Gemini model to use
  • LLM_TEMPERATURE: LLM temperature (0-1)

Local Development

Backend Only 

# Install Python dependencies
pip install -r requirements.txt

# Run FastAPI server
uvicorn src.main:app --reload

API available at: http://localhost:8000

Frontend Only 

# Install Node dependencies
cd frontend
npm install

# Set API URL for local backend
echo "VITE_API_URL=http://localhost:8000" > .env

# Run dev server
npm run dev

Frontend available at: http://localhost:5173

Full Stack (Vercel Dev) 

# Install Vercel CLI
npm install -g vercel

# Run local Vercel environment
vercel dev

This simulates the Vercel environment locally.

Troubleshooting

Build Fails

Problem: "Module not found" error

Solution:

  • Ensure requirements.txt includes all dependencies
  • Check Python version is 3.9+ in vercel.json
  • Verify all files are committed to git

API Returns 500

Problem: Serverless function crashes

Solution:

  • Check function logs in Vercel Dashboard
  • Verify GOOGLE_API_KEY is set correctly
  • Ensure data/articles/ directory exists
  • Check that help articles are valid markdown

Frontend Can't Reach API

Problem: "Failed to fetch" errors

Solution:

  • Verify API endpoint: https://your-app.vercel.app/api/ask
  • Check browser console for errors
  • Test API directly with curl:
    curl -X POST https://your-app.vercel.app/api/ask \
  -H "Content-Type: application/json" \
  -d '{"question":"test"}'

Slow Response Times

Problem: Requests take >10 seconds

Solution:

  • First request loads embedding model (2-3s cold start)
  • Subsequent requests are faster (cached)
  • Use gemini-1.5-flash for faster responses
  • Consider Vercel Pro for better performance

Out of Memory

Problem: Function crashes with memory error

Solution:

  • Vercel free tier: 1GB memory limit
  • Reduce TOP_K_CHUNKS to use less memory
  • Use smaller embedding model
  • Upgrade to Pro plan for 3GB memory

Monitoring

Vercel Dashboard

Monitor your deployment:

  1. Go to Vercel Dashboard → Your Project
  2. View real-time logs in Deployments tab
  3. Check function execution time and errors
  4. Monitor bandwidth usage

Enable Analytics

  1. Go to Analytics tab in Vercel Dashboard
  2. Enable Web Analytics (free)
  3. Enable Speed Insights for performance monitoring

Key Metrics

Watch for:

  • Function execution time (should be <5s)
  • Error rate (should be <5%)
  • Cold start frequency
  • Memory usage

Updating

Update Code 

# Make changes
git add .
git commit -m "Update feature"
git push

# Vercel automatically deploys

Update Help Articles 

# Edit articles
vim data/articles/getting-started.md

# Commit and push
git add data/articles/
git commit -m "Update help articles"
git push

# Vercel redeploys, vector store rebuilds

Update Dependencies

Python:

# Update requirements.txt
pip install new-package
pip freeze > requirements.txt

# Commit and push
git add requirements.txt
git commit -m "Add new dependency"
git push

Node:

cd frontend
npm install new-package
git add package.json package-lock.json
git commit -m "Add new dependency"
git push

Cost Estimates

Vercel Free Tier

  • ✅ 100GB bandwidth/month
  • ✅ 100 hours function execution/month
  • ✅ 6,000 function invocations/day
  • ✅ Unlimited deployments
  • ✅ Automatic HTTPS
  • ✅ Global CDN

Expected Usage

For low-medium traffic (100-500 requests/day):

  • Function time: ~1-2s per request
  • Daily usage: 100-1000s = 0.03-0.3 hours/day
  • Monthly usage: 1-9 hours/month
  • Well within free tier limits

When to Upgrade

Upgrade to Pro ($20/month) if you need:

  • 100 hours function execution

  • 6,000 requests/day

  • 60s timeout (vs 10s)
  • 3GB memory (vs 1GB)
  • Priority support

Additional Costs

  • Google Gemini API: Free tier (15 req/min, 1500 req/day)
  • Total: $0-20/month depending on traffic

Security

Best Practices

  1. ✅ Never commit API keys to git
  2. ✅ Use Vercel environment variables for secrets
  3. ✅ Rotate API keys periodically
  4. ✅ Monitor logs for suspicious activity
  5. ✅ Keep dependencies updated

Automatic Security

Vercel provides:

  • ✅ Automatic HTTPS/SSL
  • ✅ DDoS protection
  • ✅ Secure environment variables
  • ✅ Isolated function execution

Support

Resources

Getting Help

  1. Check README.md for detailed documentation
  2. Review Troubleshooting section above
  3. Check Vercel function logs for errors
  4. Open GitHub issue for bugs
  5. Contact Vercel support (Pro plan)

Next Steps

After deployment:

  1. ✅ Test with various questions
  2. ✅ Monitor performance in Vercel Dashboard
  3. ✅ Enable Analytics for insights
  4. ✅ Set up custom domain (optional)
  5. ✅ Configure alerts for errors
  6. ✅ Share with users!

Need help? Open an issue on GitHub or check the README.md for more details.