docs/guides/REMOTE_ACCESS_GUIDE.md

# SPARKNET Remote Access Guide

## Problem Solved ✅
Your SPARKNET frontend and backend are running on a remote server, and you need to access them from your local browser.

## Solution Applied
I've configured both services to bind to all network interfaces (0.0.0.0) so they're accessible from your local machine.

---

## Your Server IP Address
```
172.24.50.21
```

---

## Quick Start (Easiest Method)

### Step 1: Start Services

On your **remote server**, run:

```bash
cd /home/mhamdan/SPARKNET
bash start_services.sh
```

This will start both backend and frontend in the background.

### Step 2: Access from Local Browser

On your **local computer**, open your browser and go to:

```
http://172.24.50.21:3000
```

That's it! 🎉

---

## URLs Reference

| Service | URL | Description |
|---------|-----|-------------|
| **Frontend** | http://172.24.50.21:3000 | Main SPARKNET UI |
| **Backend API** | http://172.24.50.21:8000 | API endpoints |
| **API Docs** | http://172.24.50.21:8000/api/docs | Interactive API documentation |
| **Health Check** | http://172.24.50.21:8000/api/health | Backend health status |

---

## Manual Start (Alternative)

If you prefer to start services manually:

### Terminal 1 - Backend
```bash
cd /home/mhamdan/SPARKNET
conda activate agentic-ai
python -m api.main
```

### Terminal 2 - Frontend
```bash
cd /home/mhamdan/SPARKNET/frontend
conda activate agentic-ai
npm run dev
```

---

## Managing Services

### View Logs

If using screen (automatic with start_services.sh):

```bash
# View backend logs
screen -r sparknet-backend

# View frontend logs
screen -r sparknet-frontend

# Detach from screen (keeps it running)
Press: Ctrl+A then D
```

### Stop Services

```bash
cd /home/mhamdan/SPARKNET
bash stop_services.sh
```

Or manually:
```bash
# Stop backend screen
screen -S sparknet-backend -X quit

# Stop frontend screen
screen -S sparknet-frontend -X quit
```

---

## Troubleshooting

### Issue 1: Cannot Access from Local Browser

**Check 1**: Are services running?
```bash
# Check if ports are open
ss -tlnp | grep -E ':(3000|8000)'
```

You should see:
```
tcp   LISTEN 0.0.0.0:3000  (frontend)
tcp   LISTEN 0.0.0.0:8000  (backend)
```

**Check 2**: Firewall blocking?
```bash
# Check firewall status
sudo ufw status

# If firewall is active, allow ports
sudo ufw allow 3000
sudo ufw allow 8000
```

**Check 3**: Can you ping the server?
```bash
# On your local machine
ping 172.24.50.21
```

**Check 4**: Try curl from local machine
```bash
# On your local machine, try:
curl http://172.24.50.21:8000/api/health
```

### Issue 2: Services Not Starting

**Check Node.js**:
```bash
source /home/mhamdan/miniconda3/etc/profile.d/conda.sh
conda activate agentic-ai
node --version  # Should show v24.9.0
```

**Check Backend**:
```bash
cd /home/mhamdan/SPARKNET
python -m api.main
# Look for errors in output
```

**Check Frontend**:
```bash
cd /home/mhamdan/SPARKNET/frontend
npm run dev
# Look for errors in output
```

### Issue 3: CORS Errors

If you see CORS errors in browser console, verify:

1. Backend CORS settings include your IP:
```bash
grep -A 5 "allow_origins" /home/mhamdan/SPARKNET/api/main.py
```

Should include: `http://172.24.50.21:3000`

2. Frontend .env.local has correct API URL:
```bash
cat /home/mhamdan/SPARKNET/frontend/.env.local
```

Should show: `NEXT_PUBLIC_API_URL=http://172.24.50.21:8000`

---

## Network Configuration Summary

### What Was Changed

1. **Frontend (Next.js)**:
   - Changed bind address from `localhost` to `0.0.0.0`
   - Updated `.env.local` to use server IP instead of localhost
   - Modified `package.json` scripts to use `-H 0.0.0.0`

2. **Backend (FastAPI)**:
   - Already binding to `0.0.0.0` (no change needed)
   - Added server IP to CORS allowed origins
   - Ports: Backend on 8000, Frontend on 3000

