docs_connection.md

# SPARKNET Deployment Architecture

## Quick Answer

**For Streamlit Cloud:** Push to **GitHub only** (`git push origin main`), then reboot the app.

**For Hugging Face Spaces:** Push to **Hugging Face only** (`git push hf main`).

They are **independent deployments** - you choose which platform to use.

---

## Architecture Overview

```
+------------------+          +-------------------+
|    Your Code     |          |   Lytos Server    |
|   (Local/Git)    |          |   172.24.50.21    |
+--------+---------+          +---------+---------+
         |                              |
         |                              | Backend API
    +----+----+                         | (port 8000)
    |         |                         |
    v         v                         v
+-------+  +--------+           +---------------+
|GitHub |  |Hugging |           | localtunnel   |
|       |  |Face    |           | (public URL)  |
+---+---+  +---+----+           +-------+-------+
    |          |                        |
    |          |                        |
    v          v                        |
+----------+  +-----------+             |
|Streamlit |  |HF Spaces  |<------------+
|Cloud     |  |           |   Backend calls
+----------+  +-----------+
```

---

## Platform Comparison

| Feature | Streamlit Cloud | Hugging Face Spaces |
|---------|-----------------|---------------------|
| **Source** | GitHub repo | HF repo (or GitHub) |
| **Push command** | `git push origin main` | `git push hf main` |
| **Auto-rebuild** | Yes (on push) | Yes (on push) |
| **Secrets** | Dashboard > Settings > Secrets | Settings > Variables |
| **Free tier** | Yes (limited resources) | Yes (limited resources) |
| **Custom domain** | Premium only | Premium only |
| **GPU support** | No | Yes (paid) |

---

## Your Current Setup

### Git Remotes
```bash
origin  -> github.com:MHHamdan/SPARKNET.git     # For Streamlit Cloud
hf      -> hf.co:spaces/mhamdan/SPARKNET.git   # For Hugging Face Spaces
```

### Deployment URLs
- **Streamlit Cloud:** `https://mhhamdan-sparknet.streamlit.app`
- **Hugging Face:** `https://huggingface.co/spaces/mhamdan/SPARKNET`

### Backend (Lytos GPU Server)
- **Internal:** `http://172.24.50.21:8000`
- **Public (via tunnel):** `https://selfish-crab-86.loca.lt`

---

## How to Deploy

### Option 1: Streamlit Cloud (Recommended)

```bash
# 1. Make changes locally
# 2. Commit
git add .
git commit -m "Your message"

# 3. Push to GitHub
git push origin main

# 4. Streamlit Cloud auto-rebuilds (or manually reboot in dashboard)
```

**Secrets location:** https://share.streamlit.io > Your App > Settings > Secrets

### Option 2: Hugging Face Spaces

```bash
# 1. Make changes locally
# 2. Commit
git add .
git commit -m "Your message"

# 3. Push to Hugging Face
git push hf main

# 4. HF Spaces auto-rebuilds
```

**Secrets location:** https://huggingface.co/spaces/mhamdan/SPARKNET/settings

---

## Keeping Both in Sync

If you want both platforms updated:

```bash
git push origin main && git push hf main
```

Or push to both at once:
```bash
git remote add all git@github.com:MHHamdan/SPARKNET.git
git remote set-url --add all git@hf.co:spaces/mhamdan/SPARKNET.git
git push all main
```

---

## Backend Connection Flow

```
User Browser
     |
     v
Streamlit Cloud (frontend)
     |
     | HTTP requests to BACKEND_URL
     v
localtunnel (https://selfish-crab-86.loca.lt)
     |
     | tunnels to
     v
Lytos Server (172.24.50.21:8000)
     |
     | processes with
     v
PaddleOCR + Ollama + GPU
```

---

## Required Secrets (Streamlit Cloud)

```toml
[auth]
password = "SPARKNET@2026"

BACKEND_URL = "https://selfish-crab-86.loca.lt"

GROQ_API_KEY = "your-key"
HF_TOKEN = "your-token"
GOOGLE_API_KEY = "your-key"
OPENROUTER_API_KEY = "your-key"
MISTRAL_API_KEY = "your-key"
```

---

## Troubleshooting

| Issue | Solution |
|-------|----------|
| Changes not appearing | Reboot app in Streamlit dashboard |
| Backend connection failed | Check if localtunnel is running (`screen -r lt-tunnel`) |
| Tunnel URL changed | Update `BACKEND_URL` in Streamlit secrets |
| PaddleOCR warning | Normal on Streamlit Cloud - backend handles OCR |

---

## Screen Sessions on Lytos

```bash
screen -ls                    # List sessions
screen -r sparknet-backend    # Attach to backend
screen -r lt-tunnel           # Attach to tunnel
screen -r ollama              # Attach to Ollama
```