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