deploy: b1de43e — 更新 README.md

.env.example

@@ -0,0 +1,38 @@
+# ─────────────────────────────────────────────────────────────────────────────
+# AI Gateway Hub — Environment Configuration
+# Copy this file to .env and fill in your values.
+# ─────────────────────────────────────────────────────────────────────────────
+
+# ── Security ──────────────────────────────────────────────────────────────────
+# Master key for LiteLLM proxy admin API.
+# Change this in production!
+LITELLM_MASTER_KEY=sk-gateway-master-key-change-me
+
+# JWT secret for backend sessions (future use).
+JWT_SECRET=super-secret-jwt-key-change-in-production
+
+# ── Networking ────────────────────────────────────────────────────────────────
+# The public URL where your gateway is accessible.
+# This is used to generate the OpenAI-compatible endpoint URLs shown in the UI.
+GATEWAY_PUBLIC_URL=http://localhost
+
+# HTTP/HTTPS ports for the nginx reverse proxy.
+HTTP_PORT=80
+HTTPS_PORT=443
+
+# ── Optional: Pre-configured provider keys ───────────────────────────────────
+# These can be set here as env vars for providers configured in litellm/config.yaml.
+# OPENAI_API_KEY=sk-...
+# ANTHROPIC_API_KEY=sk-ant-...
+# GROQ_API_KEY=gsk_...
+# GEMINI_API_KEY=...
+# COHERE_API_KEY=...
+# MISTRAL_API_KEY=...
+# TOGETHER_API_KEY=...
+# PERPLEXITYAI_API_KEY=pplx-...
+
+# ── Logging ───────────────────────────────────────────────────────────────────
+# BUG FIX #1: Was "info" (level 2) which silently drops all Morgan HTTP logs
+# (level 3). Must be "http" or lower to see HTTP access logs in the console.
+# Winston level hierarchy: error(0) < warn(1) < info(2) < http(3) < verbose(4)
+LOG_LEVEL=http

.gitattributes

@@ -1,35 +0,0 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,35 @@
+# Environment
+.env
+.env.local
+
+# Dependencies
+node_modules/
+*/node_modules/
+
+# Build output
+frontend/dist/
+frontend/.vite/
+
+# Data volumes (Docker)
+data/
+*.db
+*.db-shm
+*.db-wal
+
+# Logs
+*.log
+logs/
+
+# SSL certificates
+nginx/ssl/*.pem
+nginx/ssl/*.key
+nginx/ssl/*.crt
+
+# OS
+.DS_Store
+Thumbs.db
+
+# IDE
+.idea/
+.vscode/
+*.swp

Dockerfile

@@ -0,0 +1,138 @@
+# ─────────────────────────────────────────────────────────────────────────────
+# Dockerfile.huggingface
+#
+# Single-container build for Hugging Face Spaces (Docker SDK).
+#
+# Architecture inside the container:
+#
+#   ┌──────────────────────────────────────────┐  port 7860 (HF Spaces)
+#   │  nginx                                   │──────────────────────►
+#   │    /          → static frontend files    │
+#   │    /api/*     → localhost:3001 (backend) │
+#   │    /v1/*      → localhost:4000 (litellm) │
+#   └──────────────────────────────────────────┘
+#        │                    │
+#        ▼                    ▼
+#   Node.js backend      LiteLLM proxy
+#   (port 3001)          (port 4000)
+#        │
+#        ▼
+#   SQLite  /app/data/gateway.db
+#
+# All processes are managed by supervisord.
+#
+# Bug fixes applied:
+#   [Bug2] Added build-essential so better-sqlite3 can compile via node-gyp
+#          if the prebuilt binary download fails.
+#   [Bug3] Changed `npm ci --only=production` → `npm ci --omit=dev`
+#          (--only=production is deprecated since npm v7; Node 20 ships npm v10).
+#   [Bug5] LiteLLM pip version extracted to ARG LITELLM_VERSION so it stays
+#          in sync with docker-compose.yml without touching two separate lines.
+# ─────────────────────────────────────────────────────────────────────────────
+
+# ── Stage 1: Build React frontend ─────────────────────────────────────────────
+FROM node:20-alpine AS frontend-builder
+
+WORKDIR /build
+
+# Build args match the original frontend/Dockerfile
+ARG VITE_API_BASE=/api
+ARG VITE_APP_NAME="AI Gateway Hub"
+ENV VITE_API_BASE=$VITE_API_BASE \
+    VITE_APP_NAME=$VITE_APP_NAME
+
+# Layer-cache package install separately from source copy
+COPY frontend/package*.json ./
+RUN npm ci
+
+COPY frontend/ .
+RUN npm run build
+
+# ── Stage 2: Production runtime ───────────────────────────────────────────────
+FROM python:3.11-slim
+
+# ── LiteLLM version — keep in sync with docker-compose.yml image tag ──────────
+# docker-compose.yml: ghcr.io/berriai/litellm:main-v1.81.14-stable
+#                     → PyPI package:        litellm==1.81.14
+# To upgrade: change both this ARG and the docker-compose image tag together.
+ARG LITELLM_VERSION=1.81.14
+
+# ── System deps ───────────────────────────────────────────────────────────────
+# build-essential (make + g++) is required as a fallback compilation path for
+# better-sqlite3. prebuild-install downloads a prebuilt .node binary at npm ci
+# time; if that download fails (version mismatch, network timeout, etc.) the
+# package falls back to compiling from source via node-gyp, which needs make
+# and g++. Without build-essential that fallback path crashes the build.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        curl \
+        gnupg \
+        ca-certificates \
+        nginx \
+        supervisor \
+        build-essential \
+    && \
+    # Node.js 20 LTS (backend runtime — frontend is pre-built in Stage 1)
+    curl -fsSL https://deb.nodesource.com/setup_20.x | bash - && \
+    apt-get install -y --no-install-recommends nodejs && \
+    # Clean up (gnupg no longer needed after nodesource setup)
+    apt-get purge -y gnupg && \
+    apt-get autoremove -y && \
+    rm -rf /var/lib/apt/lists/*
+
+# ── LiteLLM proxy ─────────────────────────────────────────────────────────────
+RUN pip install --no-cache-dir "litellm[proxy]==${LITELLM_VERSION}"
+
+# ── Non-root user (HF Spaces recommendation: uid=1000) ────────────────────────
+RUN useradd -m -u 1000 -s /bin/bash user
+
+# ── Directory layout ──────────────────────────────────────────────────────────
+RUN mkdir -p \
+        /app/frontend/dist \
+        /app/backend/src \
+        /app/litellm \
+        /app/huggingface \
+        /app/data \
+        /var/log/supervisor \
+        /tmp/nginx/client_body \
+        /tmp/nginx/proxy \
+        /tmp/nginx/fastcgi \
+        /tmp/nginx/uwsgi \
+        /tmp/nginx/scgi \
+    && \
+    # Give nginx writable log/lib dirs when running as uid 1000
+    chown -R user:user \
+        /app \
+        /var/log/supervisor \
+        /var/log/nginx \
+        /var/lib/nginx \
+        /tmp/nginx
+
+# ── Frontend (pre-built in Stage 1) ───────────────────────────────────────────
+COPY --from=frontend-builder --chown=user:user /build/dist /app/frontend/dist
+
+# ── Backend ───────────────────────────────────────────────────────────────────
+COPY --chown=user:user backend/package*.json /app/backend/
+
+# FIX [Bug3]: --only=production is deprecated since npm v7 and broken in npm v10
+# (Node 20). The correct flag is --omit=dev.
+# We run npm ci as root so node-gyp can write to system temp dirs during native
+# addon compilation (better-sqlite3), then hand ownership to the user.
+RUN cd /app/backend && npm ci --omit=dev && chown -R user:user /app/backend/node_modules
+
+COPY --chown=user:user backend/src/ /app/backend/src/
+
+# ── Configs ───────────────────────────────────────────────────────────────────
+COPY --chown=user:user litellm/config.yaml           /app/litellm/config.yaml
+COPY --chown=user:user huggingface/nginx.conf        /app/huggingface/nginx.conf
+COPY --chown=user:user huggingface/supervisord.conf  /app/huggingface/supervisord.conf
+COPY --chown=user:user huggingface/entrypoint.sh     /app/huggingface/entrypoint.sh
+RUN chmod +x /app/huggingface/entrypoint.sh
+
+# ── Switch to non-root ────────────────────────────────────────────────────────
+USER user
+WORKDIR /app
+
+# HF Spaces listens on 7860 (declared in huggingface/README.md frontmatter)
+EXPOSE 7860
+
+ENTRYPOINT ["/app/huggingface/entrypoint.sh"]

Dockerfile.huggingface

@@ -0,0 +1,138 @@
+# ─────────────────────────────────────────────────────────────────────────────
+# Dockerfile.huggingface
+#
+# Single-container build for Hugging Face Spaces (Docker SDK).
+#
+# Architecture inside the container:
+#
+#   ┌──────────────────────────────────────────┐  port 7860 (HF Spaces)
+#   │  nginx                                   │──────────────────────►
+#   │    /          → static frontend files    │
+#   │    /api/*     → localhost:3001 (backend) │
+#   │    /v1/*      → localhost:4000 (litellm) │
+#   └──────────────────────────────────────────┘
+#        │                    │
+#        ▼                    ▼
+#   Node.js backend      LiteLLM proxy
+#   (port 3001)          (port 4000)
+#        │
+#        ▼
+#   SQLite  /app/data/gateway.db
+#
+# All processes are managed by supervisord.
+#
+# Bug fixes applied:
+#   [Bug2] Added build-essential so better-sqlite3 can compile via node-gyp
+#          if the prebuilt binary download fails.
+#   [Bug3] Changed `npm ci --only=production` → `npm ci --omit=dev`
+#          (--only=production is deprecated since npm v7; Node 20 ships npm v10).
+#   [Bug5] LiteLLM pip version extracted to ARG LITELLM_VERSION so it stays
+#          in sync with docker-compose.yml without touching two separate lines.
+# ─────────────────────────────────────────────────────────────────────────────
+
+# ── Stage 1: Build React frontend ─────────────────────────────────────────────
+FROM node:20-alpine AS frontend-builder
+
+WORKDIR /build
+
+# Build args match the original frontend/Dockerfile
+ARG VITE_API_BASE=/api
+ARG VITE_APP_NAME="AI Gateway Hub"
+ENV VITE_API_BASE=$VITE_API_BASE \
+    VITE_APP_NAME=$VITE_APP_NAME
+
+# Layer-cache package install separately from source copy
+COPY frontend/package*.json ./
+RUN npm ci
+
+COPY frontend/ .
+RUN npm run build
+
+# ── Stage 2: Production runtime ───────────────────────────────────────────────
+FROM python:3.11-slim
+
+# ── LiteLLM version — keep in sync with docker-compose.yml image tag ──────────
+# docker-compose.yml: ghcr.io/berriai/litellm:main-v1.81.14-stable
+#                     → PyPI package:        litellm==1.81.14
+# To upgrade: change both this ARG and the docker-compose image tag together.
+ARG LITELLM_VERSION=1.81.14
+
+# ── System deps ───────────────────────────────────────────────────────────────
+# build-essential (make + g++) is required as a fallback compilation path for
+# better-sqlite3. prebuild-install downloads a prebuilt .node binary at npm ci
+# time; if that download fails (version mismatch, network timeout, etc.) the
+# package falls back to compiling from source via node-gyp, which needs make
+# and g++. Without build-essential that fallback path crashes the build.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        curl \
+        gnupg \
+        ca-certificates \
+        nginx \
+        supervisor \
+        build-essential \
+    && \
+    # Node.js 20 LTS (backend runtime — frontend is pre-built in Stage 1)
+    curl -fsSL https://deb.nodesource.com/setup_20.x | bash - && \
+    apt-get install -y --no-install-recommends nodejs && \
+    # Clean up (gnupg no longer needed after nodesource setup)
+    apt-get purge -y gnupg && \
+    apt-get autoremove -y && \
+    rm -rf /var/lib/apt/lists/*
+
+# ── LiteLLM proxy ─────────────────────────────────────────────────────────────
+RUN pip install --no-cache-dir "litellm[proxy]==${LITELLM_VERSION}"
+
+# ── Non-root user (HF Spaces recommendation: uid=1000) ────────────────────────
+RUN useradd -m -u 1000 -s /bin/bash user
+
+# ── Directory layout ──────────────────────────────────────────────────────────
+RUN mkdir -p \
+        /app/frontend/dist \
+        /app/backend/src \
+        /app/litellm \
+        /app/huggingface \
+        /app/data \
+        /var/log/supervisor \
+        /tmp/nginx/client_body \
+        /tmp/nginx/proxy \
+        /tmp/nginx/fastcgi \
+        /tmp/nginx/uwsgi \
+        /tmp/nginx/scgi \
+    && \
+    # Give nginx writable log/lib dirs when running as uid 1000
+    chown -R user:user \
+        /app \
+        /var/log/supervisor \
+        /var/log/nginx \
+        /var/lib/nginx \
+        /tmp/nginx
+
+# ── Frontend (pre-built in Stage 1) ───────────────────────────────────────────
+COPY --from=frontend-builder --chown=user:user /build/dist /app/frontend/dist
+
+# ── Backend ───────────────────────────────────────────────────────────────────
+COPY --chown=user:user backend/package*.json /app/backend/
+
+# FIX [Bug3]: --only=production is deprecated since npm v7 and broken in npm v10
+# (Node 20). The correct flag is --omit=dev.
+# We run npm ci as root so node-gyp can write to system temp dirs during native
+# addon compilation (better-sqlite3), then hand ownership to the user.
+RUN cd /app/backend && npm ci --omit=dev && chown -R user:user /app/backend/node_modules
+
+COPY --chown=user:user backend/src/ /app/backend/src/
+
+# ── Configs ───────────────────────────────────────────────────────────────────
+COPY --chown=user:user litellm/config.yaml           /app/litellm/config.yaml
+COPY --chown=user:user huggingface/nginx.conf        /app/huggingface/nginx.conf
+COPY --chown=user:user huggingface/supervisord.conf  /app/huggingface/supervisord.conf
+COPY --chown=user:user huggingface/entrypoint.sh     /app/huggingface/entrypoint.sh
+RUN chmod +x /app/huggingface/entrypoint.sh
+
+# ── Switch to non-root ────────────────────────────────────────────────────────
+USER user
+WORKDIR /app
+
+# HF Spaces listens on 7860 (declared in huggingface/README.md frontmatter)
+EXPOSE 7860
+
+ENTRYPOINT ["/app/huggingface/entrypoint.sh"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 AI Gateway Hub Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -0,0 +1,53 @@
+.PHONY: up down restart logs build clean setup dev
+
+# ── Production ────────────────────────────────────────────────────────────────
+up:
+	docker compose up -d
+
+down:
+	docker compose down
+
+restart:
+	docker compose restart
+
+build:
+	docker compose build --no-cache
+
+logs:
+	docker compose logs -f
+
+logs-backend:
+	docker compose logs -f backend
+
+logs-litellm:
+	docker compose logs -f litellm
+
+status:
+	docker compose ps
+
+# ── Setup ─────────────────────────────────────────────────────────────────────
+setup:
+	chmod +x scripts/setup.sh && ./scripts/setup.sh
+
+env:
+	@if [ ! -f .env ]; then cp .env.example .env && echo ".env created"; else echo ".env already exists"; fi
+
+# ── Development ───────────────────────────────────────────────────────────────
+dev-backend:
+	cd backend && npm run dev
+
+dev-frontend:
+	cd frontend && npm run dev
+
+dev-install:
+	cd backend && npm install
+	cd frontend && npm install
+
+# ── Cleanup ───────────────────────────────────────────────────────────────────
+clean:
+	docker compose down -v --remove-orphans
+	docker image prune -f
+
+clean-data:
+	docker compose down -v
+	@echo "All persistent data removed."

README.md

@@ -1,10 +1,87 @@
 ---
-title: LitellmGUI
-emoji: 📚
-colorFrom: blue
-colorTo: gray
+title: AI Gateway Hub
+emoji: 🚀
+colorFrom: green
+colorTo: blue
 sdk: docker
+app_port: 7860
 pinned: false
+license: mit
+short_description: Universal AI Gateway — any provider to OpenAI API
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🚀 AI Gateway Hub
+
+> **Universal AI API Gateway** — Register any AI provider (OpenAI, Anthropic, Ollama, Gemini, Groq, and 100+ more) and get a single OpenAI-compatible endpoint. Powered by [LiteLLM](https://litellm.ai).
+
+## ⚙️ Setup (Required Before First Use)
+
+This Space needs a few secrets set before it will work correctly.
+
+Go to **Space Settings → Repository secrets** and add:
+
+| Secret | Required | Description |
+|---|---|---|
+| `LITELLM_MASTER_KEY` | ✅ Yes | Admin key for the LiteLLM proxy. Use a strong random string, e.g. `sk-gateway-xxxxxxxx` |
+| `JWT_SECRET` | ✅ Yes | Secret for backend session tokens. Any long random string |
+| `GATEWAY_PUBLIC_URL` | ✅ Yes | The public URL of this Space: `https://<your-username>-<space-name>.hf.space` |
+| `OPENAI_API_KEY` | Optional | Required only if you register OpenAI models |
+| `ANTHROPIC_API_KEY` | Optional | Required only if you register Anthropic models |
+| `GROQ_API_KEY` | Optional | Required only if you register Groq models |
+| `GEMINI_API_KEY` | Optional | Required only if you register Google Gemini models |
+
+> **Tip:** `GATEWAY_PUBLIC_URL` is set automatically on the **first** deploy by the GitHub Actions workflow and is never overwritten afterward, so you can safely customise it to a custom domain later.
+
+> **Tip:** Any provider API key you register through the UI is stored encrypted in the Space's SQLite database and never exposed to callers of the gateway.
+
+## 🚀 Quick Start
+
+1. After setting secrets above, wait for the Space to restart (it rebuilds automatically)
+2. Open the Space — you'll see the **AI Gateway Hub** dashboard
+3. Click **Add Model** and fill in your provider details
+4. Use the generated `model name` with any OpenAI SDK:
+
+```python
+from openai import OpenAI
+
+client = OpenAI(
+    base_url="https://<your-username>-<space-name>.hf.space/v1",
+    api_key="any-string",   # callers don't need the real provider key
+)
+
+response = client.chat.completions.create(
+    model="anthropic/claude-3-5-sonnet-20241022",  # alias shown in the UI
+    messages=[{"role": "user", "content": "Hello!"}],
+)
+print(response.choices[0].message.content)
+```
+
+## 📡 API Endpoints
+
+| Path | Description |
+|---|---|
+| `GET  /` | Web dashboard |
+| `POST /v1/chat/completions` | OpenAI-compatible chat (streaming supported) |
+| `POST /v1/embeddings` | Text embeddings |
+| `GET  /v1/models` | List registered models |
+| `GET  /api/models` | Management API — list models |
+| `POST /api/models` | Management API — register model |
+| `GET  /api/health` | Health check |
+
+## 📦 Supported Providers
+
+OpenAI · Anthropic · Google Gemini · Ollama · Groq · Mistral · Cohere · Together AI · AWS Bedrock · Azure OpenAI · HuggingFace · DeepSeek · Perplexity · Replicate · any OpenAI-compatible endpoint
+
+Full list: [docs.litellm.ai/docs/providers](https://docs.litellm.ai/docs/providers)
+
+## ⚠️ Important Notes
+
+- **Persistence:** The SQLite database (`/app/data/gateway.db`) storing your registered models is **ephemeral** on the free CPU Basic hardware tier — it resets on Space restart. To persist data, upgrade to a paid hardware tier or use an external database.
+- **Rate limits:** The free HF Spaces tier has CPU/memory limits. For production use, consider duplicating this Space with upgraded hardware.
+- **Security:** This Space is public by default. Anyone can call your `/v1/*` endpoints. For private use, set the Space visibility to **Private** in Space Settings.
+
+## 🔗 Source
+
+This Space is automatically deployed from the [AI Gateway Hub GitHub repository](https://github.com/your-org/ai-gateway-hub).
+
+> Replace `your-org/ai-gateway-hub` above with your actual repository URL.

backend/Dockerfile

@@ -0,0 +1,18 @@
+FROM node:20-alpine AS base
+WORKDIR /app
+
+# Install build dependencies for better-sqlite3
+RUN apk add --no-cache python3 make g++ curl
+
+COPY package*.json ./
+RUN npm ci --only=production
+
+COPY src/ ./src/
+
+RUN mkdir -p /app/data
+
+EXPOSE 3001
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s \
+  CMD curl -f http://localhost:3001/api/health || exit 1
+
+CMD ["node", "src/index.js"]

backend/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "ai-gateway-backend",
+  "version": "1.0.0",
+  "description": "AI Gateway Hub — Backend API Server",
+  "main": "src/index.js",
+  "type": "commonjs",
+  "scripts": {
+    "start": "node src/index.js",
+    "dev": "nodemon src/index.js"
+  },
+  "dependencies": {
+    "axios": "^1.7.2",
+    "better-sqlite3": "^9.6.0",
+    "cors": "^2.8.5",
+    "express": "^4.19.2",
+    "express-rate-limit": "^7.3.1",
+    "helmet": "^7.1.0",
+    "morgan": "^1.10.0",
+    "nanoid": "^3.3.7",
+    "uuid": "^10.0.0",
+    "winston": "^3.13.0"
+  },
+  "devDependencies": {
+    "nodemon": "^3.1.4"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

backend/src/database.js

@@ -0,0 +1,242 @@
+"use strict";
+
+const Database = require("better-sqlite3");
+const path = require("path");
+const { logger } = require("./logger");
+
+const DB_PATH = process.env.DB_PATH || path.join(__dirname, "../data/gateway.db");
+
+let db;
+
+function getDb() {
+  if (!db) {
+    db = new Database(DB_PATH, { verbose: null });
+    db.pragma("journal_mode = WAL");
+    db.pragma("foreign_keys = ON");
+    migrate(db);
+    logger.info(`SQLite database opened at ${DB_PATH}`);
+  }
+  return db;
+}
+
+function migrate(db) {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS models (
+      id          TEXT PRIMARY KEY,
+      name        TEXT NOT NULL UNIQUE,
+      display_name TEXT NOT NULL,
+      provider    TEXT NOT NULL,
+      litellm_model TEXT NOT NULL,
+      api_base    TEXT,
+      api_key     TEXT,
+      description TEXT,
+      tags        TEXT DEFAULT '[]',
+      model_type  TEXT DEFAULT 'chat',
+      enabled     INTEGER DEFAULT 1,
+      litellm_id  TEXT,
+      created_at  TEXT DEFAULT (datetime('now')),
+      updated_at  TEXT DEFAULT (datetime('now'))
+    );
+
+    CREATE TABLE IF NOT EXISTS usage_logs (
+      id           INTEGER PRIMARY KEY AUTOINCREMENT,
+      model_id     TEXT REFERENCES models(id),
+      model_name   TEXT NOT NULL,
+      request_type TEXT NOT NULL,
+      status       INTEGER NOT NULL,
+      latency_ms   INTEGER,
+      tokens_in    INTEGER,
+      tokens_out   INTEGER,
+      created_at   TEXT DEFAULT (datetime('now'))
+    );
+
+    CREATE TABLE IF NOT EXISTS settings (
+      key   TEXT PRIMARY KEY,
+      value TEXT NOT NULL
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_models_enabled ON models(enabled);
+    CREATE INDEX IF NOT EXISTS idx_usage_model ON usage_logs(model_id);
+    CREATE INDEX IF NOT EXISTS idx_usage_created ON usage_logs(created_at);
+  `);
+
+  // Seed default settings
+  const upsertSetting = db.prepare(
+    `INSERT OR IGNORE INTO settings (key, value) VALUES (?, ?)`
+  );
+  upsertSetting.run("gateway_version", "1.0.0");
+  upsertSetting.run("require_auth", "false");
+}
+
+// ─── Field mapping ─────────────────────────────────────────────────────────
+//
+// BUG FIX #5: Replace the fragile inline ternary chain with a single
+// declarative map.  Every camelCase JS key maps to its snake_case SQL column.
+// Adding a new field only requires one entry here — not edits spread across
+// multiple places.
+//
+// Convention: if a JS key IS the same as its SQL column, it can be omitted
+// (the fallback at the end of jsToCol() handles it), but explicit entries are
+// preferred for clarity.
+//
+const JS_TO_COL = {
+  displayName: "display_name",
+  litellmModel: "litellm_model",
+  apiBase: "api_base",
+  apiKey: "api_key",
+  modelType: "model_type",
+  litellmId: "litellm_id",
+  // Fields whose JS name == SQL column (listed for documentation purposes)
+  id: "id",
+  name: "name",
+  provider: "provider",
+  description: "description",
+  tags: "tags",
+  enabled: "enabled",
+};
+
+function jsToCol(key) {
+  return JS_TO_COL[key] || key;
+}
+
+// ─── Model CRUD ────────────────────────────────────────────────────────────
+
+function listModels({ enabledOnly = false } = {}) {
+  const db = getDb();
+  const where = enabledOnly ? "WHERE enabled = 1" : "";
+  const rows = db.prepare(`SELECT * FROM models ${where} ORDER BY created_at DESC`).all();
+  return rows.map(deserializeModel);
+}
+
+function getModel(id) {
+  const db = getDb();
+  const row = db.prepare("SELECT * FROM models WHERE id = ?").get(id);
+  return row ? deserializeModel(row) : null;
+}
+
+function getModelByName(name) {
+  const db = getDb();
+  const row = db.prepare("SELECT * FROM models WHERE name = ?").get(name);
+  return row ? deserializeModel(row) : null;
+}
+
+function createModel(model) {
+  const db = getDb();
+  const stmt = db.prepare(`
+    INSERT INTO models
+      (id, name, display_name, provider, litellm_model, api_base, api_key,
+       description, tags, model_type, enabled, litellm_id)
+    VALUES
+      (@id, @name, @display_name, @provider, @litellm_model, @api_base, @api_key,
+       @description, @tags, @model_type, @enabled, @litellm_id)
+  `);
+  stmt.run({ ...serializeModel(model) });
+  return getModel(model.id);
+}
+
+function updateModel(id, updates) {
+  const db = getDb();
+
+  const keys = Object.keys(updates).filter((k) => k !== "id");
+  if (keys.length === 0) return getModel(id);
+
+  // Normalize types for SQLite
+  const normalized = { ...updates };
+  if (typeof normalized.enabled === "boolean") {
+    normalized.enabled = normalized.enabled ? 1 : 0;
+  }
+  if (normalized.tags && Array.isArray(normalized.tags)) {
+    normalized.tags = JSON.stringify(normalized.tags);
+  }
+
+  // BUG FIX #5: Use the declarative JS_TO_COL map instead of an inline
+  // ternary chain.  Each SET clause: `sql_col = @jsKey` so that
+  // better-sqlite3's named binding (@jsKey) finds the value in `normalized`.
+  const fields = keys
+    .map((k) => `${jsToCol(k)} = @${k}`)
+    .join(", ");
+
+  db.prepare(
+    `UPDATE models SET ${fields}, updated_at = datetime('now') WHERE id = @id`
+  ).run({ id, ...normalized });
+
+  return getModel(id);
+}
+
+function deleteModel(id) {
+  const db = getDb();
+  db.prepare("DELETE FROM models WHERE id = ?").run(id);
+}
+
+function logUsage(entry) {
+  const db = getDb();
+  db.prepare(`
+    INSERT INTO usage_logs (model_id, model_name, request_type, status, latency_ms, tokens_in, tokens_out)
+    VALUES (@modelId, @modelName, @requestType, @status, @latencyMs, @tokensIn, @tokensOut)
+  `).run(entry);
+}
+
+function getStats() {
+  const db = getDb();
+  return {
+    totalModels: db.prepare("SELECT COUNT(*) as n FROM models").get().n,
+    enabledModels: db.prepare("SELECT COUNT(*) as n FROM models WHERE enabled = 1").get().n,
+    totalRequests: db.prepare("SELECT COUNT(*) as n FROM usage_logs").get().n,
+    successRequests: db.prepare("SELECT COUNT(*) as n FROM usage_logs WHERE status = 200").get().n,
+    avgLatency: db.prepare("SELECT AVG(latency_ms) as n FROM usage_logs WHERE status = 200").get().n || 0,
+  };
+}
+
+// ─── Serialization helpers ─────────────────────────────────────────────────
+
+function serializeModel(m) {
+  // IMPORTANT: raw key is stored as _apiKey in model records coming from routes,
+  // m.apiKey may be the masked "••••••••" string — never write that to the DB.
+  const rawKey = m._apiKey || (m.apiKey && m.apiKey !== "••••••••" ? m.apiKey : null) || m.api_key || null;
+  return {
+    id: m.id,
+    name: m.name,
+    display_name: m.displayName || m.display_name,
+    provider: m.provider,
+    litellm_model: m.litellmModel || m.litellm_model,
+    api_base: m.apiBase || m.api_base || null,
+    api_key: rawKey,
+    description: m.description || null,
+    tags: JSON.stringify(m.tags || []),
+    model_type: m.modelType || m.model_type || "chat",
+    enabled: m.enabled !== false ? 1 : 0,
+    litellm_id: m.litellmId || m.litellm_id || null,
+  };
+}
+
+function deserializeModel(row) {
+  return {
+    id: row.id,
+    name: row.name,
+    displayName: row.display_name,
+    provider: row.provider,
+    litellmModel: row.litellm_model,
+    apiBase: row.api_base,
+    apiKey: row.api_key ? "••••••••" : null, // mask key
+    _apiKey: row.api_key, // raw key for internal use
+    description: row.description,
+    tags: JSON.parse(row.tags || "[]"),
+    modelType: row.model_type,
+    enabled: row.enabled === 1,
+    litellmId: row.litellm_id,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  };
+}
+
+module.exports = {
+  getDb,
+  listModels,
+  getModel,
+  getModelByName,
+  createModel,
+  updateModel,
+  deleteModel,
+  logUsage,
+  getStats,
+};

backend/src/index.js

@@ -0,0 +1,132 @@
+"use strict";
+
+const express = require("express");
+const cors = require("cors");
+const helmet = require("helmet");
+const morgan = require("morgan");
+const rateLimit = require("express-rate-limit");
+
+const { logger } = require("./logger");
+const modelsRouter = require("./routes/models");
+const statsRouter = require("./routes/stats");
+const db = require("./database");
+const litellm = require("./litellm");
+
+const app = express();
+const PORT = parseInt(process.env.PORT || "3001", 10);
+
+// ─── Middleware ────────────────────────────────────────────────────────────
+
+app.use(helmet({ crossOriginResourcePolicy: false }));
+app.use(
+  cors({
+    origin: "*",
+    methods: ["GET", "POST", "PATCH", "PUT", "DELETE", "OPTIONS"],
+    allowedHeaders: ["Content-Type", "Authorization"],
+  })
+);
+app.use(express.json({ limit: "10mb" }));
+app.use(
+  morgan("combined", {
+    stream: { write: (msg) => logger.http(msg.trim()) },
+    skip: (req) => req.url === "/api/health",
+  })
+);
+
+// Rate limiting
+app.use(
+  "/api/",
+  rateLimit({
+    windowMs: 60 * 1000,
+    max: 200,
+    standardHeaders: true,
+    legacyHeaders: false,
+    message: { success: false, error: "Too many requests" },
+  })
+);
+
+// ─── Routes ───────────────────────────────────────────────────────────────
+
+// BUG FIX: The simple stub was removed. statsRouter's /health checks LiteLLM + DB health.
+app.use("/api/models", modelsRouter);
+app.use("/api", statsRouter);
+
+// 404
+app.use((req, res) => {
+  res.status(404).json({ success: false, error: "Not found" });
+});
+
+// Error handler
+app.use((err, req, res, _next) => {
+  logger.error("Unhandled error", { error: err.message, stack: err.stack });
+  res.status(500).json({ success: false, error: "Internal server error" });
+});
+
+// ─── Startup ──────────────────────────────────────────────────────────────
+
+async function start() {
+  // Initialize DB
+  db.getDb();
+  logger.info("Database initialized");
+
+  // BUG FIX: 5s hardcoded delay was unreliable — LiteLLM can take 30-60s to start.
+  // Use retry loop with backoff instead.
+  syncModelsToLitellmWithRetry();
+
+  app.listen(PORT, "0.0.0.0", () => {
+    logger.info(`AI Gateway Backend running on port ${PORT}`);
+    logger.info(`Gateway public URL: ${process.env.GATEWAY_PUBLIC_URL || "http://localhost"}`);
+  });
+}
+
+/**
+ * Retry wrapper: attempts sync with exponential backoff for up to ~5 minutes.
+ * Handles the case where LiteLLM container starts slower than the backend.
+ */
+async function syncModelsToLitellmWithRetry() {
+  const MAX_ATTEMPTS = 10;
+  const BASE_DELAY_MS = 5000;
+  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+    try {
+      await litellm.healthCheck();
+      await syncModelsToLitellm();
+      return;
+    } catch (err) {
+      const delay = Math.min(BASE_DELAY_MS * attempt, 30000);
+      logger.warn(`LiteLLM not ready (attempt ${attempt}/${MAX_ATTEMPTS}), retrying in ${delay}ms...`);
+      await new Promise((r) => setTimeout(r, delay));
+    }
+  }
+  logger.error("LiteLLM did not become ready after all retry attempts. Models not synced.");
+}
+
+/**
+ * On startup, re-register all persisted models with LiteLLM.
+ * This handles the case where LiteLLM was restarted and lost its in-memory state.
+ */
+async function syncModelsToLitellm() {
+  try {
+    const models = db.listModels({ enabledOnly: true });
+    logger.info(`Syncing ${models.length} models to LiteLLM...`);
+
+    for (const model of models) {
+      try {
+        // _apiKey is the raw (unmasked) API key set by deserializeModel
+        const litellmId = await litellm.registerModel({ ...model, _apiKey: model._apiKey });
+        db.updateModel(model.id, { litellmId });
+        logger.info(`Synced: ${model.name}`);
+      } catch (err) {
+        logger.warn(`Failed to sync model ${model.name}: ${err.message}`);
+      }
+    }
+
+    logger.info("Model sync complete");
+  } catch (err) {
+    logger.error("Model sync failed", { error: err.message });
+  }
+}
+
+start().catch((err) => {
+  logger.error("Fatal startup error", { error: err.message });
+  process.exit(1);
+});

