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

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)

# 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

# 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:

git push origin main && git push hf main

Or push to both at once:

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)

[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

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