Spaces:
Running
Running
| # OpenCode Space — Production System Architecture & Design Specification | |
| This document provides a comprehensive technical overview of the **`Jishnupg/Opencode-Cli`** multi-service gateway architecture, service discovery, database persistence model, security boundaries, and protocol proxies. | |
| --- | |
| ## 1. System Ingress Topology & Port Matrix | |
| All client traffic terminates at **Port 4096** (the exposed public port on Hugging Face Spaces). The system operates a dual-layer reverse proxy architecture to guarantee sub-second platform readiness and unified routing. | |
| ``` | |
| [🌐 Public Internet Client] | |
| │ | |
| [Nginx Edge Proxy (Port 4096)] | |
| │ | |
| [FastAPI Master Gateway (:8000)] | |
| │ | |
| ┌───────────────────────┬───────────────────┴───────────────────┬──────────────────┐ | |
| │ │ │ │ | |
| [Portal Hub / Dashboard] [OmniRoute API & Dash] [Hermes Autonomous Agent] [Jellyfin & TG] | |
| (FastAPI Internal) (Port 20128) (Port 8642) (Port 8096 / 8080) | |
| Path: / Path: /v1, /dashboard Path: /hermes/v1/* Path: /jellyfin, /tg-stream | |
| ``` | |
| ### Complete Ingress Routing Matrix | |
| | Ingress Path / Pattern | Upstream Host:Port | Microservice | Protocol / Handler | Header Sanitization | | |
| | :--- | :--- | :--- | :--- | :--- | | |
| | `GET /health/live` | Internal Gateway | FastAPI Gateway | Native ASGI JSON | Instant 200 OK (<1ms) | | |
| | `/`, `/index.html` | Internal Gateway | Multi-Service Portal | HTML File Response | Portal Landing UI | | |
| | `/omniroute`, `/omniroute/`| `127.0.0.1:8000` | FastAPI Gateway | HTTP 307 Redirect | Redirects to `/dashboard` | | |
| | `/dashboard/*` | `127.0.0.1:20128` | OmniRoute Dashboard | HTTP / Next.js SSR | Strip X-Frame-Options | | |
| | `/v1/*`, `/api/v1/*` | `127.0.0.1:20128` | OmniRoute AI API | OpenAI SSE Stream | CORS `*`, `Host` forward | | |
| | `/v1beta/*`, `/api/v1beta/*`| `127.0.0.1:20128` | Gemini Web Bridge | Gemini JSON / Stream | CORS `*`, `Host` forward | | |
| | `/hermes/v1/*` | `127.0.0.1:8642` | Hermes Autonomous Agent | OpenAI / Tool SSE | Bearer Auth Forward | | |
| | `/api/providers/*` | `127.0.0.1:20128` | OmniRoute Management | REST JSON API | Encrypted DB read | | |
| | `/api/custom-models/*` | `127.0.0.1:20128` | OmniRoute Management | REST JSON API | Referer-based proxy | | |
| | `/api/connections/*` | `127.0.0.1:20128` | OmniRoute Management | REST JSON API | Referer-based proxy | | |
| | `/api/oauth/*` | `127.0.0.1:20128` | OmniRoute OAuth | Remote OAuth Flow | `ALLOW_REMOTE_OAUTH` | | |
| | `/live-ws/*` | `127.0.0.1:20128` | Live Telemetry WS | WebSocket Stream | `Host`, `X-Forwarded-*` | | |
| | `/jellyfin/*` | `127.0.0.1:8096` | Jellyfin Media Server | Range Video / HTTP | `X-Forwarded-Prefix` | | |
| | `/tg-stream/*`, `/tg_stream/*`| `127.0.0.1:8080` | Pyrogram 5G Streamer | 5G Chunk Streamer | Direct Pyrogram Stream | | |
| --- | |
| ## 2. Gateway Core Engine Architecture (`gateway/`) | |
| The master gateway (`gateway/main.py`, `gateway/utils.py`, `gateway/omniroute.py`, `gateway/hermes.py`) provides intelligent request classification and routing. | |
| ``` | |
| [Incoming HTTP Request] | |
| │ | |
| [Security Path Traversal Check] | |
| │ | |
| [Lightweight Probe /health/live?] ──(Yes)──> 200 OK | |
| │ (No) | |
| [Referer Header Inspection] | |
| / \ | |
| (Referer has /dashboard) (No OmniRoute Referer) | |
| │ │ | |
| [Route to OmniRoute :20128] [Match Path Prefix Matrix] | |
| / │ \ | |
| (OmniRoute) (Hermes) (Jellyfin / TG) | |
| │ │ │ | |
| [:20128] [:8642] [:8096 / :8080] | |
| │ | |
| [Root Fallback /] | |
| │ | |
| [Multi-Service Portal] | |
| ``` | |
| ### Key Gateway Design Patterns: | |
| 1. **Async Connection Pooling (`httpx.AsyncClient`)**: Managed via FastAPI `@asynccontextmanager` lifespan. Connection keep-alive prevents TCP handshake overhead across internal microservice proxies. | |
| 2. **Referer-Aware Routing**: Requests originating from OmniRoute UI pages (`Referer` containing `/dashboard` or `/omniroute`) are routed directly to OmniRoute port `20128`. This prevents auxiliary requests (`/api/custom-models`, `/api/connections`, `/providers/*.svg`) from breaking. | |
| 3. **CORS & iFrame Security Normalization**: Automatically strips restrictive `X-Frame-Options` headers and injects `Content-Security-Policy: frame-ancestors 'self' https://huggingface.co https://*.hf.space;` to enable embedding on Hugging Face Spaces. | |
| --- | |
| ## 3. Storage Persistence & SQLite Synchronization Model | |
| OmniRoute uses `better-sqlite3`. To bypass FUSE network drive lock limitations while maintaining persistence, a dual-layer storage architecture is implemented: | |
| ``` | |
| ┌──────────────────────────────────────────────┐ 120s Cron Daemon / ┌──────────────────────────────────────────────┐ | |
| │ High-Speed Ext4 Container Disk │ Shutdown Backup Loop │ Persistent Volume Mount │ | |
| │ (/root/.omniroute/storage.sqlite) ├────────────────────────────>│ (/data/omniroute/storage.sqlite) │ | |
| │ - Active runtime POSIX file locks (fcntl) │ │ - Persistent across Space rebuilds & sleep │ | |
| │ - Active WAL (-wal) & SHM (-shm) sidecars │<────────────────────────────┤ - Rotating backups (/data/omniroute/backups) │ | |
| └──────────────────────────────────────────────┘ Boot Restoration Sync └──────────────────────────────────────────────┘ | |
| ``` | |
| ### Database Lifecycle & Safety Guarantees: | |
| 1. **Boot Initialization**: | |
| - `entrypoint.sh` checks for persistent snapshot at `/data/omniroute/storage.sqlite`. | |
| - Validates integrity using `sqlite3 "PRAGMA quick_check;"`. | |
| - Restores clean snapshot into `/root/.omniroute/storage.sqlite`. | |
| 2. **Runtime Backup Loop**: | |
| - Every 120 seconds, a background daemon executes `sync_omniroute_db()`. | |
| - Issues `PRAGMA wal_checkpoint(PASSIVE);` and `sqlite3 .backup`. | |
| - Syncs `-wal` and `-shm` sidecars to preserve uncommitted transactions. | |
| - Rotates up to 5 rolling backups in `/data/omniroute/backups/storage-YYYYMMDD-HHMM.sqlite`. | |
| 3. **Shutdown Hook**: | |
| - Shell traps (`trap sync_omniroute_db EXIT INT TERM`) flush runtime state before container termination. | |
| --- | |
| ## 4. Encryption & Security Model | |
| - **AES-256-GCM Encryption**: All provider credentials (API keys, OAuth access tokens, refresh tokens) are encrypted at rest with `STORAGE_ENCRYPTION_KEY`. | |
| - **Secrets Fallback Engine**: If secrets are not passed via Hugging Face Space Secrets during local development, safe default fallbacks prevent container crash: | |
| - `STORAGE_ENCRYPTION_KEY` | |
| - `JWT_SECRET` | |
| - `API_KEY_SECRET` | |
| - `INITIAL_PASSWORD` | |
| - **Path Traversal Gate**: The gateway inspects all requested paths and rejects directory traversal patterns (`..`, `.env`, `.sqlite`, `.git`) with HTTP 403. | |
| --- | |
| ## 5. Process Lifecycle & Self-Healing Supervisor | |
| The container supervisor (`entrypoint.sh`) maintains 24/7 uptime for all background daemons: | |
| ``` | |
| [PID 1 Process Supervisor Loop] | |
| │ (every 5s) | |
| ┌─────────────────────────────┼─────────────────────────────┐ | |
| ▼ ▼ ▼ | |
| [Kill -0 $FASTAPI_PID] [Kill -0 $NGINX_PID] [Kill -0 $OMNIROUTE_PID] | |
| │ │ │ | |
| (Dead? Restart) (Dead? Restart) (Dead? Restart) | |
| python3 -m uvicorn proxy:app nginx -g 'daemon off;' cd /omniroute && node server.js | |
| ``` | |
| - **Fast Gateway Readiness**: FastAPI (`:8000`) and Nginx (`:4096`) start within **300ms**, allowing Hugging Face to report `RUNNING` status instantly. | |
| - **Asynchronous Heavy Boot**: OmniRoute Next.js server, Hermes Agent, Jellyfin, and TG Streamer initialize in parallel background tasks without blocking public ingress. | |