backend/src/litellm.js

@@ -0,0 +1,250 @@
+“use strict”;
+
+/**
+
+- LiteLLM Proxy Management Client
+- Wraps LiteLLM’s admin API for dynamic model registration.
+  */
+
+const axios = require(“axios”);
+const { logger } = require(”./logger”);
+
+const LITELLM_BASE_URL = process.env.LITELLM_BASE_URL || “http://litellm:4000”;
+const LITELLM_MASTER_KEY = process.env.LITELLM_MASTER_KEY || “sk-gateway-master-key”;
+
+const client = axios.create({
+baseURL: LITELLM_BASE_URL,
+timeout: 15000,
+headers: {
+Authorization: `Bearer ${LITELLM_MASTER_KEY}`,
+“Content-Type”: “application/json”,
+},
+});
+
+// ─── Model Registration ────────────────────────────────────────────────────
+
+/**
+
+- Register a new model in LiteLLM at runtime.
+- @param {object} model  - Our internal model record
+- @returns {string}       - LiteLLM internal model ID
+  */
+  async function registerModel(model) {
+  const payload = {
+  model_name: model.name, // OpenAI-compatible alias exposed to callers
+  litellm_params: buildLitellmParams(model),
+  model_info: {
+  id: model.id,
+  description: model.description || “”,
+  model_type: model.modelType || “chat”,
+  },
+  };
+
+logger.info(“Registering model with LiteLLM”, { modelName: model.name });
+
+const response = await client.post(”/model/new”, payload);
+
+// ─── BUG FIX #7: Ghost model on missing LiteLLM ID ──────────────────────
+//
+// ORIGINAL CODE:
+//   const litellmId = response.data?.model_info?.id || response.data?.id || model.id;
+//
+// The final `|| model.id` fallback silently stored our own UUID as
+// `litellm_id` whenever LiteLLM returned a response without a recognisable
+// ID field. This created a “ghost model” scenario:
+//
+//   1. DB stored our own UUID as `litellm_id`.
+//   2. On delete, deregisterModel() sent that UUID to LiteLLM /model/delete.
+//   3. LiteLLM couldn’t find it → returned an error we silently swallowed.
+//   4. Model removed from our DB but remained live inside LiteLLM’s in-memory
+//      router — still accepting real API traffic indefinitely.
+//
+// FIX: Extract the ID from the two documented response paths. If neither
+// yields an ID, emit a structured WARN (visible in logs/alerts) then fall
+// back to model.id only as a last resort so the creation flow is not broken.
+// The warning makes the deregistration risk explicit to operators.
+//
+// LiteLLM /model/new documented response shapes:
+//   v1.x+  → { model_info: { id: “<uuid>”, … }, model_name: “…” }
+//   older  → { id: “<uuid>”, … }
+// ─────────────────────────────────────────────────────────────────────────
+const litellmId =
+response.data?.model_info?.id ||
+response.data?.id ||
+null;
+
+if (!litellmId) {
+logger.warn(
+“[BUG#7] LiteLLM /model/new response contained no recognisable model ID. “ +
+“Falling back to internal UUID as litellm_id. “ +
+“Subsequent deregisterModel() calls for this model will likely fail silently, “ +
+“leaving a ghost model active inside LiteLLM. “ +
+“Inspect responseData below and verify your LiteLLM version.”,
+{
+modelName: model.name,
+internalId: model.id,
+responseTopLevelKeys: response.data ? Object.keys(response.data) : [],
+responseData: response.data,
+}
+);
+// Retain fallback so createModel() still returns a usable record.
+return model.id;
+}
+
+logger.info(“Model registered in LiteLLM”, { modelName: model.name, litellmId });
+return litellmId;
+}
+
+/**
+
+- Remove a model from LiteLLM.
+- 
+- @param {string} litellmId  - LiteLLM’s model ID (returned from registerModel)
+- 
+- ─── BUG FIX #6: /model/delete field-name version incompatibility ──────────
+- 
+- ORIGINAL CODE:
+- await client.post(”/model/delete”, { id: litellmId });
+- 
+- The request-body field name accepted by /model/delete has changed across
+- LiteLLM releases:
+- 
+- • Older versions (pre-v1.x):  { model_id: “<id>” }
+- • Current versions (v1.x+):   { id: “<id>” }
+- 
+- Sending only `id` against an older deployment produces a silent no-op:
+- LiteLLM returns HTTP 200 but ignores the request because it only reads
+- `model_id`. The same failure mode applies in reverse on newer versions.
+- 
+- FIX: Send BOTH fields in every request. LiteLLM’s Pydantic models use
+- `model_config = ConfigDict(extra="ignore")`, so unknown keys are silently
+- discarded — the payload is safe for all known versions.
+- 
+- If deletion silently fails after a future LiteLLM upgrade, verify the
+- current accepted field name via the running instance’s Swagger UI:
+- http://<litellm-host>:4000/docs  →  POST /model/delete
+- ─────────────────────────────────────────────────────────────────────────
+  */
+  async function deregisterModel(litellmId) {
+  if (!litellmId) return;
+  try {
+  await client.post(”/model/delete”, {
+  id: litellmId,       // accepted by LiteLLM v1.x+
+  model_id: litellmId, // accepted by LiteLLM pre-v1.x
+  });
+  logger.info(“Model deregistered from LiteLLM”, { litellmId });
+  } catch (err) {
+  // Model may not exist in LiteLLM (e.g. was never synced, or litellmId
+  // is our own UUID fallback from Bug Fix #7).  Log at warn so the operator
+  // is aware but the delete flow is not blocked.
+  logger.warn(“Could not deregister model from LiteLLM”, {
+  litellmId,
+  httpStatus: err.response?.status,
+  error: err.message,
+  });
+  }
+  }
+
+/**
+
+- List all models currently registered in LiteLLM.
+  */
+  async function listLitellmModels() {
+  const response = await client.get(”/model/info”);
+  return response.data?.data || response.data || [];
+  }
+
+/**
+
+- Update a model in LiteLLM (delete + re-add since update isn’t atomic).
+  */
+  async function updateModel(oldLitellmId, model) {
+  await deregisterModel(oldLitellmId);
+  return registerModel(model);
+  }
+
+/**
+
+- Check LiteLLM liveness.
+- 
+- Uses /health/liveliness instead of /health:
+- - /health validates all registered model upstreams. If any upstream is
+- unreachable it returns an error even though LiteLLM itself is healthy,
+- causing syncModelsToLitellmWithRetry() to retry endlessly and give up.
+- - /health/liveliness only checks that the LiteLLM process is alive, which
+- is the correct signal for “ready to accept /model/new requests”.
+- This also matches the docker-compose.yml container healthcheck target.
+  */
+  async function healthCheck() {
+  const response = await client.get(”/health/liveliness”);
+  return response.data;
+  }
+
+/**
+
+- Test a model by sending a minimal chat completion request.
+  */
+  async function testModel(modelName, options = {}) {
+  const start = Date.now();
+  const messages =
+  options.messages && options.messages.length > 0
+  ? options.messages
+  : [{ role: “user”, content: options.prompt || “Say ‘OK’ in one word.” }];
+  try {
+  const response = await client.post(
+  “/v1/chat/completions”,
+  {
+  model: modelName,
+  messages,
+  max_tokens: 256,
+  stream: false,
+  },
+  { timeout: 30000 }
+  );
+  return {
+  success: true,
+  latencyMs: Date.now() - start,
+  response: response.data,
+  };
+  } catch (err) {
+  return {
+  success: false,
+  latencyMs: Date.now() - start,
+  error: err.response?.data || err.message,
+  };
+  }
+  }
+
+// ─── Helpers ──────────────────────────────────────────────────────────────
+
+function buildLitellmParams(model) {
+const params = {
+model: model.litellmModel,
+};
+
+// Note: original code also checked `model._apiBase` which is never set
+// anywhere in the codebase — that dead reference has been removed.
+if (model.apiBase) {
+params.api_base = model.apiBase;
+}
+
+// Only include api_key if provided and non-empty
+const key = model._apiKey || model.apiKey;
+if (key && key !== “••••••••” && key.trim() !== “”) {
+params.api_key = key.trim();
+} else {
+// LiteLLM requires some api_key for most providers; use placeholder
+params.api_key = “none”;
+}
+
+return params;
+}
+
+module.exports = {
+registerModel,
+deregisterModel,
+listLitellmModels,
+updateModel,
+healthCheck,
+testModel,
+};

backend/src/logger.js

@@ -0,0 +1,26 @@
+"use strict";
+
+const winston = require("winston");
+
+const logger = winston.createLogger({
+  // BUG FIX: "info" level (2) drops Morgan HTTP logs (level 3). Default to "http".
+  level: process.env.LOG_LEVEL || "http",
+  format: winston.format.combine(
+    winston.format.timestamp(),
+    winston.format.errors({ stack: true }),
+    winston.format.json()
+  ),
+  transports: [
+    new winston.transports.Console({
+      format: winston.format.combine(
+        winston.format.colorize(),
+        winston.format.printf(({ level, message, timestamp, ...meta }) => {
+          const extras = Object.keys(meta).length ? ` ${JSON.stringify(meta)}` : "";
+          return `${timestamp} [${level}] ${message}${extras}`;
+        })
+      ),
+    }),
+  ],
+});
+
+module.exports = { logger };

backend/src/routes/models.js

@@ -0,0 +1,283 @@
+"use strict";
+
+const express = require("express");
+const { v4: uuidv4 } = require("uuid");
+const router = express.Router();
+
+const db = require("../database");
+const litellm = require("../litellm");
+const { logger } = require("../logger");
+
+const GATEWAY_PUBLIC_URL =
+  (process.env.GATEWAY_PUBLIC_URL || "http://localhost").replace(/\/$/, "");
+
+// ─── Helpers ──────────────────────────────────────────────────────────────
+
+/**
+ * Build the OpenAI-compatible model alias (the `model` field callers use).
+ *
+ * BUG NOTE #9: Aliases may contain forward slashes (e.g.
+ * "anthropic/claude-3-5-sonnet-20241022"). This is intentional and safe for
+ * our management API because all model lookups use the UUID `id`, not the
+ * `name` slug, as the :id URL parameter. Avoid adding routes that look up
+ * models by name via URL params — the slash would be mis-parsed by Express.
+ */
+function buildModelAlias(provider, litellmModel) {
+  const base = litellmModel.startsWith(`${provider}/`) ? litellmModel : `${provider}/${litellmModel}`;
+  const slug = base
+    .toLowerCase()
+    .replace(/[^a-z0-9\-_./]/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+  return slug;
+}
+
+function modelResponse(model) {
+  return {
+    ...model,
+    openaiEndpoint: `${GATEWAY_PUBLIC_URL}/v1`,
+    openaiModelName: model.name,
+    curlExample: buildCurlExample(model.name),
+    pythonExample: buildPythonExample(model.name),
+  };
+}
+
+function buildCurlExample(modelName) {
+  return `curl ${GATEWAY_PUBLIC_URL}/v1/chat/completions \\
+  -H "Content-Type: application/json" \\
+  -H "Authorization: Bearer any-key" \\
+  -d '{
+    "model": "${modelName}",
+    "messages": [{"role": "user", "content": "Hello!"}]
+  }'`;
+}
+
+function buildPythonExample(modelName) {
+  return `from openai import OpenAI
+
+client = OpenAI(
+    base_url="${GATEWAY_PUBLIC_URL}/v1",
+    api_key="any-key",  # No real key needed
+)
+
+response = client.chat.completions.create(
+    model="${modelName}",
+    messages=[{"role": "user", "content": "Hello!"}],
+)
+print(response.choices[0].message.content)`;
+}
+
+// ─── Routes ───────────────────────────────────────────────────────────────
+
+/**
+ * GET /api/models
+ */
+router.get("/", (req, res) => {
+  try {
+    const models = db.listModels();
+    res.json({ success: true, data: models.map(modelResponse), count: models.length });
+  } catch (err) {
+    logger.error("Failed to list models", { error: err.message });
+    res.status(500).json({ success: false, error: "Failed to fetch models" });
+  }
+});
+
+/**
+ * GET /api/models/:id
+ */
+router.get("/:id", (req, res) => {
+  try {
+    const model = db.getModel(req.params.id);
+    if (!model) return res.status(404).json({ success: false, error: "Model not found" });
+    res.json({ success: true, data: modelResponse(model) });
+  } catch (err) {
+    res.status(500).json({ success: false, error: err.message });
+  }
+});
+
+/**
+ * POST /api/models
+ * Register a new model.
+ */
+router.post("/", async (req, res) => {
+  const {
+    displayName,
+    provider,
+    litellmModel,
+    apiBase,
+    apiKey,
+    description,
+    tags = [],
+    modelType = "chat",
+  } = req.body;
+
+  if (!displayName || !provider || !litellmModel) {
+    return res.status(400).json({
+      success: false,
+      error: "displayName, provider, and litellmModel are required",
+    });
+  }
+
+  const id = uuidv4();
+  const name = buildModelAlias(provider, litellmModel);
+
+  if (db.getModelByName(name)) {
+    return res.status(409).json({
+      success: false,
+      error: `A model with alias "${name}" already exists. Use a different provider label or model.`,
+    });
+  }
+
+  const modelRecord = {
+    id,
+    name,
+    displayName,
+    provider,
+    litellmModel,
+    apiBase: apiBase || null,
+    apiKey: apiKey || null,
+    description: description || null,
+    tags,
+    modelType,
+    enabled: true,
+    litellmId: null,
+  };
+
+  try {
+    db.createModel(modelRecord);
+
+    try {
+      const litellmId = await litellm.registerModel({ ...modelRecord, _apiKey: modelRecord.apiKey });
+      db.updateModel(id, { litellmId });
+      modelRecord.litellmId = litellmId;
+    } catch (litellmErr) {
+      logger.warn("Could not register model with LiteLLM (will retry on next request)", {
+        modelName: name,
+        error: litellmErr.message,
+      });
+    }
+
+    const created = db.getModel(id);
+    logger.info("Model created", { id, name });
+    res.status(201).json({ success: true, data: modelResponse(created) });
+  } catch (err) {
+    logger.error("Failed to create model", { error: err.message });
+    res.status(500).json({ success: false, error: "Failed to create model" });
+  }
+});
+
+/**
+ * PATCH /api/models/:id
+ * Update model metadata.
+ */
+router.patch("/:id", async (req, res) => {
+  try {
+    const existing = db.getModel(req.params.id);
+    if (!existing) return res.status(404).json({ success: false, error: "Model not found" });
+
+    const allowedFields = ["displayName", "description", "tags", "modelType", "enabled", "apiKey", "apiBase"];
+    const updates = {};
+    for (const field of allowedFields) {
+      if (req.body[field] !== undefined) {
+        updates[field] = req.body[field];
+      }
+    }
+
+    db.updateModel(req.params.id, updates);
+
+    // Re-sync with LiteLLM if key/endpoint changed
+    if (updates.apiKey !== undefined || updates.apiBase !== undefined) {
+      try {
+        const updated = db.getModel(req.params.id);
+
+        // BUG FIX #8: Was `updates.apiKey || existing._apiKey` which treated
+        // apiKey="" (intentional clear) as falsy and fell back to the old key,
+        // so LiteLLM would still use the stale key even though DB was cleared.
+        // Now: if apiKey was explicitly sent (even as ""), honour it; only fall
+        // back to the existing key when apiKey was NOT part of this PATCH.
+        const rawKey = updates.apiKey !== undefined
+          ? (updates.apiKey || null)   // "" → null (clear the key in LiteLLM)
+          : existing._apiKey;
+
+        const newLitellmId = await litellm.updateModel(existing.litellmId, {
+          ...updated,
+          _apiKey: rawKey,
+        });
+        db.updateModel(req.params.id, { litellmId: newLitellmId });
+      } catch (litellmErr) {
+        logger.warn("LiteLLM re-sync failed", { error: litellmErr.message });
+      }
+    }
+
+    const updated = db.getModel(req.params.id);
+    res.json({ success: true, data: modelResponse(updated) });
+  } catch (err) {
+    res.status(500).json({ success: false, error: err.message });
+  }
+});
+
+/**
+ * DELETE /api/models/:id
+ */
+router.delete("/:id", async (req, res) => {
+  try {
+    const model = db.getModel(req.params.id);
+    if (!model) return res.status(404).json({ success: false, error: "Model not found" });
+
+    if (model.litellmId) {
+      await litellm.deregisterModel(model.litellmId);
+    }
+
+    db.deleteModel(req.params.id);
+    logger.info("Model deleted", { id: req.params.id, name: model.name });
+    res.json({ success: true, message: "Model deleted successfully" });
+  } catch (err) {
+    res.status(500).json({ success: false, error: err.message });
+  }
+});
+
+/**
+ * POST /api/models/:id/test
+ */
+router.post("/:id/test", async (req, res) => {
+  try {
+    const model = db.getModel(req.params.id);
+    if (!model) return res.status(404).json({ success: false, error: "Model not found" });
+
+    const result = await litellm.testModel(model.name, {
+      prompt: req.body.prompt,
+      messages: req.body.messages,
+    });
+
+    db.logUsage({
+      modelId: model.id,
+      modelName: model.name,
+      requestType: "test",
+      status: result.success ? 200 : 500,
+      latencyMs: result.latencyMs,
+      tokensIn: result.response?.usage?.prompt_tokens || 0,
+      tokensOut: result.response?.usage?.completion_tokens || 0,
+    });
+
+    res.json({ success: true, data: result });
+  } catch (err) {
+    res.status(500).json({ success: false, error: err.message });
+  }
+});
+
+/**
+ * POST /api/models/:id/toggle
+ */
+router.post("/:id/toggle", (req, res) => {
+  try {
+    const model = db.getModel(req.params.id);
+    if (!model) return res.status(404).json({ success: false, error: "Model not found" });
+    db.updateModel(req.params.id, { enabled: !model.enabled });
+    const updated = db.getModel(req.params.id);
+    res.json({ success: true, data: modelResponse(updated) });
+  } catch (err) {
+    res.status(500).json({ success: false, error: err.message });
+  }
+});
+
+module.exports = router;

backend/src/routes/stats.js

@@ -0,0 +1,237 @@
+"use strict";
+
+const express = require("express");
+const router = express.Router();
+const db = require("../database");
+const litellm = require("../litellm");
+const { logger } = require("../logger");
+
+/**
+ * GET /api/stats
+ * Dashboard statistics.
+ *
+ * BUG FIX #1: Was router.get("/") which only matched GET /api/ (the bare mount path).
+ * Frontend calls GET /api/stats — this route was never reached, always 404.
+ */
+router.get("/stats", (req, res) => {
+  try {
+    const stats = db.getStats();
+    res.json({ success: true, data: stats });
+  } catch (err) {
+    res.status(500).json({ success: false, error: err.message });
+  }
+});
+
+/**
+ * GET /api/health
+ * Service health check.
+ */
+router.get("/health", async (req, res) => {
+  const status = { api: "ok", litellm: "unknown", db: "unknown" };
+
+  // DB check
+  try {
+    db.getStats();
+    status.db = "ok";
+  } catch {
+    status.db = "error";
+  }
+
+  // LiteLLM check
+  try {
+    await litellm.healthCheck();
+    status.litellm = "ok";
+  } catch {
+    status.litellm = "degraded";
+  }
+
+  const allOk = Object.values(status).every((v) => v === "ok");
+  res.status(allOk ? 200 : 207).json({ success: true, data: status });
+});
+
+/**
+ * GET /api/providers
+ * Returns a curated list of known LiteLLM provider prefixes and example models
+ * to help users fill in the model registration form.
+ */
+router.get("/providers", (req, res) => {
+  res.json({
+    success: true,
+    data: KNOWN_PROVIDERS,
+  });
+});
+
+const KNOWN_PROVIDERS = [
+  {
+    id: "openai",
+    name: "OpenAI",
+    prefix: "openai/",
+    requiresApiKey: true,
+    defaultApiBase: "https://api.openai.com/v1",
+    exampleModels: ["openai/gpt-4o", "openai/gpt-4-turbo", "openai/gpt-3.5-turbo"],
+    modelTypes: ["chat", "embedding", "image", "audio"],
+    docs: "https://docs.litellm.ai/docs/providers/openai",
+  },
+  {
+    id: "anthropic",
+    name: "Anthropic",
+    prefix: "anthropic/",
+    requiresApiKey: true,
+    defaultApiBase: "https://api.anthropic.com",
+    exampleModels: [
+      "anthropic/claude-3-5-sonnet-20241022",
+      "anthropic/claude-3-opus-20240229",
+      "anthropic/claude-3-haiku-20240307",
+    ],
+    modelTypes: ["chat"],
+    docs: "https://docs.litellm.ai/docs/providers/anthropic",
+  },
+  {
+    id: "google",
+    name: "Google Gemini",
+    prefix: "gemini/",
+    requiresApiKey: true,
+    defaultApiBase: null,
+    exampleModels: ["gemini/gemini-1.5-pro", "gemini/gemini-1.5-flash", "gemini/gemini-pro"],
+    modelTypes: ["chat", "embedding"],
+    docs: "https://docs.litellm.ai/docs/providers/gemini",
+  },
+  {
+    id: "ollama",
+    name: "Ollama (Local)",
+    prefix: "ollama/",
+    requiresApiKey: false,
+    defaultApiBase: "http://host.docker.internal:11434",
+    exampleModels: ["ollama/llama3", "ollama/mistral", "ollama/codellama", "ollama/phi3"],
+    modelTypes: ["chat", "completion", "embedding"],
+    docs: "https://docs.litellm.ai/docs/providers/ollama",
+  },
+  {
+    id: "cohere",
+    name: "Cohere",
+    prefix: "cohere/",
+    requiresApiKey: true,
+    defaultApiBase: null,
+    exampleModels: ["cohere/command-r-plus", "cohere/command-r", "cohere/command"],
+    modelTypes: ["chat", "embedding"],
+    docs: "https://docs.litellm.ai/docs/providers/cohere_chat",
+  },
+  {
+    id: "mistral",
+    name: "Mistral AI",
+    prefix: "mistral/",
+    requiresApiKey: true,
+    defaultApiBase: null,
+    exampleModels: ["mistral/mistral-large-latest", "mistral/mistral-medium", "mistral/mistral-small"],
+    modelTypes: ["chat"],
+    docs: "https://docs.litellm.ai/docs/providers/mistral",
+  },
+  {
+    id: "groq",
+    name: "Groq",
+    prefix: "groq/",
+    requiresApiKey: true,
+    defaultApiBase: "https://api.groq.com/openai/v1",
+    exampleModels: ["groq/llama3-70b-8192", "groq/mixtral-8x7b-32768", "groq/gemma-7b-it"],
+    modelTypes: ["chat"],
+    docs: "https://docs.litellm.ai/docs/providers/groq",
+  },
+  {
+    id: "azure",
+    name: "Azure OpenAI",
+    prefix: "azure/",
+    requiresApiKey: true,
+    defaultApiBase: "https://<your-resource>.openai.azure.com",
+    exampleModels: ["azure/gpt-4o", "azure/gpt-35-turbo"],
+    modelTypes: ["chat", "embedding", "image"],
+    docs: "https://docs.litellm.ai/docs/providers/azure",
+  },
+  {
+    id: "vertex_ai",
+    name: "Google Vertex AI",
+    prefix: "vertex_ai/",
+    requiresApiKey: false,
+    defaultApiBase: null,
+    exampleModels: ["vertex_ai/gemini-1.5-pro", "vertex_ai/claude-3-5-sonnet@20241022"],
+    modelTypes: ["chat", "embedding"],
+    docs: "https://docs.litellm.ai/docs/providers/vertex",
+  },
+  {
+    id: "bedrock",
+    name: "AWS Bedrock",
+    prefix: "bedrock/",
+    requiresApiKey: false,
+    defaultApiBase: null,
+    exampleModels: [
+      "bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0",
+      "bedrock/amazon.titan-text-express-v1",
+    ],
+    modelTypes: ["chat", "embedding"],
+    docs: "https://docs.litellm.ai/docs/providers/bedrock",
+  },
+  {
+    id: "huggingface",
+    name: "HuggingFace",
+    prefix: "huggingface/",
+    requiresApiKey: true,
+    defaultApiBase: "https://api-inference.huggingface.co/models/<model>",
+    exampleModels: ["huggingface/HuggingFaceH4/zephyr-7b-beta"],
+    modelTypes: ["chat", "completion", "embedding"],
+    docs: "https://docs.litellm.ai/docs/providers/huggingface",
+  },
+  {
+    id: "openai_compatible",
+    name: "OpenAI-Compatible (Custom)",
+    prefix: "openai/",
+    requiresApiKey: false,
+    defaultApiBase: "https://your-custom-endpoint.example.com/v1",
+    exampleModels: ["openai/your-model-name"],
+    modelTypes: ["chat", "completion", "embedding"],
+    docs: "https://docs.litellm.ai/docs/providers/openai_compatible",
+  },
+  {
+    id: "together_ai",
+    name: "Together AI",
+    prefix: "together_ai/",
+    requiresApiKey: true,
+    defaultApiBase: null,
+    exampleModels: [
+      "together_ai/togethercomputer/llama-3-70b",
+      "together_ai/mistralai/Mixtral-8x7B-Instruct-v0.1",
+    ],
+    modelTypes: ["chat", "embedding"],
+    docs: "https://docs.litellm.ai/docs/providers/togetherai",
+  },
+  {
+    id: "replicate",
+    name: "Replicate",
+    prefix: "replicate/",
+    requiresApiKey: true,
+    defaultApiBase: null,
+    exampleModels: ["replicate/meta/llama-3-70b-instruct"],
+    modelTypes: ["chat", "image"],
+    docs: "https://docs.litellm.ai/docs/providers/replicate",
+  },
+  {
+    id: "deepseek",
+    name: "DeepSeek",
+    prefix: "deepseek/",
+    requiresApiKey: true,
+    defaultApiBase: "https://api.deepseek.com/v1",
+    exampleModels: ["deepseek/deepseek-chat", "deepseek/deepseek-coder"],
+    modelTypes: ["chat"],
+    docs: "https://docs.litellm.ai/docs/providers/deepseek",
+  },
+  {
+    id: "perplexity",
+    name: "Perplexity AI",
+    prefix: "perplexity/",
+    requiresApiKey: true,
+    defaultApiBase: "https://api.perplexity.ai",
+    exampleModels: ["perplexity/llama-3.1-sonar-large-128k-online"],
+    modelTypes: ["chat"],
+    docs: "https://docs.litellm.ai/docs/providers/perplexity",
+  },
+];
+
+module.exports = router;

docker-compose.yml

@@ -0,0 +1,117 @@
+version: "3.9"
+
+services:
+  # ─── LiteLLM Proxy Gateway ───────────────────────────────────────────────
+  litellm:
+    # BUG FIX #12: Was "main-latest" which points to the HEAD of the main branch
+    # and pulls in breaking changes on every `docker compose pull`. LiteLLM ships
+    # multiple commits per day; /model/delete field names, config.yaml keys, and
+    # routing behaviour have all changed between minor versions without notice.
+    #
+    # "main-stable" is the LiteLLM-maintained tag that always points to the
+    # latest release that has passed their 12-hour load-test suite. It is still
+    # a moving target, so for production deployments pin to a specific version:
+    #   ghcr.io/berriai/litellm:main-v1.81.14-stable
+    #
+    # To upgrade: review the release notes at https://docs.litellm.ai/release_notes
+    # then bump the version below and redeploy.
+    image: ghcr.io/berriai/litellm:main-v1.81.14-stable
+    container_name: ai_gateway_litellm
+    restart: unless-stopped
+    volumes:
+      - ./litellm/config.yaml:/app/config.yaml:ro
+      - litellm_data:/app/data
+    environment:
+      - LITELLM_MASTER_KEY=${LITELLM_MASTER_KEY:-sk-gateway-master-key}
+      # NOTE: STORE_MODEL_IN_DB requires PostgreSQL (not SQLite) in LiteLLM >= 1.x.
+      # We omit it here — our backend manages model persistence via SQLite and
+      # re-registers models with LiteLLM on startup via the /model/new API.
+      - PORT=4000
+    # NOTE: --detailed_debug flag is intentionally omitted.
+    # It dumps every internal processing step (including per-token details) to
+    # stdout, causing massive log volume and container slowdown in production.
+    # Use --debug only during active troubleshooting; omit it normally.
+    command: >
+      --config /app/config.yaml
+      --port 4000
+      --num_workers 4
+    healthcheck:
+      # LiteLLM image has no curl (GitHub issue #9295). Use wget + /health/liveliness.
+      test: ["CMD-SHELL", "wget --quiet --tries=1 -O /dev/null http://localhost:4000/health/liveliness || exit 1"]
+      interval: 30s
+      timeout: 10s
+      retries: 5
+      start_period: 60s
+    networks:
+      - gateway_net
+
+  # ─── Backend API ─────────────────────────────────────────────────────────
+  backend:
+    build:
+      context: ./backend
+      dockerfile: Dockerfile
+    container_name: ai_gateway_backend
+    restart: unless-stopped
+    environment:
+      - NODE_ENV=production
+      - PORT=3001
+      - LITELLM_BASE_URL=http://litellm:4000
+      - LITELLM_MASTER_KEY=${LITELLM_MASTER_KEY:-sk-gateway-master-key}
+      - DB_PATH=/app/data/gateway.db
+      - JWT_SECRET=${JWT_SECRET:-super-secret-jwt-key-change-in-production}
+      - GATEWAY_PUBLIC_URL=${GATEWAY_PUBLIC_URL:-http://localhost}
+    volumes:
+      - backend_data:/app/data
+    depends_on:
+      litellm:
+        condition: service_healthy
+    networks:
+      - gateway_net
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:3001/api/health"]
+      interval: 20s
+      timeout: 5s
+      retries: 3
+
+  # ─── Frontend ─────────────────────────────────────────────────────────────
+  frontend:
+    build:
+      context: ./frontend
+      dockerfile: Dockerfile
+      args:
+        - VITE_API_BASE=/api
+        - VITE_APP_NAME=AI Gateway Hub
+    container_name: ai_gateway_frontend
+    restart: unless-stopped
+    networks:
+      - gateway_net
+    depends_on:
+      - backend
+
+  # ─── Nginx Reverse Proxy ──────────────────────────────────────────────────
+  nginx:
+    image: nginx:1.25-alpine
+    container_name: ai_gateway_nginx
+    restart: unless-stopped
+    ports:
+      - "${HTTP_PORT:-80}:80"
+      # To enable HTTPS: add certs to nginx/ssl/ and uncomment below + add SSL server block to nginx.conf
+      # - "${HTTPS_PORT:-443}:443"
+    volumes:
+      - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
+      - nginx_logs:/var/log/nginx
+    depends_on:
+      - frontend
+      - backend
+      - litellm
+    networks:
+      - gateway_net
+
+volumes:
+  litellm_data:
+  backend_data:
+  nginx_logs:
+
+networks:
+  gateway_net:
+    driver: bridge

frontend/Dockerfile

@@ -0,0 +1,22 @@
+FROM node:20-alpine AS builder
+WORKDIR /app
+ 
+ARG VITE_API_BASE=/api
+ARG VITE_APP_NAME="AI Gateway Hub"
+
+ENV VITE_API_BASE=$VITE_API_BASE
+ENV VITE_APP_NAME=$VITE_APP_NAME
+
+COPY package*.json ./
+RUN npm ci
+
+COPY . .
+RUN npm run build
+
+# ── Production stage ──
+FROM nginx:1.25-alpine AS production
+COPY --from=builder /app/dist /usr/share/nginx/html
+COPY nginx.conf /etc/nginx/conf.d/default.conf
+
+EXPOSE 80
+CMD ["nginx", "-g", "daemon off;"]

frontend/index.html

@@ -0,0 +1,17 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>AI Gateway Hub</title>
+    <meta name="description" content="Universal AI API Gateway — Convert any AI provider to OpenAI-compatible endpoints via LiteLLM" />
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&family=IBM+Plex+Sans:wght@300;400;500;600&family=Space+Grotesk:wght@400;500;600;700&display=swap" rel="stylesheet" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.jsx"></script>
+  </body>
+</html>

frontend/nginx.conf

@@ -0,0 +1,109 @@
+user nginx;
+worker_processes auto;
+error_log /var/log/nginx/error.log warn;
+pid /var/run/nginx.pid;
+
+events {
+    worker_connections 4096;
+    # NOTE: removed "use epoll" — Linux-only, breaks on macOS Docker Desktop.
+    multi_accept on;
+}
+
+http {
+    include       /etc/nginx/mime.types;
+    default_type  application/octet-stream;
+
+    log_format main '$remote_addr - $remote_user [$time_local] "$request" '
+                    '$status $body_bytes_sent "$http_referer" '
+                    '"$http_user_agent" rt=$request_time';
+
+    access_log /var/log/nginx/access.log main;
+
+    sendfile        on;
+    tcp_nopush      on;
+    tcp_nodelay     on;
+    keepalive_timeout 65;
+    gzip on;
+    gzip_vary on;
+    gzip_proxied any;
+    gzip_comp_level 6;
+    gzip_types text/plain text/css text/xml application/json application/javascript
+               application/xml+rss application/atom+xml image/svg+xml;
+
+    # Rate limiting
+    limit_req_zone $binary_remote_addr zone=api:10m rate=100r/m;
+    limit_req_zone $binary_remote_addr zone=v1:10m rate=200r/m;
+
+    # Upstream definitions
+    upstream backend {
+        server backend:3001;
+        keepalive 32;
+    }
+
+    upstream litellm {
+        server litellm:4000;
+        keepalive 64;
+    }
+
+    upstream frontend {
+        server frontend:80;
+        keepalive 16;
+    }
+
+    server {
+        listen 80;
+        server_name _;
+
+        client_max_body_size 100M;
+        proxy_read_timeout 300s;
+        proxy_connect_timeout 10s;
+        proxy_send_timeout 300s;
+
+        # ── OpenAI-compatible AI API endpoints (via LiteLLM) ──────────────
+        location /v1/ {
+            limit_req zone=v1 burst=50 nodelay;
+
+            proxy_pass http://litellm;
+            proxy_http_version 1.1;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+            proxy_set_header Connection "";
+
+            # SSE / streaming support
+            proxy_buffering off;
+            proxy_cache off;
+            chunked_transfer_encoding on;
+            proxy_read_timeout 300s;
+        }
+
+        # ── Backend Management API ────────────────────────────────────────
+        location /api/ {
+            limit_req zone=api burst=20 nodelay;
+
+            proxy_pass http://backend;
+            proxy_http_version 1.1;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+            proxy_set_header Connection "";
+        }
+
+        # ── Frontend SPA ──────────────────────────────────────────────────
+        # BUG FIX #12: Removed Upgrade / Connection "upgrade" headers.
+        # The frontend is a static React SPA served by nginx — it does not use
+        # WebSockets. Sending Upgrade headers to a plain HTTP upstream is
+        # incorrect. Connection "" clears the hop-by-hop header and enables
+        # HTTP/1.1 keepalive to the upstream frontend container.
+        location / {
+            proxy_pass http://frontend;
+            proxy_http_version 1.1;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header Connection "";
+        }
+    }
+}

frontend/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "ai-gateway-frontend",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "lucide-react": "^0.383.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.3",
+    "@types/react-dom": "^18.3.0",
+    "@vitejs/plugin-react": "^4.3.1",
+    "autoprefixer": "^10.4.19",
+    "postcss": "^8.4.40",
+    "tailwindcss": "^3.4.7",
+    "vite": "^5.3.4"
+  }
+}

frontend/postcss.config.js

@@ -0,0 +1,6 @@
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+};

