🚀 Zege V1 Backend

Production-ready backend for Zege V1 - A browser-based IDE with AI support and code execution.

✨ Features

• 🔐 JWT Authentication with refresh tokens
• 🐳 Docker-based Code Execution (9 languages: Python, Node, Java, C/C++, Go, Rust, Ruby, PHP)
• 💾 Backblaze B2 Storage (Free 10GB)
• 🤖 Google Gemini AI (Free unlimited)
• ⚡ Supabase Caching (Free 500MB)
• 📊 MongoDB Atlas for data persistence
• 🔌 WebSockets for real-time execution logs
• 🛡️ Security - Rate limiting, helmet, CORS
• 📦 Production Ready with Docker Compose

📚 Documentation

All documentation is now organized in the /docs folder!

🎯 Quick Links:

To Deploy Right Now:

• 📖 PORTAINER_QUICK_REFERENCE.md - Copy-paste config
• 📖 DEPLOY_TO_VPS.md - Upload code to VPS

To Understand the Project:

• 📖 START_HERE_HYBRID.md - Architecture overview
• 📖 MIGRATION_SUMMARY.md - What changed

See /docs/README.md for complete documentation index.

---

⚡ Quick Start (5 Minutes)

Prerequisites

• VPS with Docker installed
• Portainer GUI installed
• Git or SCP access to VPS

🛠️ Installation

1. Clone the repository

cd backend

1. Upload Code to VPS

# See docs/DEPLOY_TO_VPS.md for detailed instructions

# Option A: Git
git clone https://github.com/YOUR_USERNAME/zege-backend.git

# Option B: SCP
scp -r ./backend your-user@your-vps-ip:/opt/zege-backend

2. Create Container in Portainer

Open docs/PORTAINER_QUICK_REFERENCE.md and follow the copy-paste instructions!

3. Done!

Test your deployment:

curl http://your-vps-ip:5000/health

---

🏗️ Tech Stack

Component	Technology	Tier
Runtime	Node.js 18 + Express	Backend
Database	MongoDB Atlas	Cloud (Free)
Storage	Backblaze B2	Cloud (Free 10GB)
AI	Google Gemini Pro	Cloud (Free)
Caching	Supabase	Cloud (Free 500MB)
Code Execution	Docker + Dockerode	Self-hosted
Real-time	Socket.IO	Backend
Auth	JWT + bcrypt	Backend

📁 Project Structure

/backend
  /docs              → 📚 All documentation (organized!)
  /src
    /config          → DB, Logger, Environment
    /models          → MongoDB schemas
    /controllers     → Request handlers
    /routes          → API routes
    /services        → Docker, B2, Gemini, Supabase
    /middlewares     → Auth, Validation, Rate limiting
    /ws              → WebSocket for real-time logs
  index.js           → Entry point
  Dockerfile         → Container config
  docker-compose.yml → Multi-container setup
  .env               → Your configuration

🔌 API Overview

Authentication (/api/auth)

• Signup, Login, Logout
• JWT with refresh tokens
• Session management

Projects (/api/projects)

• CRUD operations
• Version control
• Export/Import (ZIP to B2)

Runtime (/api/runtime)

• Execute code (9 languages)
• Real-time logs via WebSocket
• Stop execution
• Supported languages list

AI Assistant (/api/ai)

• Chat with Gemini
• Code completion (with caching)
• Code explanation
• Error fixing

See docs/API.md for complete API documentation.

🔐 Security

✅ Helmet.js - Secure headers ✅ CORS - Restricted origins
✅ Rate Limiting - 100 req/min ✅ Input Sanitization - XSS/NoSQL injection protection ✅ JWT Authentication - Secure tokens ✅ Docker Sandboxing - Isolated execution ✅ Password Hashing - bcrypt (12 rounds)

🐳 Docker Code Execution

• Account Locking - After 5 failed attempts

🐳 Docker

Build image

Supports 9 languages:

• 🐍 Python 3.11
• 📗 Node.js 18
• ☕ Java 17
• ⚙️ C/C++ (GCC)
• 🔷 Go 1.21
• 🦀 Rust (latest)
• 💎 Ruby 3.2
• 🐘 PHP 8.2
• More coming soon!

See docs/DOCKER_EXECUTION_GUIDE.md for details.

---

📊 Monitoring & Testing

Health Check

curl http://localhost:5000/health
# Expected: {"status":"ok","timestamp":"...","uptime":5.123}

View Logs

# Docker Compose
docker-compose logs -f backend

# Portainer
Containers → zege-backend → Logs tab

Run Tests

npm test

---

� Configuration

All configuration is in .env file. See .env.example for template.

Key Variables:

• MONGODB_URI - MongoDB Atlas connection
• B2_APPLICATION_KEY_ID - Backblaze B2 credentials
• GEMINI_API_KEY - Google Gemini API key
• SUPABASE_URL - Supabase project URL
• JWT_* - Authentication secrets

See docs/QUICK_START_FREE.md for how to get free API keys.

---

🚦 Rate Limits

Endpoint	Limit
General API	100 req/min
Auth	5 req/min
Code Execution	10 req/min
AI Requests	20 req/min

---

� Additional Resources

• Complete Documentation Index
• Architecture Overview
• Migration Summary
• API Documentation

---

🤝 Contributing

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing)
5. Open Pull Request

---

📜 License

MIT License - See LICENSE file for details

---

� Need Help?

1. Check /docs folder for guides
2. Read PORTAINER_QUICK_REFERENCE.md for deployment
3. Create an issue for bugs/questions

---

Built with ❤️ using free-tier services