---

## Alternative Access Methods

### Method 1: SSH Port Forwarding (If Direct Access Doesn't Work)

On your **local machine**, create an SSH tunnel:

```bash
ssh -L 3000:localhost:3000 -L 8000:localhost:8000 mhamdan@172.24.50.21
```

Then access via:
- Frontend: http://localhost:3000
- Backend: http://localhost:8000

Keep the SSH connection open while using the app.

### Method 2: ngrok (For External Access)

If you want to access from anywhere:

```bash
# Install ngrok
curl -s https://ngrok-agent.s3.amazonaws.com/ngrok.asc | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null
echo "deb https://ngrok-agent.s3.amazonaws.com buster main" | sudo tee /etc/apt/sources.list.d/ngrok.list
sudo apt update && sudo apt install ngrok

# Start tunnels (in separate terminals)
ngrok http 3000  # Frontend
ngrok http 8000  # Backend
```

---

## Testing the Application

### 1. Test Backend API
```bash
# From your local machine
curl http://172.24.50.21:8000/api/health
```

Expected response:
```json
{
  "status": "healthy",
  "components": { ... },
  "statistics": { ... }
}
```

### 2. Test Frontend
Open browser to: http://172.24.50.21:3000

You should see:
- Beautiful landing page with gradient SPARKNET logo
- "Transform Dormant Patents..." heading
- Features showcase
- "Start Patent Analysis" button

### 3. Test Full Workflow
1. Click "Start Patent Analysis" or go to http://172.24.50.21:3000/upload
2. Drag-and-drop a PDF from your Dataset/
3. Watch real-time progress at http://172.24.50.21:3000/workflow/{id}
4. View results at http://172.24.50.21:3000/results/{id}

---

## Performance Notes

### Expected Speed
- Frontend load: < 1 second
- API response: < 100ms
- WebSocket latency: < 50ms
- Patent analysis: 2-5 minutes

### Network Requirements
- Minimum bandwidth: 1 Mbps
- Recommended: 10+ Mbps for smooth experience
- Stable connection for WebSocket real-time updates

---

## Security Notes

### Current Setup (Development)
- ⚠️ No authentication
- ⚠️ HTTP (not HTTPS)
- ⚠️ No rate limiting
- ✅ CORS configured for specific origins
- ✅ File validation (PDF only, max 50MB)
- ✅ Input sanitization

### For Production
Consider adding:
- HTTPS/SSL certificates
- JWT authentication
- Rate limiting
- API keys
- Firewall rules limiting access

---

## Quick Commands Reference

```bash
# Start everything
cd /home/mhamdan/SPARKNET && bash start_services.sh

# Stop everything
cd /home/mhamdan/SPARKNET && bash stop_services.sh

# View backend logs
screen -r sparknet-backend

# View frontend logs
screen -r sparknet-frontend

# Check if running
ss -tlnp | grep -E ':(3000|8000)'

# Test backend
curl http://172.24.50.21:8000/api/health

# Test frontend
curl http://172.24.50.21:3000
```

---

## Success Checklist

- [ ] Services started with `bash start_services.sh`
- [ ] Can access http://172.24.50.21:8000/api/health from local browser
- [ ] Can access http://172.24.50.21:3000 from local browser
- [ ] Landing page loads correctly
- [ ] Can upload a patent PDF
- [ ] Real-time progress updates work
- [ ] Results display correctly
- [ ] Can download valorization brief

---

## Need Help?

### Check Logs
```bash
# Backend logs
screen -r sparknet-backend

# Frontend logs
screen -r sparknet-frontend

# System logs
journalctl -xe
```

### Common Issues

1. **Connection Refused**: Services not running or firewall blocking
2. **CORS Error**: Check CORS configuration in backend
3. **404 Error**: Wrong URL or service not started
4. **Slow Loading**: Network congestion or server resources

---

## Summary

**Your SPARKNET application is now accessible from your local browser!**

Simply open: **http://172.24.50.21:3000**

The frontend will automatically connect to the backend API at http://172.24.50.21:8000 for all operations including:
- Patent upload
- Workflow execution
- Real-time WebSocket updates
- Results retrieval
- PDF download

Enjoy your beautiful SPARKNET interface! 🚀