frontend/src/App.jsx

@@ -0,0 +1,127 @@
+import { useState, useEffect } from "react";
+import {
+  Cpu, LayoutGrid, FlaskConical, BookOpen,
+  Github, Activity, ChevronRight, Zap
+} from "lucide-react";
+import { api } from "./api";
+import ModelManager from "./components/ModelManager";
+import TestPanel from "./components/TestPanel";
+import DocsView from "./components/DocsView";
+import StatsBar from "./components/StatsBar";
+
+const NAV = [
+  { id: "models", label: "Models", icon: LayoutGrid },
+  { id: "test", label: "Test API", icon: FlaskConical },
+  { id: "docs", label: "Integration Docs", icon: BookOpen },
+];
+
+export default function App() {
+  const [tab, setTab] = useState("models");
+  const [stats, setStats] = useState(null);
+  const [health, setHealth] = useState(null);
+
+  useEffect(() => {
+    Promise.all([api.getStats(), api.getHealth()])
+      .then(([s, h]) => { setStats(s.data); setHealth(h.data); })
+      .catch(() => {});
+
+    const interval = setInterval(() => {
+      api.getStats().then(s => setStats(s.data)).catch(() => {});
+    }, 30000);
+    return () => clearInterval(interval);
+  }, []);
+
+  return (
+    <div className="min-h-screen bg-surface-0 flex flex-col">
+      {/* ── Header ─────────────────────────────────────────────────────── */}
+      <header className="glass sticky top-0 z-50 border-b border-white/5">
+        <div className="max-w-7xl mx-auto px-4 sm:px-6 h-14 flex items-center justify-between gap-4">
+          {/* Logo */}
+          <div className="flex items-center gap-3 flex-shrink-0">
+            <div className="w-8 h-8 rounded-lg bg-gradient-to-br from-accent-green to-accent-cyan
+                            flex items-center justify-center">
+              <Zap size={16} className="text-surface-0" />
+            </div>
+            <div className="flex items-center gap-1.5">
+              <span className="font-display font-semibold text-text-primary text-sm">
+                AI Gateway
+              </span>
+              <span className="font-display font-semibold text-accent-green text-sm">Hub</span>
+            </div>
+            <div className="hidden sm:flex items-center gap-1 text-text-muted">
+              <ChevronRight size={12} />
+              <span className="text-xs font-mono text-text-secondary">LiteLLM-powered</span>
+            </div>
+          </div>
+
+          {/* Nav */}
+          <nav className="flex items-center gap-1">
+            {NAV.map(({ id, label, icon: Icon }) => (
+              <button
+                key={id}
+                onClick={() => setTab(id)}
+                className={`flex items-center gap-1.5 px-3 py-1.5 rounded-md text-xs font-medium
+                            transition-all duration-150 ${
+                  tab === id
+                    ? "bg-accent-green/10 text-accent-green border border-accent-green/20"
+                    : "text-text-secondary hover:text-text-primary hover:bg-surface-2"
+                }`}
+              >
+                <Icon size={13} />
+                <span className="hidden sm:inline">{label}</span>
+              </button>
+            ))}
+          </nav>
+
+          {/* Status + GitHub */}
+          <div className="flex items-center gap-2 flex-shrink-0">
+            <StatusDot health={health} />
+            <a
+              href="https://github.com/your-org/ai-gateway-hub"
+              target="_blank"
+              rel="noreferrer"
+              className="text-text-muted hover:text-text-primary transition-colors"
+            >
+              <Github size={16} />
+            </a>
+          </div>
+        </div>
+      </header>
+
+      {/* ── Stats bar ──────────────────────────────────────────────────── */}
+      {stats && <StatsBar stats={stats} />}
+
+      {/* ── Main content ───────────────────────────────────────────────── */}
+      <main className="flex-1 max-w-7xl mx-auto w-full px-4 sm:px-6 py-6">
+        {tab === "models" && <ModelManager />}
+        {tab === "test"   && <TestPanel />}
+        {tab === "docs"   && <DocsView />}
+      </main>
+
+      {/* ── Footer ─────────────────────────────────────────────────────── */}
+      <footer className="border-t border-white/5 py-4 text-center">
+        <p className="text-text-muted text-xs font-mono">
+          AI Gateway Hub · Powered by{" "}
+          <a href="https://litellm.ai" target="_blank" rel="noreferrer"
+             className="text-accent-green hover:underline">LiteLLM</a>
+          {" "}· OpenAI-compatible proxy for any AI provider
+        </p>
+      </footer>
+    </div>
+  );
+}
+
+function StatusDot({ health }) {
+  if (!health) return null;
+  const allOk = Object.values(health).every(v => v === "ok");
+  return (
+    <div className="flex items-center gap-1.5 text-xs">
+      <div className={`w-1.5 h-1.5 rounded-full ${
+        allOk ? "bg-accent-green animate-pulse" : "bg-accent-orange"
+      }`} />
+      <span className="text-text-muted hidden sm:inline font-mono">
+        {allOk ? "online" : "degraded"}
+      </span>
+    </div>
+  );
+}

