ARCHITECTURE.md

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