frontend/src/api.js

@@ -0,0 +1,32 @@
+const BASE = import.meta.env.VITE_API_BASE || "/api";
+
+async function request(method, path, body) {
+  const res = await fetch(`${BASE}${path}`, {
+    method,
+    headers: { "Content-Type": "application/json" },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  const data = await res.json();
+  if (!data.success) throw new Error(data.error || "Request failed");
+  return data;
+}
+
+export const api = {
+  // Models
+  listModels: () => request("GET", "/models"),
+  getModel: (id) => request("GET", `/models/${id}`),
+  createModel: (body) => request("POST", "/models", body),
+  updateModel: (id, body) => request("PATCH", `/models/${id}`, body),
+  deleteModel: (id) => request("DELETE", `/models/${id}`),
+  // BUG FIX: accepts messages array (full conversation) not just a string prompt
+  testModel: (id, messages) => request("POST", `/models/${id}/test`, {
+    messages: Array.isArray(messages) ? messages : undefined,
+    prompt: typeof messages === "string" ? messages : undefined,
+  }),
+  toggleModel: (id) => request("POST", `/models/${id}/toggle`),
+
+  // Stats & info
+  getStats: () => request("GET", "/stats"),
+  getHealth: () => request("GET", "/health"),
+  getProviders: () => request("GET", "/providers"),
+};

frontend/src/components/DocsView.jsx

@@ -0,0 +1,291 @@
+import { useState } from "react";
+import { Copy, Check, ExternalLink } from "lucide-react";
+
+export default function DocsView() {
+  const [copied, setCopied] = useState(null);
+  const [active, setActive] = useState("overview");
+  // BUG FIX #7: Removed unused `codeTab` / `setCodeTab` state that was
+  // declared but never referenced in JSX, creating dead React state on every
+  // render and confusing future developers.
+
+  const BASE = window.location.origin;
+
+  const copy = (text, key) => {
+    navigator.clipboard.writeText(text);
+    setCopied(key);
+    setTimeout(() => setCopied(null), 1500);
+  };
+
+  const sections = [
+    {
+      id: "overview",
+      title: "Overview",
+      content: (
+        <div className="space-y-3 text-text-secondary text-sm leading-relaxed">
+          <p>
+            AI Gateway Hub proxies any AI provider through a single{" "}
+            <span className="badge badge-green font-mono text-xs">OpenAI-compatible</span>{" "}
+            API endpoint. Add any model via the UI, then call it using the standard OpenAI SDK
+            from any language.
+          </p>
+          <div className="grid grid-cols-1 sm:grid-cols-3 gap-3 mt-4">
+            {[
+              { label: "Base URL", value: `${BASE}/v1`, badge: "green" },
+              { label: "Auth", value: "Any bearer token (passthrough)", badge: "cyan" },
+              { label: "Protocol", value: "OpenAI API v1", badge: "purple" },
+            ].map(({ label, value, badge }) => (
+              <div key={label} className="card p-3">
+                <div className={`badge badge-${badge} mb-2`}>{label}</div>
+                <p className="font-mono text-xs text-text-primary">{value}</p>
+              </div>
+            ))}
+          </div>
+        </div>
+      ),
+    },
+    {
+      id: "python",
+      title: "Python (openai SDK)",
+      lang: "python",
+      code: `from openai import OpenAI
+
+# Point the official OpenAI SDK at your gateway
+client = OpenAI(
+    base_url="${BASE}/v1",
+    api_key="any-string",   # No real key needed for keyless providers
+)
+
+# Chat completions
+response = client.chat.completions.create(
+    model="anthropic-claude-3-5-sonnet-20241022",  # Your registered alias
+    messages=[
+        {"role": "system", "content": "You are a helpful assistant."},
+        {"role": "user", "content": "Explain quantum entanglement simply."},
+    ],
+    temperature=0.7,
+)
+print(response.choices[0].message.content)
+
+# Streaming
+stream = client.chat.completions.create(
+    model="ollama-llama3",
+    messages=[{"role": "user", "content": "Write a haiku."}],
+    stream=True,
+)
+for chunk in stream:
+    print(chunk.choices[0].delta.content or "", end="", flush=True)
+
+# Embeddings
+embedding = client.embeddings.create(
+    model="openai-text-embedding-3-small",
+    input="Hello world",
+)
+print(embedding.data[0].embedding[:5])`,
+    },
+    {
+      id: "nodejs",
+      title: "Node.js / TypeScript",
+      lang: "javascript",
+      code: `import OpenAI from "openai";
+
+const client = new OpenAI({
+  baseURL: "${BASE}/v1",
+  apiKey: "any-string",
+});
+
+// Chat completions
+const response = await client.chat.completions.create({
+  model: "anthropic-claude-3-5-sonnet-20241022",
+  messages: [
+    { role: "system", content: "You are a helpful assistant." },
+    { role: "user",   content: "What is the capital of France?" },
+  ],
+});
+console.log(response.choices[0].message.content);
+
+// Streaming
+const stream = await client.chat.completions.create({
+  model: "ollama-llama3",
+  messages: [{ role: "user", content: "Count to 10." }],
+  stream: true,
+});
+for await (const chunk of stream) {
+  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
+}`,
+    },
+    {
+      id: "curl",
+      title: "cURL",
+      lang: "bash",
+      code: `# Chat completion
+curl ${BASE}/v1/chat/completions \\
+  -H "Content-Type: application/json" \\
+  -H "Authorization: Bearer any-key" \\
+  -d '{
+    "model": "anthropic-claude-3-5-sonnet-20241022",
+    "messages": [
+      {"role": "user", "content": "Hello, who are you?"}
+    ]
+  }'
+
+# List available models
+curl ${BASE}/v1/models \\
+  -H "Authorization: Bearer any-key"
+
+# Embeddings
+curl ${BASE}/v1/embeddings \\
+  -H "Content-Type: application/json" \\
+  -H "Authorization: Bearer any-key" \\
+  -d '{
+    "model": "openai-text-embedding-3-small",
+    "input": "The food was delicious."
+  }'`,
+    },
+    {
+      id: "langchain",
+      title: "LangChain",
+      lang: "python",
+      code: `from langchain_openai import ChatOpenAI, OpenAIEmbeddings
+
+# Drop-in replacement — just change base_url
+llm = ChatOpenAI(
+    base_url="${BASE}/v1",
+    api_key="any-key",
+    model="anthropic-claude-3-5-sonnet-20241022",
+    temperature=0,
+)
+
+result = llm.invoke("What are the benefits of LangChain?")
+print(result.content)
+
+# Embeddings
+embeddings = OpenAIEmbeddings(
+    base_url="${BASE}/v1",
+    api_key="any-key",
+    model="openai-text-embedding-3-small",
+)
+vector = embeddings.embed_query("Hello world")`,
+    },
+    {
+      id: "litellm_sdk",
+      title: "LiteLLM SDK",
+      lang: "python",
+      code: `import litellm
+
+# Call via gateway
+response = litellm.completion(
+    model="openai/anthropic-claude-3-5-sonnet-20241022",
+    api_base="${BASE}/v1",
+    api_key="any-key",
+    messages=[{"role": "user", "content": "Hello!"}],
+)
+print(response.choices[0].message.content)`,
+    },
+    {
+      id: "endpoints",
+      title: "Supported Endpoints",
+      content: (
+        <div className="space-y-2">
+          {[
+            { method: "POST", path: "/v1/chat/completions",    desc: "Chat completions (streaming supported)" },
+            { method: "POST", path: "/v1/completions",         desc: "Text completions" },
+            { method: "POST", path: "/v1/embeddings",          desc: "Text embeddings" },
+            { method: "POST", path: "/v1/images/generations",  desc: "Image generation (DALL-E / Stable Diffusion)" },
+            { method: "POST", path: "/v1/audio/speech",        desc: "Text-to-speech" },
+            { method: "POST", path: "/v1/audio/transcriptions",desc: "Speech-to-text (Whisper)" },
+            { method: "GET",  path: "/v1/models",              desc: "List all registered models" },
+          ].map(({ method, path, desc }) => (
+            <div key={path} className="flex items-center gap-3 text-sm py-2 border-b border-white/5 last:border-0">
+              <span className={`badge flex-shrink-0 ${
+                method === "GET" ? "badge-cyan" : "badge-green"
+              }`}>{method}</span>
+              <span className="font-mono text-text-primary text-xs flex-shrink-0">{path}</span>
+              <span className="text-text-muted text-xs">{desc}</span>
+            </div>
+          ))}
+        </div>
+      ),
+    },
+  ];
+
+  return (
+    <div className="animate-fade-in">
+      <div className="mb-6">
+        <h1 className="font-display text-xl font-semibold text-text-primary">Integration Docs</h1>
+        <p className="text-text-secondary text-sm mt-0.5">
+          Use any OpenAI-compatible client to connect to your registered models.
+        </p>
+      </div>
+
+      <div className="flex gap-6">
+        {/* Sidebar */}
+        <nav className="hidden lg:block w-44 flex-shrink-0 space-y-0.5">
+          {sections.map(s => (
+            <button
+              key={s.id}
+              onClick={() => setActive(s.id)}
+              className={`w-full text-left px-3 py-2 rounded text-xs font-medium transition-colors ${
+                active === s.id
+                  ? "bg-accent-green/10 text-accent-green"
+                  : "text-text-secondary hover:text-text-primary hover:bg-surface-2"
+              }`}
+            >
+              {s.title}
+            </button>
+          ))}
+          <div className="pt-3 border-t border-white/5 mt-3">
+            <a
+              href="https://docs.litellm.ai/docs/providers"
+              target="_blank" rel="noreferrer"
+              className="flex items-center gap-1.5 px-3 py-2 text-xs text-text-muted hover:text-accent-cyan"
+            >
+              <ExternalLink size={10} />
+              LiteLLM Providers
+            </a>
+          </div>
+        </nav>
+
+        {/* Content */}
+        <div className="flex-1 min-w-0 space-y-4">
+          {/* Mobile tab strip */}
+          <div className="lg:hidden flex gap-1 flex-wrap mb-4">
+            {sections.map(s => (
+              <button
+                key={s.id}
+                onClick={() => setActive(s.id)}
+                className={`badge cursor-pointer ${active === s.id ? "badge-green" : "badge-gray"}`}
+              >
+                {s.title}
+              </button>
+            ))}
+          </div>
+
+          {sections
+            .filter(s => s.id === active)
+            .map(s => (
+              <div key={s.id} className="card p-5 animate-slide-in">
+                <h2 className="font-display font-semibold text-text-primary mb-4">{s.title}</h2>
+                {s.content && s.content}
+                {s.code && (
+                  <div className="relative">
+                    <button
+                      onClick={() => copy(s.code, s.id)}
+                      className="absolute top-3 right-3 text-text-muted hover:text-text-primary transition-colors z-10"
+                    >
+                      {copied === s.id
+                        ? <Check size={13} className="text-accent-green" />
+                        : <Copy size={13} />
+                      }
+                    </button>
+                    <div className="code-block text-text-secondary text-[0.75rem] leading-relaxed">
+                      {s.code}
+                    </div>
+                  </div>
+                )}
+              </div>
+            ))}
+        </div>
+      </div>
+    </div>
+  );
+}

frontend/src/components/ModelCard.jsx

@@ -0,0 +1,217 @@
+import { useState } from "react";
+import {
+  Copy, Check, Pencil, Trash2, ToggleLeft, ToggleRight,
+  ChevronDown, ChevronUp, Terminal, Globe, Key
+} from "lucide-react";
+import { api } from "../api";
+
+const TYPE_BADGE = {
+  chat: "badge-green",
+  embedding: "badge-cyan",
+  image: "badge-purple",
+  audio: "badge-orange",
+  completion: "badge-gray",
+};
+
+export default function ModelCard({ model, onEdit, onDelete, onToggle }) {
+  const [copied, setCopied] = useState(null);
+  const [expanded, setExpanded] = useState(false);
+  const [testing, setTesting] = useState(false);
+  const [testResult, setTestResult] = useState(null);
+
+  const copy = (text, key) => {
+    navigator.clipboard.writeText(text);
+    setCopied(key);
+    setTimeout(() => setCopied(null), 1500);
+  };
+
+  const runTest = async () => {
+    setTesting(true);
+    setTestResult(null);
+    try {
+      const res = await api.testModel(model.id);
+      setTestResult(res.data);
+    } catch (e) {
+      setTestResult({ success: false, error: e.message });
+    } finally {
+      setTesting(false);
+    }
+  };
+
+  return (
+    <div className={`card flex flex-col animate-slide-in transition-all duration-200 ${
+      model.enabled ? "" : "opacity-50"
+    }`}>
+      {/* ── Card header ── */}
+      <div className="p-4 flex items-start justify-between gap-3">
+        <div className="min-w-0 flex-1">
+          <div className="flex items-center gap-2 flex-wrap">
+            <span className={`badge ${TYPE_BADGE[model.modelType] || "badge-gray"}`}>
+              {model.modelType || "chat"}
+            </span>
+            <span className="badge badge-gray">{model.provider}</span>
+            {!model.enabled && <span className="badge badge-gray">disabled</span>}
+          </div>
+          <h3 className="font-display font-semibold text-text-primary mt-2 text-sm leading-tight">
+            {model.displayName}
+          </h3>
+          {model.description && (
+            <p className="text-text-muted text-xs mt-1 leading-relaxed line-clamp-2">
+              {model.description}
+            </p>
+          )}
+        </div>
+        <div className="flex items-center gap-1 flex-shrink-0">
+          <button onClick={onToggle} title={model.enabled ? "Disable" : "Enable"}
+            className="p-1.5 rounded text-text-muted hover:text-text-primary transition-colors">
+            {model.enabled
+              ? <ToggleRight size={16} className="text-accent-green" />
+              : <ToggleLeft size={16} />
+            }
+          </button>
+          <button onClick={onEdit}
+            className="p-1.5 rounded text-text-muted hover:text-text-primary transition-colors">
+            <Pencil size={14} />
+          </button>
+          <button onClick={onDelete}
+            className="p-1.5 rounded text-text-muted hover:text-accent-red transition-colors">
+            <Trash2 size={14} />
+          </button>
+        </div>
+      </div>
+
+      <hr className="divider" />
+
+      {/* ── Endpoint info ── */}
+      <div className="p-4 space-y-2">
+        <InfoRow
+          icon={Globe}
+          label="Endpoint"
+          value={model.openaiEndpoint}
+          onCopy={() => copy(model.openaiEndpoint, "endpoint")}
+          copied={copied === "endpoint"}
+          mono
+        />
+        <InfoRow
+          icon={Terminal}
+          label="Model Name"
+          value={model.openaiModelName}
+          onCopy={() => copy(model.openaiModelName, "model")}
+          copied={copied === "model"}
+          mono
+          accent
+        />
+        {model.apiBase && (
+          <InfoRow
+            icon={Globe}
+            label="Source API"
+            value={model.apiBase}
+            mono
+          />
+        )}
+        <InfoRow
+          icon={Key}
+          label="API Key"
+          value={model.apiKey ? "Configured ✓" : "Not required / None"}
+          className={model.apiKey ? "text-accent-green" : "text-text-muted"}
+        />
+      </div>
+
+      {/* ── Expandable section ── */}
+      <div className="border-t border-white/5">
+        <button
+          onClick={() => setExpanded(e => !e)}
+          className="w-full px-4 py-2.5 flex items-center justify-between text-xs
+                     text-text-muted hover:text-text-secondary transition-colors"
+        >
+          <span>LiteLLM model: <span className="font-mono text-text-secondary">{model.litellmModel}</span></span>
+          {expanded ? <ChevronUp size={12} /> : <ChevronDown size={12} />}
+        </button>
+
+        {expanded && (
+          <div className="px-4 pb-4 space-y-3 animate-slide-in">
+            {/* Curl example */}
+            <div>
+              <div className="flex items-center justify-between mb-1.5">
+                <span className="text-xs text-text-muted font-mono">curl</span>
+                <button
+                  onClick={() => copy(model.curlExample, "curl")}
+                  className="text-text-muted hover:text-text-primary transition-colors"
+                >
+                  {copied === "curl" ? <Check size={12} className="text-accent-green" /> : <Copy size={12} />}
+                </button>
+              </div>
+              <div className="code-block text-text-secondary text-[0.7rem] leading-relaxed max-h-32 overflow-y-auto">
+                {model.curlExample}
+              </div>
+            </div>
+
+            {/* Test button */}
+            <div>
+              <button
+                onClick={runTest}
+                disabled={testing || !model.enabled}
+                className="btn-secondary w-full justify-center text-xs"
+              >
+                {testing ? (
+                  <><RefreshCwIcon className="animate-spin" size={12} /> Testing…</>
+                ) : "Run connectivity test"}
+              </button>
+
+              {testResult && (
+                <div className={`mt-2 p-2 rounded text-xs font-mono border ${
+                  testResult.success
+                    ? "bg-accent-green/5 border-accent-green/20 text-accent-green"
+                    : "bg-accent-red/5 border-accent-red/20 text-accent-red"
+                }`}>
+                  {testResult.success
+                    ? `✓ OK — ${testResult.latencyMs}ms`
+                    : `✗ ${JSON.stringify(testResult.error)?.slice(0, 120)}`
+                  }
+                </div>
+              )}
+            </div>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+function InfoRow({ icon: Icon, label, value, onCopy, copied, mono, accent, className }) {
+  return (
+    <div className="flex items-center gap-2 group">
+      <Icon size={11} className="text-text-muted flex-shrink-0" />
+      <span className="text-text-muted text-xs flex-shrink-0 w-20">{label}</span>
+      <span className={`text-xs flex-1 truncate ${
+        mono ? "font-mono" : ""
+      } ${accent ? "text-accent-cyan" : "text-text-secondary"} ${className || ""}`}>
+        {value}
+      </span>
+      {onCopy && (
+        <button
+          onClick={onCopy}
+          className="opacity-0 group-hover:opacity-100 transition-opacity text-text-muted hover:text-text-primary flex-shrink-0"
+        >
+          {copied
+            ? <Check size={11} className="text-accent-green" />
+            : <Copy size={11} />
+          }
+        </button>
+      )}
+    </div>
+  );
+}
+
+// Inline icon to avoid import issues
+function RefreshCwIcon({ size, className }) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 24 24" fill="none"
+         stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"
+         className={className}>
+      <polyline points="23 4 23 10 17 10" />
+      <polyline points="1 20 1 14 7 14" />
+      <path d="M3.51 9a9 9 0 0 1 14.85-3.36L23 10M1 14l4.64 4.36A9 9 0 0 0 20.49 15" />
+    </svg>
+  );
+}

frontend/src/components/ModelForm.jsx

@@ -0,0 +1,282 @@
+import { useState, useEffect } from "react";
+import { X, ExternalLink, Info, Eye, EyeOff } from "lucide-react";
+import { api } from "../api";
+
+const MODEL_TYPES = [
+  { value: "chat",       label: "Chat / Instruct" },
+  { value: "completion", label: "Text Completion" },
+  { value: "embedding",  label: "Embedding" },
+  { value: "image",      label: "Image Generation" },
+  { value: "audio",      label: "Audio / Speech" },
+];
+
+export default function ModelForm({ initial, onSave, onClose }) {
+  const isEdit = !!initial;
+
+  const [form, setForm] = useState({
+    displayName: initial?.displayName || "",
+    provider:    initial?.provider    || "",
+    litellmModel:initial?.litellmModel|| "",
+    apiBase:     initial?.apiBase     || "",
+    apiKey:      "",
+    description: initial?.description || "",
+    modelType:   initial?.modelType   || "chat",
+    tags:        initial?.tags?.join(", ") || "",
+  });
+
+  const [providers, setProviders] = useState([]);
+  const [saving, setSaving] = useState(false);
+  const [error, setError] = useState(null);
+  const [showKey, setShowKey] = useState(false);
+  const [selectedProvider, setSelectedProvider] = useState(null);
+
+  useEffect(() => {
+    api.getProviders().then(r => setProviders(r.data)).catch(() => {});
+  }, []);
+
+  const set = (k) => (e) => setForm(f => ({ ...f, [k]: e.target.value }));
+
+  const handleProviderSelect = (e) => {
+    const prov = providers.find(p => p.id === e.target.value);
+    setSelectedProvider(prov || null);
+    if (prov) {
+      setForm(f => ({
+        ...f,
+        provider: prov.id,
+        apiBase: prov.defaultApiBase || "",
+        litellmModel: prov.exampleModels?.[0] || "",
+        modelType: prov.modelTypes?.[0] || "chat",
+      }));
+    }
+  };
+
+  const handleSubmit = async () => {
+    if (!form.displayName.trim() || !form.provider.trim() || !form.litellmModel.trim()) {
+      setError("Display name, provider, and LiteLLM model are required.");
+      return;
+    }
+    setSaving(true);
+    setError(null);
+    try {
+      await onSave({
+        ...form,
+        tags: form.tags.split(",").map(t => t.trim()).filter(Boolean),
+        apiKey: form.apiKey || undefined,
+      });
+    } catch (e) {
+      setError(e.message);
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  return (
+    <div className="fixed inset-0 z-50 flex items-center justify-center p-4"
+         onClick={(e) => e.target === e.currentTarget && onClose()}>
+      {/* Backdrop */}
+      <div className="absolute inset-0 bg-black/70 backdrop-blur-sm" onClick={onClose} />
+
+      {/* Modal */}
+      <div className="relative w-full max-w-xl glass rounded-xl border border-white/10
+                      shadow-2xl shadow-black/50 animate-slide-in overflow-hidden">
+        {/* Header */}
+        <div className="flex items-center justify-between px-5 py-4 border-b border-white/5">
+          <div>
+            <h2 className="font-display font-semibold text-text-primary">
+              {isEdit ? "Edit Model" : "Register New Model"}
+            </h2>
+            <p className="text-text-muted text-xs mt-0.5">
+              {isEdit ? "Update model configuration." : "Add any AI model to the gateway."}
+            </p>
+          </div>
+          <button onClick={onClose} className="text-text-muted hover:text-text-primary transition-colors">
+            <X size={18} />
+          </button>
+        </div>
+
+        {/* Body */}
+        <div className="px-5 py-4 space-y-4 max-h-[70vh] overflow-y-auto">
+
+          {/* Provider quick-select */}
+          {!isEdit && providers.length > 0 && (
+            <div>
+              <label className="form-label">Quick-select provider</label>
+              <select className="select" onChange={handleProviderSelect} defaultValue="">
+                <option value="">— choose a provider to pre-fill —</option>
+                {providers.map(p => (
+                  <option key={p.id} value={p.id}>{p.name}</option>
+                ))}
+              </select>
+              {selectedProvider && (
+                <a
+                  href={selectedProvider.docs}
+                  target="_blank" rel="noreferrer"
+                  className="inline-flex items-center gap-1 text-accent-cyan text-xs mt-1.5 hover:underline"
+                >
+                  <ExternalLink size={10} />
+                  LiteLLM docs for {selectedProvider.name}
+                </a>
+              )}
+            </div>
+          )}
+
+          {/* Display name */}
+          <div>
+            <label className="form-label">Display Name <Required /></label>
+            <input
+              className="input"
+              placeholder="e.g. My Claude Proxy"
+              value={form.displayName}
+              onChange={set("displayName")}
+            />
+          </div>
+
+          {/* Provider */}
+          <div>
+            <label className="form-label">Provider ID <Required /></label>
+            <input
+              className="input"
+              placeholder="e.g. anthropic, openai, ollama"
+              value={form.provider}
+              onChange={set("provider")}
+            />
+            <p className="text-text-muted text-xs mt-1">
+              Used to build the OpenAI model alias: <span className="font-mono">provider/model</span>
+            </p>
+          </div>
+
+          {/* LiteLLM model name */}
+          <div>
+            <label className="form-label">
+              LiteLLM Model Name <Required />
+              <a
+                href="https://docs.litellm.ai/docs/providers"
+                target="_blank" rel="noreferrer"
+                className="ml-2 text-accent-cyan text-xs inline-flex items-center gap-0.5 hover:underline"
+              >
+                <ExternalLink size={9} /> LiteLLM docs
+              </a>
+            </label>
+            <input
+              className="input input-mono"
+              placeholder="e.g. anthropic/claude-3-5-sonnet-20241022"
+              value={form.litellmModel}
+              onChange={set("litellmModel")}
+            />
+            {selectedProvider?.exampleModels?.length > 0 && (
+              <div className="flex flex-wrap gap-1 mt-1.5">
+                {selectedProvider.exampleModels.map(m => (
+                  <button
+                    key={m}
+                    type="button"
+                    onClick={() => setForm(f => ({ ...f, litellmModel: m }))}
+                    className="badge badge-gray cursor-pointer hover:badge-green font-mono text-[0.65rem]"
+                  >
+                    {m}
+                  </button>
+                ))}
+              </div>
+            )}
+          </div>
+
+          {/* API Base */}
+          <div>
+            <label className="form-label">API Base URL <span className="text-text-muted">(optional)</span></label>
+            <input
+              className="input input-mono"
+              placeholder="e.g. https://api.anthropic.com  or  http://localhost:11434"
+              value={form.apiBase}
+              onChange={set("apiBase")}
+            />
+            <p className="text-text-muted text-xs mt-1">
+              Leave blank to use LiteLLM's default for this provider.
+            </p>
+          </div>
+
+          {/* API Key */}
+          <div>
+            <label className="form-label">
+              API Key <span className="text-text-muted">(optional)</span>
+            </label>
+            <div className="relative">
+              <input
+                className="input input-mono pr-9"
+                placeholder={isEdit ? "Leave blank to keep existing" : "sk-… (leave empty for keyless providers)"}
+                type={showKey ? "text" : "password"}
+                value={form.apiKey}
+                onChange={set("apiKey")}
+                autoComplete="new-password"
+              />
+              <button
+                type="button"
+                onClick={() => setShowKey(s => !s)}
+                className="absolute right-2.5 top-1/2 -translate-y-1/2 text-text-muted hover:text-text-primary"
+              >
+                {showKey ? <EyeOff size={14} /> : <Eye size={14} />}
+              </button>
+            </div>
+            <p className="text-text-muted text-xs mt-1 flex items-center gap-1">
+              <Info size={10} />
+              Keys are stored server-side and masked in the UI.
+              For Ollama and local models, no key is needed.
+            </p>
+          </div>
+
+          {/* Model type */}
+          <div>
+            <label className="form-label">Model Type</label>
+            <select className="select" value={form.modelType} onChange={set("modelType")}>
+              {MODEL_TYPES.map(t => (
+                <option key={t.value} value={t.value}>{t.label}</option>
+              ))}
+            </select>
+          </div>
+
+          {/* Description */}
+          <div>
+            <label className="form-label">Description <span className="text-text-muted">(optional)</span></label>
+            <textarea
+              className="input resize-none"
+              rows={2}
+              placeholder="Brief description of this model endpoint…"
+              value={form.description}
+              onChange={set("description")}
+            />
+          </div>
+
+          {/* Tags */}
+          <div>
+            <label className="form-label">Tags <span className="text-text-muted">(comma-separated)</span></label>
+            <input
+              className="input"
+              placeholder="e.g. production, fast, vision"
+              value={form.tags}
+              onChange={set("tags")}
+            />
+          </div>
+
+          {error && (
+            <div className="p-3 rounded-lg bg-accent-red/10 border border-accent-red/20 text-accent-red text-sm">
+              {error}
+            </div>
+          )}
+        </div>
+
+        {/* Footer */}
+        <div className="flex items-center justify-end gap-2 px-5 py-3.5 border-t border-white/5 bg-surface-1/30">
+          <button onClick={onClose} className="btn-secondary">Cancel</button>
+          <button onClick={handleSubmit} disabled={saving} className="btn-primary">
+            {saving ? "Saving…" : isEdit ? "Save Changes" : "Register Model"}
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function Required() {
+  return <span className="text-accent-red text-xs ml-0.5">*</span>;
+}
+// BUG FIX: Removed module-level document.createElement("style") — it ran on every
+// module evaluation and injected duplicate <style> tags on HMR reloads.
+// The .form-label class is now defined in index.css @layer components.

frontend/src/components/ModelManager.jsx

@@ -0,0 +1,166 @@
+import { useState, useEffect } from "react";
+import { Plus, RefreshCw } from "lucide-react";
+import { api } from "../api";
+import ModelCard from "./ModelCard";
+import ModelForm from "./ModelForm";
+
+export default function ModelManager() {
+  const [models, setModels] = useState([]);
+  const [loading, setLoading] = useState(true);
+  const [showForm, setShowForm] = useState(false);
+  const [editModel, setEditModel] = useState(null);
+  const [filter, setFilter] = useState("all");
+
+  const load = async () => {
+    setLoading(true);
+    try {
+      const res = await api.listModels();
+      setModels(res.data);
+    } catch (e) {
+      console.error(e);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  useEffect(() => { load(); }, []);
+
+  const handleDelete = async (id) => {
+    if (!confirm("Delete this model? It will be removed from the gateway.")) return;
+    await api.deleteModel(id);
+    setModels(m => m.filter(x => x.id !== id));
+  };
+
+  const handleToggle = async (id) => {
+    const res = await api.toggleModel(id);
+    setModels(m => m.map(x => x.id === id ? res.data : x));
+  };
+
+  const handleSave = async (data) => {
+    if (editModel) {
+      const res = await api.updateModel(editModel.id, data);
+      setModels(m => m.map(x => x.id === editModel.id ? res.data : x));
+    } else {
+      const res = await api.createModel(data);
+      setModels(m => [res.data, ...m]);
+    }
+    setShowForm(false);
+    setEditModel(null);
+  };
+
+  const TYPE_COLORS = {
+    chat: "green", embedding: "cyan", image: "purple",
+    audio: "orange", completion: "gray",
+  };
+
+  const filtered = filter === "all"
+    ? models
+    : models.filter(m => m.modelType === filter || (filter === "enabled" ? m.enabled : !m.enabled));
+
+  const types = [...new Set(models.map(m => m.modelType))].filter(Boolean);
+
+  return (
+    <div className="animate-fade-in">
+      {/* ── Header ── */}
+      <div className="flex items-center justify-between mb-6">
+        <div>
+          <h1 className="font-display text-xl font-semibold text-text-primary">
+            Model Registry
+          </h1>
+          <p className="text-text-secondary text-sm mt-0.5">
+            Register any AI model and get an OpenAI-compatible endpoint instantly.
+          </p>
+        </div>
+        <div className="flex items-center gap-2">
+          <button onClick={load} className="btn-secondary" title="Refresh">
+            <RefreshCw size={14} className={loading ? "animate-spin" : ""} />
+          </button>
+          <button onClick={() => { setEditModel(null); setShowForm(true); }} className="btn-primary">
+            <Plus size={14} />
+            Add Model
+          </button>
+        </div>
+      </div>
+
+      {/* ── Filters ── */}
+      {models.length > 0 && (
+        <div className="flex items-center gap-2 mb-4 flex-wrap">
+          {["all", "enabled", ...types].map(f => (
+            <button
+              key={f}
+              onClick={() => setFilter(f)}
+              className={`badge cursor-pointer transition-all ${
+                filter === f
+                  ? `badge-${TYPE_COLORS[f] || "green"}`
+                  : "badge-gray hover:border-surface-4"
+              }`}
+            >
+              {f}
+            </button>
+          ))}
+        </div>
+      )}
+
+      {/* ── Content ── */}
+      {loading ? (
+        <div className="grid grid-cols-1 md:grid-cols-2 xl:grid-cols-3 gap-4">
+          {[...Array(3)].map((_, i) => (
+            <div key={i} className="card p-5 animate-pulse">
+              <div className="h-4 bg-surface-3 rounded w-2/3 mb-3" />
+              <div className="h-3 bg-surface-3 rounded w-full mb-2" />
+              <div className="h-3 bg-surface-3 rounded w-3/4" />
+            </div>
+          ))}
+        </div>
+      ) : filtered.length === 0 ? (
+        <EmptyState onAdd={() => setShowForm(true)} hasModels={models.length > 0} />
+      ) : (
+        <div className="grid grid-cols-1 md:grid-cols-2 xl:grid-cols-3 gap-4">
+          {filtered.map(model => (
+            <ModelCard
+              key={model.id}
+              model={model}
+              onEdit={() => { setEditModel(model); setShowForm(true); }}
+              onDelete={() => handleDelete(model.id)}
+              onToggle={() => handleToggle(model.id)}
+            />
+          ))}
+        </div>
+      )}
+
+      {/* ── Form modal ── */}
+      {showForm && (
+        <ModelForm
+          initial={editModel}
+          onSave={handleSave}
+          onClose={() => { setShowForm(false); setEditModel(null); }}
+        />
+      )}
+    </div>
+  );
+}
+
+function EmptyState({ onAdd, hasModels }) {
+  return (
+    <div className="card p-12 text-center border-dashed">
+      <div className="w-14 h-14 rounded-2xl bg-accent-green/10 border border-accent-green/20
+                      flex items-center justify-center mx-auto mb-4">
+        <Plus size={24} className="text-accent-green" />
+      </div>
+      <h3 className="font-display font-semibold text-text-primary mb-1">
+        {hasModels ? "No models match this filter" : "No models registered yet"}
+      </h3>
+      <p className="text-text-secondary text-sm mb-5 max-w-sm mx-auto">
+        {hasModels
+          ? "Try a different filter to see your models."
+          : "Add your first model to start routing AI requests through an OpenAI-compatible endpoint."}
+      </p>
+      {!hasModels && (
+        <button onClick={onAdd} className="btn-primary mx-auto">
+          <Plus size={14} />
+          Add your first model
+        </button>
+      )}
+    </div>
+  );
+}

frontend/src/components/StatsBar.jsx

@@ -0,0 +1,30 @@
+import { Cpu, Activity, CheckCircle2, Clock } from "lucide-react";
+
+export default function StatsBar({ stats }) {
+  const items = [
+    { icon: Cpu, label: "Total Models", value: stats.totalModels },
+    { icon: CheckCircle2, label: "Active", value: stats.enabledModels, accent: "green" },
+    { icon: Activity, label: "Requests", value: stats.totalRequests },
+    {
+      icon: Clock,
+      label: "Avg Latency",
+      value: stats.avgLatency ? `${Math.round(stats.avgLatency)}ms` : "—",
+    },
+  ];
+
+  return (
+    <div className="border-b border-white/5 bg-surface-1/30">
+      <div className="max-w-7xl mx-auto px-4 sm:px-6 py-2 flex items-center gap-6 overflow-x-auto">
+        {items.map(({ icon: Icon, label, value, accent }) => (
+          <div key={label} className="flex items-center gap-2 flex-shrink-0">
+            <Icon size={12} className={accent === "green" ? "text-accent-green" : "text-text-muted"} />
+            <span className="text-text-muted text-xs">{label}:</span>
+            <span className={`text-xs font-mono font-medium ${
+              accent === "green" ? "text-accent-green" : "text-text-secondary"
+            }`}>{value}</span>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}

frontend/src/components/TestPanel.jsx

@@ -0,0 +1,288 @@
+import { useState, useEffect } from "react";
+import { Copy, Check, Zap } from "lucide-react";
+import { api } from "../api";
+
+export default function TestPanel() {
+  const [models, setModels] = useState([]);
+  const [selectedId, setSelectedId] = useState("");
+  const [messages, setMessages] = useState([
+    { role: "system", content: "You are a helpful assistant." },
+    { role: "user", content: "Hello! Tell me what model you are in one sentence." },
+  ]);
+  const [response, setResponse] = useState(null);
+  const [loading, setLoading] = useState(false);
+  const [copied, setCopied] = useState(null);
+
+  useEffect(() => {
+    api.listModels()
+      .then(r => {
+        const enabled = r.data.filter(m => m.enabled && m.modelType === "chat");
+        setModels(enabled);
+        if (enabled.length > 0) setSelectedId(enabled[0].id);
+      })
+      .catch(() => {});
+  }, []);
+
+  const selected = models.find(m => m.id === selectedId);
+
+  const addMessage = () => {
+    setMessages(m => [...m, { role: "user", content: "" }]);
+  };
+
+  const updateMessage = (i, field, value) => {
+    setMessages(m => m.map((msg, idx) => idx === i ? { ...msg, [field]: value } : msg));
+  };
+
+  const removeMessage = (i) => {
+    setMessages(m => m.filter((_, idx) => idx !== i));
+  };
+
+  const runTest = async () => {
+    const validMessages = messages.filter(m => m.content.trim());
+    if (!selected || !validMessages.length) return;
+    setLoading(true);
+    setResponse(null);
+    const start = Date.now();
+    try {
+      const res = await api.testModel(selectedId, validMessages);
+      setResponse({ ...res.data, _latency: Date.now() - start });
+    } catch (e) {
+      setResponse({ error: e.message, _latency: Date.now() - start });
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const copy = (text, key) => {
+    navigator.clipboard.writeText(text);
+    setCopied(key);
+    setTimeout(() => setCopied(null), 1500);
+  };
+
+  const curlCode = selected
+    ? `curl ${selected.openaiEndpoint}/chat/completions \\
+  -H "Content-Type: application/json" \\
+  -H "Authorization: Bearer any-key" \\
+  -d '${JSON.stringify({ model: selected.openaiModelName, messages: messages.filter(m => m.content.trim()) }, null, 2)}'`
+    : "";
+
+  const pythonCode = selected
+    ? `from openai import OpenAI
+
+client = OpenAI(
+    base_url="${selected.openaiEndpoint}",
+    api_key="any-key",
+)
+
+response = client.chat.completions.create(
+    model="${selected.openaiModelName}",
+    messages=${JSON.stringify(messages.filter(m => m.content.trim()), null, 4).replace(/^/gm, "    ").trim()},
+)
+print(response.choices[0].message.content)`
+    : "";
+
+  const jsCode = selected
+    ? `import OpenAI from "openai";
+
+const client = new OpenAI({
+  baseURL: "${selected.openaiEndpoint}",
+  apiKey: "any-key",
+  dangerouslyAllowBrowser: true,
+});
+
+const response = await client.chat.completions.create({
+  model: "${selected.openaiModelName}",
+  messages: ${JSON.stringify(messages.filter(m => m.content.trim()), null, 2)},
+});
+console.log(response.choices[0].message.content);`
+    : "";
+
+  const [codeTab, setCodeTab] = useState("curl");
+  const codeMap = { curl: curlCode, python: pythonCode, javascript: jsCode };
+
+  return (
+    <div className="animate-fade-in">
+      <div className="mb-6">
+        <h1 className="font-display text-xl font-semibold text-text-primary">API Tester</h1>
+        <p className="text-text-secondary text-sm mt-0.5">
+          Test your registered models with real requests.
+        </p>
+      </div>
+
+      <div className="grid grid-cols-1 xl:grid-cols-2 gap-6">
+        {/* ── Left: Request builder ── */}
+        <div className="space-y-4">
+          {/* Model select */}
+          <div className="card p-4">
+            <label className="text-xs font-medium text-text-secondary mb-2 block">
+              Select Model
+            </label>
+            {models.length === 0 ? (
+              <p className="text-text-muted text-sm">No chat models registered yet.</p>
+            ) : (
+              <select className="select" value={selectedId} onChange={e => setSelectedId(e.target.value)}>
+                {models.map(m => (
+                  <option key={m.id} value={m.id}>{m.displayName} — {m.openaiModelName}</option>
+                ))}
+              </select>
+            )}
+            {selected && (
+              <div className="mt-3 p-2.5 bg-surface-2 rounded-lg">
+                <div className="flex items-center gap-2 text-xs">
+                  <span className="text-text-muted">Endpoint:</span>
+                  <span className="font-mono text-accent-cyan flex-1 truncate">{selected.openaiEndpoint}</span>
+                  <button onClick={() => copy(selected.openaiEndpoint, "ep")}
+                    className="text-text-muted hover:text-text-primary">
+                    {copied === "ep" ? <Check size={11} className="text-accent-green" /> : <Copy size={11} />}
+                  </button>
+                </div>
+                <div className="flex items-center gap-2 text-xs mt-1">
+                  <span className="text-text-muted">Model:</span>
+                  <span className="font-mono text-accent-green flex-1 truncate">{selected.openaiModelName}</span>
+                  <button onClick={() => copy(selected.openaiModelName, "mn")}
+                    className="text-text-muted hover:text-text-primary">
+                    {copied === "mn" ? <Check size={11} className="text-accent-green" /> : <Copy size={11} />}
+                  </button>
+                </div>
+              </div>
+            )}
+          </div>
+
+          {/* Messages */}
+          <div className="card p-4 space-y-2">
+            <div className="flex items-center justify-between mb-1">
+              <label className="text-xs font-medium text-text-secondary">Messages</label>
+              <button onClick={addMessage} className="text-xs text-accent-green hover:underline">
+                + Add message
+              </button>
+            </div>
+            {messages.map((msg, i) => (
+              <div key={i} className="flex gap-2 items-start">
+                <select
+                  className="select w-24 flex-shrink-0 text-xs py-1.5"
+                  value={msg.role}
+                  onChange={e => updateMessage(i, "role", e.target.value)}
+                >
+                  <option value="system">system</option>
+                  <option value="user">user</option>
+                  <option value="assistant">assistant</option>
+                </select>
+                <textarea
+                  className="input flex-1 resize-none text-xs"
+                  rows={msg.role === "system" ? 1 : 2}
+                  value={msg.content}
+                  onChange={e => updateMessage(i, "content", e.target.value)}
+                  placeholder={`${msg.role} message…`}
+                />
+                {messages.length > 1 && (
+                  <button onClick={() => removeMessage(i)}
+                    className="text-text-muted hover:text-accent-red transition-colors mt-1.5">
+                    <span className="text-xs">✕</span>
+                  </button>
+                )}
+              </div>
+            ))}
+          </div>
+
+          <button
+            onClick={runTest}
+            disabled={loading || !selected}
+            className="btn-primary w-full justify-center"
+          >
+            <Zap size={14} />
+            {loading ? "Sending request…" : "Send Request"}
+          </button>
+        </div>
+
+        {/* ── Right: Response + Code ── */}
+        <div className="space-y-4">
+          {/* Response */}
+          <div className="card">
+            <div className="px-4 py-3 border-b border-white/5 flex items-center justify-between">
+              <span className="text-xs font-medium text-text-secondary">Response</span>
+              {response && (
+                <span className="text-xs font-mono text-text-muted">
+                  {response._latency}ms
+                </span>
+              )}
+            </div>
+            <div className="p-4 min-h-[160px]">
+              {loading && (
+                <div className="flex items-center gap-2 text-text-muted text-sm">
+                  <div className="w-2 h-2 bg-accent-green rounded-full animate-pulse" />
+                  Waiting for response…
+                </div>
+              )}
+              {!loading && !response && (
+                <p className="text-text-muted text-sm">Response will appear here.</p>
+              )}
+              {!loading && response && (
+                <>
+                  {response.error ? (
+                    <div className="text-accent-red text-sm font-mono whitespace-pre-wrap">
+                      {JSON.stringify(response.error, null, 2)}
+                    </div>
+                  ) : (
+                    <div className="space-y-3">
+                      <div className="p-3 bg-surface-2 rounded-lg">
+                        <p className="text-text-primary text-sm leading-relaxed whitespace-pre-wrap">
+                          {/* FIX: response state shape is { success, latencyMs, response: <LiteLLM data>, _latency }
+                               The actual LiteLLM chat completion object lives at response.response,
+                               not at the top level. Previously accessed response.choices which was
+                               always undefined, causing "No content in response" on every call. */}
+                          {response.response?.choices?.[0]?.message?.content || "No content in response"}
+                        </p>
+                      </div>
+                      {response.response?.usage && (
+                        <div className="flex gap-4 text-xs text-text-muted font-mono">
+                          <span>in: {response.response.usage.prompt_tokens}</span>
+                          <span>out: {response.response.usage.completion_tokens}</span>
+                          <span>total: {response.response.usage.total_tokens}</span>
+                          <span>model: {response.response.model}</span>
+                        </div>
+                      )}
+                    </div>
+                  )}
+                </>
+              )}
+            </div>
+          </div>
+
+          {/* Code examples */}
+          {selected && (
+            <div className="card">
+              <div className="px-4 py-3 border-b border-white/5 flex items-center gap-2">
+                {["curl", "python", "javascript"].map(t => (
+                  <button
+                    key={t}
+                    onClick={() => setCodeTab(t)}
+                    className={`text-xs px-2.5 py-1 rounded font-mono transition-colors ${
+                      codeTab === t
+                        ? "bg-accent-green/10 text-accent-green border border-accent-green/20"
+                        : "text-text-muted hover:text-text-secondary"
+                    }`}
+                  >
+                    {t}
+                  </button>
+                ))}
+                <div className="flex-1" />
+                <button
+                  onClick={() => copy(codeMap[codeTab], "code")}
+                  className="text-text-muted hover:text-text-primary transition-colors"
+                >
+                  {copied === "code"
+                    ? <Check size={13} className="text-accent-green" />
+                    : <Copy size={13} />
+                  }
+                </button>
+              </div>
+              <div className="code-block m-4 mt-3 text-text-secondary max-h-56 overflow-y-auto">
+                {codeMap[codeTab]}
+              </div>
+            </div>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}

frontend/src/index.css

@@ -0,0 +1,277 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+@layer base {
+  * {
+    box-sizing: border-box;
+  }
+
+  html {
+    scroll-behavior: smooth;
+  }
+
+  body {
+    background-color: #050709;
+    color: #e6edf3;
+    font-family: 'IBM Plex Sans', system-ui, sans-serif;
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+  }
+
+  ::-webkit-scrollbar {
+    width: 6px;
+    height: 6px;
+  }
+  ::-webkit-scrollbar-track {
+    background: #0d1117;
+  }
+  ::-webkit-scrollbar-thumb {
+    background: #30363d;
+    border-radius: 3px;
+  }
+  ::-webkit-scrollbar-thumb:hover {
+    background: #484f58;
+  }
+
+  ::selection {
+    background: rgba(0, 255, 135, 0.2);
+    color: #e6edf3;
+  }
+}
+
+@layer components {
+  .glass {
+    background: rgba(13, 17, 23, 0.8);
+    backdrop-filter: blur(12px);
+    border: 1px solid rgba(255, 255, 255, 0.06);
+  }
+
+  .glow-green {
+    box-shadow: 0 0 20px rgba(0, 255, 135, 0.15);
+  }
+
+  .glow-cyan {
+    box-shadow: 0 0 20px rgba(0, 212, 255, 0.15);
+  }
+
+  .code-block {
+    font-family: 'IBM Plex Mono', monospace;
+    font-size: 0.8rem;
+    background: #0d1117;
+    border: 1px solid #21262d;
+    border-radius: 6px;
+    padding: 1rem;
+    overflow-x: auto;
+    white-space: pre;
+    line-height: 1.6;
+  }
+
+  .badge {
+    display: inline-flex;
+    align-items: center;
+    gap: 4px;
+    font-size: 0.7rem;
+    font-weight: 500;
+    padding: 2px 8px;
+    border-radius: 999px;
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+  }
+
+  .badge-green {
+    background: rgba(0, 255, 135, 0.1);
+    color: #00ff87;
+    border: 1px solid rgba(0, 255, 135, 0.2);
+  }
+
+  .badge-cyan {
+    background: rgba(0, 212, 255, 0.1);
+    color: #00d4ff;
+    border: 1px solid rgba(0, 212, 255, 0.2);
+  }
+
+  .badge-purple {
+    background: rgba(168, 85, 247, 0.1);
+    color: #a855f7;
+    border: 1px solid rgba(168, 85, 247, 0.2);
+  }
+
+  .badge-orange {
+    background: rgba(255, 107, 53, 0.1);
+    color: #ff6b35;
+    border: 1px solid rgba(255, 107, 53, 0.2);
+  }
+
+  .badge-gray {
+    background: rgba(72, 79, 88, 0.3);
+    color: #8b949e;
+    border: 1px solid #30363d;
+  }
+
+  /* Used by ModelForm field labels */
+  .form-label {
+    display: block;
+    font-size: 0.75rem;
+    font-weight: 500;
+    color: #8b949e;
+    margin-bottom: 6px;
+  }
+
+  .btn-primary {
+    display: inline-flex;
+    align-items: center;
+    gap: 8px;
+    background: #00ff87;
+    color: #050709;
+    font-weight: 600;
+    font-size: 0.875rem;
+    padding: 8px 16px;
+    border-radius: 6px;
+    transition: all 0.15s ease;
+    cursor: pointer;
+    border: none;
+  }
+
+  .btn-primary:hover {
+    background: #00e07a;
+    transform: translateY(-1px);
+    box-shadow: 0 4px 12px rgba(0, 255, 135, 0.3);
+  }
+
+  .btn-primary:active {
+    transform: translateY(0);
+  }
+
+  .btn-primary:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+    transform: none;
+    box-shadow: none;
+  }
+
+  .btn-secondary {
+    display: inline-flex;
+    align-items: center;
+    gap: 8px;
+    background: transparent;
+    color: #8b949e;
+    font-weight: 500;
+    font-size: 0.875rem;
+    padding: 7px 15px;
+    border-radius: 6px;
+    transition: all 0.15s ease;
+    cursor: pointer;
+    border: 1px solid #30363d;
+  }
+
+  .btn-secondary:hover {
+    background: #21262d;
+    color: #e6edf3;
+    border-color: #484f58;
+  }
+
+  .btn-danger {
+    display: inline-flex;
+    align-items: center;
+    gap: 8px;
+    background: transparent;
+    color: #ff4757;
+    font-weight: 500;
+    font-size: 0.875rem;
+    padding: 7px 15px;
+    border-radius: 6px;
+    transition: all 0.15s ease;
+    cursor: pointer;
+    border: 1px solid rgba(255, 71, 87, 0.3);
+  }
+
+  .btn-danger:hover {
+    background: rgba(255, 71, 87, 0.1);
+  }
+
+  .input {
+    width: 100%;
+    background: #0d1117;
+    border: 1px solid #30363d;
+    border-radius: 6px;
+    padding: 8px 12px;
+    color: #e6edf3;
+    font-size: 0.875rem;
+    font-family: inherit;
+    transition: border-color 0.15s ease;
+    outline: none;
+  }
+
+  .input:focus {
+    border-color: #00ff87;
+    box-shadow: 0 0 0 2px rgba(0, 255, 135, 0.1);
+  }
+
+  .input::placeholder {
+    color: #484f58;
+  }
+
+  .input-mono {
+    font-family: 'IBM Plex Mono', monospace;
+    font-size: 0.8rem;
+  }
+
+  .select {
+    width: 100%;
+    background: #0d1117;
+    border: 1px solid #30363d;
+    border-radius: 6px;
+    padding: 8px 12px;
+    color: #e6edf3;
+    font-size: 0.875rem;
+    font-family: inherit;
+    outline: none;
+    cursor: pointer;
+    transition: border-color 0.15s ease;
+    appearance: none;
+    background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='12' height='12' viewBox='0 0 24 24' fill='none' stroke='%238b949e' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpolyline points='6 9 12 15 18 9'%3E%3C/polyline%3E%3C/svg%3E");
+    background-repeat: no-repeat;
+    background-position: right 12px center;
+    padding-right: 36px;
+  }
+
+  .select:focus {
+    border-color: #00ff87;
+    box-shadow: 0 0 0 2px rgba(0, 255, 135, 0.1);
+  }
+
+  .card {
+    background: #0d1117;
+    border: 1px solid #21262d;
+    border-radius: 8px;
+    transition: border-color 0.15s ease;
+  }
+
+  .card:hover {
+    border-color: #30363d;
+  }
+
+  .divider {
+    border: none;
+    border-top: 1px solid #21262d;
+  }
+
+  /* BUG FIX: Moved from ModelForm.jsx module-level style injection */
+  .form-label {
+    display: block;
+    font-size: 0.75rem;
+    font-weight: 500;
+    color: #8b949e;
+    margin-bottom: 6px;
+  }
+}
+
+@layer utilities {
+  .text-gradient-green {
+    background: linear-gradient(135deg, #00ff87, #00d4ff);
+    -webkit-background-clip: text;
+    -webkit-text-fill-color: transparent;
+    background-clip: text;
+  }
+}

frontend/src/main.jsx

@@ -0,0 +1,10 @@
+import React from "react";
+import ReactDOM from "react-dom/client";
+import App from "./App";
+import "./index.css";
+
+ReactDOM.createRoot(document.getElementById("root")).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>
+);

frontend/tailwind.config.js

@@ -0,0 +1,55 @@
+/** @type {import('tailwindcss').Config} */
+export default {
+  content: ["./index.html", "./src/**/*.{js,ts,jsx,tsx}"],
+  theme: {
+    extend: {
+      fontFamily: {
+        sans: ["'IBM Plex Sans'", "system-ui", "sans-serif"],
+        mono: ["'IBM Plex Mono'", "monospace"],
+        display: ["'Space Grotesk'", "sans-serif"],
+      },
+      colors: {
+        surface: {
+          0: "#050709",
+          1: "#0d1117",
+          2: "#161b22",
+          3: "#21262d",
+          4: "#30363d",
+        },
+        accent: {
+          green: "#00ff87",
+          cyan: "#00d4ff",
+          purple: "#a855f7",
+          orange: "#ff6b35",
+          red: "#ff4757",
+        },
+        text: {
+          primary: "#e6edf3",
+          secondary: "#8b949e",
+          muted: "#484f58",
+        },
+      },
+      animation: {
+        "pulse-slow": "pulse 3s cubic-bezier(0.4, 0, 0.6, 1) infinite",
+        "slide-in": "slideIn 0.2s ease-out",
+        "fade-in": "fadeIn 0.3s ease-out",
+        glow: "glow 2s ease-in-out infinite alternate",
+      },
+      keyframes: {
+        slideIn: {
+          from: { transform: "translateY(-8px)", opacity: "0" },
+          to: { transform: "translateY(0)", opacity: "1" },
+        },
+        fadeIn: {
+          from: { opacity: "0" },
+          to: { opacity: "1" },
+        },
+        glow: {
+          from: { boxShadow: "0 0 5px rgba(0,255,135,0.3)" },
+          to: { boxShadow: "0 0 20px rgba(0,255,135,0.6)" },
+        },
+      },
+    },
+  },
+  plugins: [],
+};

frontend/vite.config.js

@@ -0,0 +1,30 @@
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+
+export default defineConfig({
+  plugins: [react()],
+  server: {
+    port: 5173,
+    proxy: {
+      "/api": {
+        target: "http://localhost:3001",
+        changeOrigin: true,
+      },
+      "/v1": {
+        target: "http://localhost:4000",
+        changeOrigin: true,
+      },
+    },
+  },
+  build: {
+    outDir: "dist",
+    sourcemap: false,
+    rollupOptions: {
+      output: {
+        manualChunks: {
+          react: ["react", "react-dom"],
+        },
+      },
+    },
+  },
+});

huggingface/README.md

@@ -0,0 +1,87 @@
+---
+title: AI Gateway Hub
+emoji: 🚀
+colorFrom: green
+colorTo: blue
+sdk: docker
+app_port: 7860
+pinned: false
+license: mit
+short_description: Universal AI Gateway — any provider to OpenAI API
+---
+
+# 🚀 AI Gateway Hub
+
+> **Universal AI API Gateway** — Register any AI provider (OpenAI, Anthropic, Ollama, Gemini, Groq, and 100+ more) and get a single OpenAI-compatible endpoint. Powered by [LiteLLM](https://litellm.ai).
+
+## ⚙️ Setup (Required Before First Use)
+
+This Space needs a few secrets set before it will work correctly.
+
+Go to **Space Settings → Repository secrets** and add:
+
+| Secret | Required | Description |
+|---|---|---|
+| `LITELLM_MASTER_KEY` | ✅ Yes | Admin key for the LiteLLM proxy. Use a strong random string, e.g. `sk-gateway-xxxxxxxx` |
+| `JWT_SECRET` | ✅ Yes | Secret for backend session tokens. Any long random string |
+| `GATEWAY_PUBLIC_URL` | ✅ Yes | The public URL of this Space: `https://<your-username>-<space-name>.hf.space` |
+| `OPENAI_API_KEY` | Optional | Required only if you register OpenAI models |
+| `ANTHROPIC_API_KEY` | Optional | Required only if you register Anthropic models |
+| `GROQ_API_KEY` | Optional | Required only if you register Groq models |
+| `GEMINI_API_KEY` | Optional | Required only if you register Google Gemini models |
+
+> **Tip:** `GATEWAY_PUBLIC_URL` is set automatically on the **first** deploy by the GitHub Actions workflow and is never overwritten afterward, so you can safely customise it to a custom domain later.
+
+> **Tip:** Any provider API key you register through the UI is stored encrypted in the Space's SQLite database and never exposed to callers of the gateway.
+
+## 🚀 Quick Start
+
+1. After setting secrets above, wait for the Space to restart (it rebuilds automatically)
+2. Open the Space — you'll see the **AI Gateway Hub** dashboard
+3. Click **Add Model** and fill in your provider details
+4. Use the generated `model name` with any OpenAI SDK:
+
+```python
+from openai import OpenAI
+
+client = OpenAI(
+    base_url="https://<your-username>-<space-name>.hf.space/v1",
+    api_key="any-string",   # callers don't need the real provider key
+)
+
+response = client.chat.completions.create(
+    model="anthropic/claude-3-5-sonnet-20241022",  # alias shown in the UI
+    messages=[{"role": "user", "content": "Hello!"}],
+)
+print(response.choices[0].message.content)
+```
+
+## 📡 API Endpoints
+
+| Path | Description |
+|---|---|
+| `GET  /` | Web dashboard |
+| `POST /v1/chat/completions` | OpenAI-compatible chat (streaming supported) |
+| `POST /v1/embeddings` | Text embeddings |
+| `GET  /v1/models` | List registered models |
+| `GET  /api/models` | Management API — list models |
+| `POST /api/models` | Management API — register model |
+| `GET  /api/health` | Health check |
+
+## 📦 Supported Providers
+
+OpenAI · Anthropic · Google Gemini · Ollama · Groq · Mistral · Cohere · Together AI · AWS Bedrock · Azure OpenAI · HuggingFace · DeepSeek · Perplexity · Replicate · any OpenAI-compatible endpoint
+
+Full list: [docs.litellm.ai/docs/providers](https://docs.litellm.ai/docs/providers)
+
+## ⚠️ Important Notes
+
+- **Persistence:** The SQLite database (`/app/data/gateway.db`) storing your registered models is **ephemeral** on the free CPU Basic hardware tier — it resets on Space restart. To persist data, upgrade to a paid hardware tier or use an external database.
+- **Rate limits:** The free HF Spaces tier has CPU/memory limits. For production use, consider duplicating this Space with upgraded hardware.
+- **Security:** This Space is public by default. Anyone can call your `/v1/*` endpoints. For private use, set the Space visibility to **Private** in Space Settings.
+
+## 🔗 Source
+
+This Space is automatically deployed from the [AI Gateway Hub GitHub repository](https://github.com/your-org/ai-gateway-hub).
+
+> Replace `your-org/ai-gateway-hub` above with your actual repository URL.

huggingface/entrypoint.sh

@@ -0,0 +1,100 @@
+#!/usr/bin/env bash
+# ─────────────────────────────────────────────────────────────────────────────
+# entrypoint.sh — container startup for Hugging Face Spaces
+#
+# Responsibilities:
+#   1. Apply sensible defaults for any env vars not set via HF Space secrets
+#   2. Ensure required directories exist and are writable (ephemeral /tmp)
+#   3. Sanity-check required files baked into the image
+#   4. Hand off to supervisord (which manages litellm, backend, nginx)
+#
+# Environment variables (set in HF Space → Settings → Repository secrets):
+#
+#   LITELLM_MASTER_KEY   Required. Admin key for LiteLLM proxy.
+#   JWT_SECRET           Required. Secret for backend session tokens.
+#   GATEWAY_PUBLIC_URL   Required. Public URL of this Space, e.g.
+#                          https://<user>-<space>.hf.space
+#                          (auto-set by the GitHub Actions workflow)
+#   DB_PATH              Optional. SQLite path. Default: /app/data/gateway.db
+#   LOG_LEVEL            Optional. Winston log level. Default: http
+#
+#   Provider API keys (optional, set whichever you use):
+#   OPENAI_API_KEY, ANTHROPIC_API_KEY, GROQ_API_KEY, GEMINI_API_KEY, …
+# ─────────────────────────────────────────────────────────────────────────────
+set -euo pipefail
+
+echo "──────────────────────────────────────────"
+echo " AI Gateway Hub — starting (HF Spaces)"
+echo "──────────────────────────────────────────"
+
+# ── 1. Defaults for optional / missing env vars ───────────────────────────────
+
+# LITELLM_MASTER_KEY is critical — warn loudly if using the insecure default
+if [ -z "${LITELLM_MASTER_KEY:-}" ]; then
+  export LITELLM_MASTER_KEY="sk-gateway-hf-insecure-change-me"
+  echo "⚠️  WARNING: LITELLM_MASTER_KEY not set. Using insecure default."
+  echo "    Set it in: HF Space → Settings → Repository secrets"
+fi
+
+if [ -z "${JWT_SECRET:-}" ]; then
+  # Generate a random secret at runtime; sessions won't survive restarts
+  # but this is acceptable for a demo Space.
+  export JWT_SECRET
+  JWT_SECRET=$(python3 -c "import secrets; print(secrets.token_hex(32))")
+  echo "ℹ️  JWT_SECRET not set — generated an ephemeral secret for this session."
+fi
+
+export GATEWAY_PUBLIC_URL="${GATEWAY_PUBLIC_URL:-http://localhost:7860}"
+export DB_PATH="${DB_PATH:-/app/data/gateway.db}"
+export LOG_LEVEL="${LOG_LEVEL:-http}"
+export NODE_ENV="${NODE_ENV:-production}"
+
+echo "GATEWAY_PUBLIC_URL : ${GATEWAY_PUBLIC_URL}"
+echo "DB_PATH            : ${DB_PATH}"
+echo "LOG_LEVEL          : ${LOG_LEVEL}"
+
+# ── 2. Create / verify writable directories ───────────────────────────────────
+
+# /app/data persists the SQLite DB; may be ephemeral on free-tier HF Spaces.
+mkdir -p "$(dirname "${DB_PATH}")"
+
+# nginx needs these temp dirs when running as non-root
+mkdir -p \
+  /tmp/nginx/client_body \
+  /tmp/nginx/proxy \
+  /tmp/nginx/fastcgi \
+  /tmp/nginx/uwsgi \
+  /tmp/nginx/scgi
+
+# supervisor socket + pid files live in /tmp (non-root writable)
+mkdir -p /tmp/supervisor
+
+echo "✅ Directories ready"
+
+# ── 3. Sanity-check required files baked into the image ──────────────────────
+
+if [ ! -f "/app/litellm/config.yaml" ]; then
+  echo "❌ /app/litellm/config.yaml not found — aborting."
+  exit 1
+fi
+echo "✅ LiteLLM config found"
+
+if [ ! -f "/app/frontend/dist/index.html" ]; then
+  echo "❌ Frontend build missing at /app/frontend/dist/index.html"
+  echo "   This should have been built in the Docker image Stage 1."
+  exit 1
+fi
+echo "✅ Frontend build present"
+
+# ── 4. Print startup summary ──────────────────────────────────────────────────
+echo ""
+echo "Starting services:"
+echo "  • LiteLLM proxy    → localhost:4000"
+echo "  • Node.js backend  → localhost:3001"
+echo "  • nginx (public)   → 0.0.0.0:7860"
+echo ""
+echo "Access your gateway at: ${GATEWAY_PUBLIC_URL}"
+echo "──────────────────────────────────────────"
+
+# ── 5. Exec supervisord (replaces this script as PID 1) ──────────────────────
+exec /usr/bin/supervisord -c /app/huggingface/supervisord.conf

huggingface/nginx.conf

@@ -0,0 +1,126 @@
+# ─────────────────────────────────────────────────────────────────────────────
+# nginx configuration for Hugging Face Spaces (single-container deployment)
+#
+# Key differences from nginx/nginx.conf (multi-container docker-compose):
+#
+#  1. No `user` directive — nginx runs as the current user (uid 1000).
+#     The `user` directive requires root; omitting it defaults to the process owner.
+#
+#  2. All temp/pid paths redirected to /tmp — /var/run is root-owned.
+#
+#  3. Frontend served as static files directly from /app/frontend/dist —
+#     no upstream `frontend` container exists in the single-container layout.
+#
+#  4. Upstream addresses are localhost (127.0.0.1) not container hostnames.
+#
+#  5. Port 7860 — required by HF Spaces (set in huggingface/README.md).
+#
+# Bug fix applied:
+#   [Bug8] Added explicit `log_format gateway` with a [nginx] prefix so that
+#          nginx access log lines are distinguishable from litellm/backend logs
+#          when all three processes write to the same Docker log stream via
+#          supervisord stdout/stderr forwarding.
+# ─────────────────────────────────────────────────────────────────────────────
+
+# No `user` directive — process runs as uid 1000 (set in Dockerfile USER)
+worker_processes auto;
+error_log  /dev/stderr warn;
+pid        /tmp/nginx.pid;
+
+events {
+    worker_connections 1024;
+    multi_accept on;
+}
+
+http {
+    include      /etc/nginx/mime.types;
+    default_type application/octet-stream;
+
+    # ── Writable temp dirs for non-root nginx ──────────────────────────────
+    client_body_temp_path /tmp/nginx/client_body;
+    proxy_temp_path       /tmp/nginx/proxy;
+    fastcgi_temp_path     /tmp/nginx/fastcgi;
+    uwsgi_temp_path       /tmp/nginx/uwsgi;
+    scgi_temp_path        /tmp/nginx/scgi;
+
+    # FIX [Bug8]: Named log format with [nginx] prefix so nginx access lines
+    # are distinguishable from litellm / backend lines in the merged Docker log
+    # stream produced by supervisord's stdout forwarding.
+    log_format gateway '[nginx] $remote_addr - "$request" $status $body_bytes_sent '
+                       '"$http_referer" "$http_user_agent" ${request_time}s';
+    access_log /dev/stdout gateway;
+
+    sendfile       on;
+    tcp_nopush     on;
+    tcp_nodelay    on;
+    keepalive_timeout 65;
+
+    gzip on;
+    gzip_vary on;
+    gzip_proxied any;
+    gzip_comp_level 6;
+    gzip_types
+        text/plain text/css text/xml text/javascript
+        application/json application/javascript application/xml+rss
+        application/atom+xml image/svg+xml;
+
+    server {
+        listen 7860;
+        server_name _;
+
+        client_max_body_size 100M;
+        proxy_read_timeout    300s;
+        proxy_connect_timeout  10s;
+        proxy_send_timeout    300s;
+
+        # ── LiteLLM OpenAI-compatible gateway ─────────────────────────────
+        location /v1/ {
+            proxy_pass http://127.0.0.1:4000;
+            proxy_http_version 1.1;
+            proxy_set_header Host              $host;
+            proxy_set_header X-Real-IP         $remote_addr;
+            proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+            proxy_set_header Connection        "";
+
+            # SSE / streaming — must disable buffering end-to-end
+            proxy_buffering            off;
+            proxy_cache                off;
+            chunked_transfer_encoding  on;
+            proxy_read_timeout        300s;
+        }
+
+        # ── Backend management API ─────────────────────────────────────────
+        location /api/ {
+            proxy_pass http://127.0.0.1:3001;
+            proxy_http_version 1.1;
+            proxy_set_header Host              $host;
+            proxy_set_header X-Real-IP         $remote_addr;
+            proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+            proxy_set_header Connection        "";
+        }
+
+        # ── Frontend SPA (served directly — no upstream container) ────────
+        # Vite build outputs to /app/frontend/dist.
+        # try_files handles client-side routing (React Router / direct URLs).
+        location / {
+            root  /app/frontend/dist;
+            index index.html;
+            try_files $uri $uri/ /index.html;
+
+            # Short cache for HTML entry point (users always get fresh shell)
+            location = /index.html {
+                add_header Cache-Control "no-cache, must-revalidate";
+                expires 0;
+            }
+        }
+
+        # ── Vite content-hashed assets (cache aggressively) ───────────────
+        location /assets/ {
+            root  /app/frontend/dist;
+            expires 1y;
+            add_header Cache-Control "public, immutable";
+        }
+    }
+}

huggingface/supervisord.conf

@@ -0,0 +1,105 @@
+# ─────────────────────────────────────────────────────────────────────────────
+# supervisord.conf — process manager for the HF Spaces single container
+#
+# Process start order (by priority value, lower = earlier):
+#   10  litellm  — AI proxy, must be up before backend tries to register models
+#   20  backend  — Node.js management API (has built-in retry for LiteLLM)
+#   30  nginx    — reverse proxy, last to start so upstreams are ready
+#
+# All stdout/stderr are forwarded to /dev/stdout and /dev/stderr so HF Spaces
+# can capture logs in its built-in log viewer.
+#
+# Bug fixes applied:
+#   [Bug1] Removed `user=user` — already non-root via Dockerfile USER; adding
+#          it again causes supervisord to crash with "Can't drop privilege".
+#
+#   [BugA] environment= values must be on a SINGLE LINE or with the value
+#          starting on the SAME LINE as the key (not on the next line).
+#
+#          Python's ConfigParser (used by supervisord) parses:
+#            environment=
+#                KEY="val"
+#          as value = '\nKEY="val"'  (leading newline).
+#
+#          Supervisord's env parser then fails with:
+#            Error: Format string '\nKEY=...' for 'environment' is badly
+#            formatted: float argument required, not dict
+#          See: https://github.com/Supervisor/supervisor/issues/1123
+#
+#          With the leading \n, supervisord REFUSES TO START — the whole
+#          container crashes at boot. Even if it didn't crash, LITELLM_BASE_URL
+#          would not be set, so backend/src/litellm.js would fall back to
+#          "http://litellm:4000" (Docker Compose hostname), which is
+#          unresolvable inside a single container. All LiteLLM API calls fail.
+#
+#          FIX: Keep the entire value on one line after the = sign.
+# ─────────────────────────────────────────────────────────────────────────────
+
+[supervisord]
+nodaemon=true                       ; stay in foreground so Docker sees it as PID 1
+logfile=/dev/null                   ; supervisord's own log → suppress (child logs are enough)
+logfile_maxbytes=0
+pidfile=/tmp/supervisord.pid        ; /var/run is root-owned; use /tmp
+; NOTE: do NOT add `user=` here. The container already runs as uid=1000 via
+;       Dockerfile USER. Adding `user=` when already non-root crashes supervisord.
+
+[unix_http_server]
+file=/tmp/supervisor.sock
+
+[supervisorctl]
+serverurl=unix:///tmp/supervisor.sock
+
+[rpcinterface:supervisor]
+supervisor.rpcinterface_factory=supervisor.rpcinterface:make_main_rpcinterface
+
+# ── LiteLLM proxy ─────────────────────────────────────────────────────────────
+[program:litellm]
+command=litellm --config /app/litellm/config.yaml --port 4000 --num_workers 2
+directory=/app
+autostart=true
+autorestart=true
+startsecs=15                        ; give LiteLLM time to initialise before health checks
+startretries=5
+priority=10
+stdout_logfile=/dev/stdout
+stdout_logfile_maxbytes=0
+stderr_logfile=/dev/stderr
+stderr_logfile_maxbytes=0
+; All env vars (LITELLM_MASTER_KEY etc.) are inherited from entrypoint.sh via
+; exec → supervisord env inheritance. No environment= needed here.
+
+# ── Backend (Node.js management API) ──────────────────────────────────────────
+[program:backend]
+command=node /app/backend/src/index.js
+directory=/app/backend
+autostart=true
+autorestart=true
+startsecs=5
+startretries=10
+priority=20
+stdout_logfile=/dev/stdout
+stdout_logfile_maxbytes=0
+stderr_logfile=/dev/stderr
+stderr_logfile_maxbytes=0
+; FIX [BugA]: environment= value MUST start on the same line as the key.
+; Starting it on the next line causes supervisord to parse a leading \n, which
+; makes its env formatter raise "badly formatted" and refuse to start.
+;
+; These three vars are always the same inside this container and different from
+; the docker-compose defaults, so we override them explicitly. All other vars
+; (LITELLM_MASTER_KEY, GATEWAY_PUBLIC_URL, JWT_SECRET, DB_PATH, LOG_LEVEL)
+; are inherited from entrypoint.sh exports via supervisord's environment.
+environment=LITELLM_BASE_URL="http://127.0.0.1:4000",PORT="3001",NODE_ENV="production"
+
+# ── nginx reverse proxy ────────────────────────────────────────────────────────
+[program:nginx]
+command=/usr/sbin/nginx -c /app/huggingface/nginx.conf -g "daemon off;"
+autostart=true
+autorestart=true
+startsecs=3
+startretries=5
+priority=30
+stdout_logfile=/dev/stdout
+stdout_logfile_maxbytes=0
+stderr_logfile=/dev/stderr
+stderr_logfile_maxbytes=0

litellm/config.yaml

@@ -0,0 +1,73 @@
+# ─────────────────────────────────────────────────────────────────────────────
+# LiteLLM Gateway Configuration
+# AI Gateway Hub — https://github.com/your-org/ai-gateway-hub
+# ─────────────────────────────────────────────────────────────────────────────
+
+general_settings:
+  master_key: os.environ/LITELLM_MASTER_KEY
+
+  # NOTE: store_model_in_db is intentionally disabled.
+  # LiteLLM >= 1.x requires PostgreSQL for this feature; SQLite is NOT supported.
+  # AI Gateway Hub's own backend (Node.js + SQLite) persists model configs and
+  # re-registers them with LiteLLM on startup via POST /model/new.
+  # store_model_in_db: true   ← requires postgres, keep commented out
+
+  # ─── BUG FIX #14: Removed `allow_model_access_groups_on_request: true` ───
+  #
+  # That key is NOT a valid LiteLLM general_settings field. It appears in no
+  # version of the official LiteLLM docs or source code under general_settings.
+  # LiteLLM silently ignores unknown keys in this block (Pydantic extra="ignore"),
+  # so the setting had zero effect — it was pure dead config that could mislead
+  # operators into believing access-group enforcement was active when it was not.
+  #
+  # If you need to restrict which models a virtual key can access, use
+  # LiteLLM's Virtual Keys + model access groups feature instead:
+  #   https://docs.litellm.ai/docs/proxy/virtual_keys
+  # ─────────────────────────────────────────────────────────────────────────
+
+litellm_settings:
+  # Drop unsupported parameters instead of raising errors
+  drop_params: true
+  # Return original response on errors
+  set_verbose: false
+  # Request timeout in seconds
+  request_timeout: 120
+  # Retry configuration
+  num_retries: 2
+  # NOTE: max_budget: 0 is intentionally absent — it would block all paid requests.
+  # NOTE: proxy_server_settings block is intentionally absent — it is not a valid
+  #       top-level LiteLLM config key and is silently ignored.
+  #       Callbacks belong here under litellm_settings, e.g.:
+  #         success_callback: ["langfuse"]
+  #         failure_callback: ["langfuse"]
+
+router_settings:
+  # "simple-shuffle" is the correct default for a single-instance deployment.
+  # "usage-based-routing" requires a Redis backend for cross-process TPM/RPM
+  # tracking; this project has no Redis service in docker-compose.yml so that
+  # strategy would fail a Redis connection on every request.
+  routing_strategy: "simple-shuffle"
+  num_retries: 2
+  timeout: 120
+  retry_after: 5
+
+# ─── Pre-configured model examples (users can add more via the UI) ───────────
+model_list:
+  # ── Example: Ollama local models (no API key needed) ──────────────────────
+  - model_name: ollama/llama3
+    litellm_params:
+      model: ollama/llama3
+      api_base: "http://host.docker.internal:11434"
+    model_info:
+      description: "Llama 3 via local Ollama (no API key required)"
+      supports_function_calling: true
+
+  # ── Example: OpenAI-compatible custom endpoint ────────────────────────────
+  - model_name: custom/my-openai-compatible
+    litellm_params:
+      model: openai/gpt-3.5-turbo
+      api_base: "https://your-custom-endpoint.example.com/v1"
+      api_key: "optional-key-or-empty"
+    model_info:
+      description: "Custom OpenAI-compatible endpoint example"
+      supports_function_calling: true

nginx/nginx.conf

@@ -0,0 +1,109 @@
+user nginx;
+worker_processes auto;
+error_log /var/log/nginx/error.log warn;
+pid /var/run/nginx.pid;
+
+events {
+    worker_connections 4096;
+    # NOTE: removed "use epoll" — Linux-only, breaks on macOS Docker Desktop.
+    multi_accept on;
+}
+
+http {
+    include       /etc/nginx/mime.types;
+    default_type  application/octet-stream;
+
+    log_format main '$remote_addr - $remote_user [$time_local] "$request" '
+                    '$status $body_bytes_sent "$http_referer" '
+                    '"$http_user_agent" rt=$request_time';
+
+    access_log /var/log/nginx/access.log main;
+
+    sendfile        on;
+    tcp_nopush      on;
+    tcp_nodelay     on;
+    keepalive_timeout 65;
+    gzip on;
+    gzip_vary on;
+    gzip_proxied any;
+    gzip_comp_level 6;
+    gzip_types text/plain text/css text/xml application/json application/javascript
+               application/xml+rss application/atom+xml image/svg+xml;
+
+    # Rate limiting
+    limit_req_zone $binary_remote_addr zone=api:10m rate=100r/m;
+    limit_req_zone $binary_remote_addr zone=v1:10m rate=200r/m;
+
+    # Upstream definitions
+    upstream backend {
+        server backend:3001;
+        keepalive 32;
+    }
+
+    upstream litellm {
+        server litellm:4000;
+        keepalive 64;
+    }
+
+    upstream frontend {
+        server frontend:80;
+        keepalive 16;
+    }
+
+    server {
+        listen 80;
+        server_name _;
+
+        client_max_body_size 100M;
+        proxy_read_timeout 300s;
+        proxy_connect_timeout 10s;
+        proxy_send_timeout 300s;
+
+        # ── OpenAI-compatible AI API endpoints (via LiteLLM) ──────────────
+        location /v1/ {
+            limit_req zone=v1 burst=50 nodelay;
+
+            proxy_pass http://litellm;
+            proxy_http_version 1.1;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+            proxy_set_header Connection "";
+
+            # SSE / streaming support
+            proxy_buffering off;
+            proxy_cache off;
+            chunked_transfer_encoding on;
+            proxy_read_timeout 300s;
+        }
+
+        # ── Backend Management API ────────────────────────────────────────
+        location /api/ {
+            limit_req zone=api burst=20 nodelay;
+
+            proxy_pass http://backend;
+            proxy_http_version 1.1;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+            proxy_set_header Connection "";
+        }
+
+        # ── Frontend SPA ──────────────────────────────────────────────────
+        # BUG FIX #12: Removed Upgrade / Connection "upgrade" headers.
+        # The frontend is a static React SPA served by nginx — it does not use
+        # WebSockets. Sending Upgrade headers to a plain HTTP upstream is
+        # incorrect. Connection "" clears the hop-by-hop header and enables
+        # HTTP/1.1 keepalive to the upstream frontend container.
+        location / {
+            proxy_pass http://frontend;
+            proxy_http_version 1.1;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header Connection "";
+        }
+    }
+}

scripts/setup.sh

@@ -0,0 +1,101 @@
+#!/usr/bin/env bash
+# ─────────────────────────────────────────────────────────────────────────────
+# AI Gateway Hub — Quick Setup Script
+# ─────────────────────────────────────────────────────────────────────────────
+set -euo pipefail
+
+BOLD="\033[1m"
+GREEN="\033[32m"
+CYAN="\033[36m"
+YELLOW="\033[33m"
+RED="\033[31m"
+RESET="\033[0m"
+
+header() { echo -e "\n${BOLD}${CYAN}▶ $1${RESET}"; }
+ok()     { echo -e "  ${GREEN}✓${RESET} $1"; }
+warn()   { echo -e "  ${YELLOW}⚠${RESET} $1"; }
+err()    { echo -e "  ${RED}✗${RESET} $1"; exit 1; }
+
+echo -e "${BOLD}${GREEN}"
+cat <<'EOF'
+   _   _____   _____       _                           _   _       _
+  /_\ |_   _| |  __ \     | |                         | | | |     | |
+ / _ \  | |   | |  \/ __ _| |_ _____      ____ _ _   _| |_| |_   _| |__
+/ ___ \ | |   | | __ / _` | __/ _ \ \ /\ / / _` | | | |  _  | | | | '_ \
+\/_/\_\|_|   | |_\ \ (_| | ||  __/\ V  V / (_| | |_| | | | | |_| | |_) |
+             \____/\__,_|\__\___| \_/\_/ \__,_|\__, \_| |_/\__,_|_.__/
+                                                __/ |
+                                               |___/
+EOF
+echo -e "${RESET}"
+
+header "Checking prerequisites"
+command -v docker   &>/dev/null || err "Docker is not installed. https://docs.docker.com/get-docker/"
+docker compose version &>/dev/null 2>&1 || \
+  docker-compose version &>/dev/null 2>&1 || err "Docker Compose is not installed."
+ok "Docker $(docker --version | awk '{print $3}' | tr -d ',')"
+ok "Docker Compose available"
+
+header "Setting up environment"
+if [ ! -f .env ]; then
+  cp .env.example .env
+
+  # BUG FIX #11: The original fallback used `xxd` which is not present in many
+  # minimal Linux images (Alpine, BusyBox-based). Replaced with `od` which is
+  # POSIX-standard and universally available. The `openssl rand -hex` path is
+  # still the primary method; `od` is only the fallback.
+  gen_hex() {
+    local bytes=$1
+    openssl rand -hex "$bytes" 2>/dev/null || \
+      od -An -N"$bytes" -tx1 /dev/urandom 2>/dev/null | tr -d ' \n'
+  }
+
+  MASTER_KEY="sk-gateway-$(gen_hex 16)"
+  JWT_SECRET="$(gen_hex 32)"
+
+  sed -i.bak "s/sk-gateway-master-key-change-me/${MASTER_KEY}/" .env
+  sed -i.bak "s/super-secret-jwt-key-change-in-production/${JWT_SECRET}/" .env
+  rm -f .env.bak
+  ok ".env created with random secrets"
+else
+  warn ".env already exists — skipping"
+fi
+
+header "Creating SSL directory"
+mkdir -p nginx/ssl
+ok "nginx/ssl/ created"
+
+header "Building and starting services"
+docker compose pull litellm 2>/dev/null || true
+docker compose build --parallel
+docker compose up -d
+
+header "Waiting for services to be healthy"
+echo -n "  Waiting"
+for i in $(seq 1 30); do
+  sleep 2
+  echo -n "."
+  if curl -sf http://localhost/api/health &>/dev/null; then
+    echo ""
+    ok "Gateway is ready!"
+    break
+  fi
+  if [ "$i" -eq 30 ]; then
+    echo ""
+    warn "Timeout waiting for health check. Check logs: docker compose logs"
+  fi
+done
+
+echo ""
+echo -e "${BOLD}${GREEN}═══════════════════════════════════════════════════${RESET}"
+echo -e "${BOLD}  🚀 AI Gateway Hub is running!${RESET}"
+echo ""
+echo -e "  ${CYAN}Web UI:${RESET}         http://localhost"
+echo -e "  ${CYAN}API Endpoint:${RESET}   http://localhost/v1"
+echo -e "  ${CYAN}Management API:${RESET} http://localhost/api"
+echo ""
+echo -e "  ${YELLOW}Next steps:${RESET}"
+echo -e "  1. Open http://localhost in your browser"
+echo -e "  2. Click 'Add Model' to register your first AI model"
+echo -e "  3. Use the generated endpoint with any OpenAI SDK"
+echo -e "${BOLD}${GREEN}═══════════════════════════════════════════════════${RESET}"