feat: decouple frontend into its own static service

- web reads API base from window.SPECTRARAG_API_BASE (config.js), default
  same-origin so local + combined deploys are unchanged
- FastAPI CORS from RAG_CORS_ORIGINS, off when unset
- Dockerfile.web + nginx.web.conf: nginx image serving web/, API URL injected
  via --build-arg (not committed)
- ADR 0030

Author: NorthernLightx

Dockerfile.web

@@ -0,0 +1,15 @@
+# Frontend service: a featherweight nginx image serving the static SPA (web/),
+# decoupled from the heavy ML API image. UI changes redeploy in ~minutes (this
+# builds in seconds) instead of rebuilding the multi-GB backend.
+#
+# The API URL is injected at build time (--build-arg API_BASE=https://…) and
+# written into app/config.js, so the prod endpoint stays out of the repo. With
+# no API_BASE the committed config.js (empty → same-origin) is used as-is.
+FROM nginx:1.27-alpine
+COPY web/ /usr/share/nginx/html/
+COPY nginx.web.conf /etc/nginx/conf.d/default.conf
+ARG API_BASE=""
+RUN if [ -n "$API_BASE" ]; then \
+      printf 'window.SPECTRARAG_API_BASE=%s;\n' "\"$API_BASE\"" \
+        > /usr/share/nginx/html/app/config.js; \
+    fi

docs/decisions/0030-frontend-backend-split.md

@@ -0,0 +1,36 @@
+# ADR 0030: Split the frontend off the backend image
+
+Status: accepted
+
+## Context
+
+The SPA (`web/`) was baked into the FastAPI image and served by it. That image
+is ~8 GB (torch, docling, the bge-m3 model, page renders, the embedded Qdrant
+index), so a one-line change to a static `.jsx` file forced a full image
+rebuild + push — roughly an hour — even though the frontend is plain static
+files with no build step (Babel runs in the browser).
+
+## Decision
+
+Serve the frontend as its own Cloud Run service, separate from the API.
+
+- **`spectrarag-web`** — a tiny nginx image (`Dockerfile.web`) that serves
+  `web/`. Builds in seconds; redeploys in ~minutes.
+- **`spectrarag`** (API) — unchanged; rebuilds only when code or deps change.
+- The SPA reads its API base from `window.SPECTRARAG_API_BASE`
+  (`web/app/config.js`), defaulting to same-origin so local dev and the
+  combined deploy keep working untouched. The prod API URL is injected at
+  build time (`--build-arg API_BASE=…`), not committed.
+- The API adds CORS (`CORSMiddleware`, origins from `RAG_CORS_ORIGINS`),
+  enabled only when that env var is set — so same-origin deploys add no CORS.
+
+The deploy specifics (URLs, the build/deploy commands, the CORS origin value)
+are local-only, like the visual-overlay build; this repo keeps the generic
+structure, not the private endpoints.
+
+## Consequences
+
+- Frontend iterations stop touching the ML pipeline — UI deploys in minutes.
+- Two services to operate instead of one (the frontend one is trivial/static).
+- Cross-origin is the one gotcha: the API now needs CORS for the web origin;
+  page images load fine cross-origin via `<img>`.

docs/decisions/README.md

@@ -33,3 +33,4 @@ kept on purpose.
 - [0027](./0027-keyless-demo-chat.md) — Keyless demo chat through a caged server-side OpenRouter key
 - [0028](./0028-persisted-visual-index-cpu-serve.md) — Persisted ColQwen2 page index for CPU serving
 - [0029](./0029-runtime-document-upload.md) — Runtime document upload (flag-gated, text-leg, incremental)
+- [0030](./0030-frontend-backend-split.md) — Split the frontend off the backend image

nginx.web.conf

@@ -0,0 +1,14 @@
+server {
+  listen 8080;
+  server_name _;
+  root /usr/share/nginx/html;
+  index index.html;
+
+  # Build-less SPA: routing is client-side (hash), so any unknown path falls
+  # back to index.html. no-cache forces revalidation so a redeploy of the
+  # static files shows immediately (cheap — they're small text assets).
+  location / {
+    try_files $uri $uri/ /index.html;
+    add_header Cache-Control "no-cache";
+  }
+}

src/api/main.py

@@ -121,6 +121,21 @@ async def lifespan(_: FastAPI) -> AsyncIterator[None]:
     api_key = settings.public_api_key.get_secret_value() if settings.public_api_key else None
     app.middleware("http")(make_api_key_middleware(api_key))
 
+    # CORS only when the frontend is served from a separate origin (decoupled
+    # deploy): origins from RAG_CORS_ORIGINS (comma-separated), empty = same-
+    # origin/no CORS. Added last so it sits outermost and answers the preflight
+    # OPTIONS before the auth middleware can short-circuit it.
+    cors_origins = [o.strip() for o in settings.cors_origins.split(",") if o.strip()]
+    if cors_origins:
+        from fastapi.middleware.cors import CORSMiddleware
+
+        app.add_middleware(
+            CORSMiddleware,
+            allow_origins=cors_origins,
+            allow_methods=["GET", "POST", "OPTIONS"],
+            allow_headers=["*"],
+        )
+
     app.include_router(health.router)
     app.include_router(query.router)
     app.include_router(ingest.router)

src/config/settings.py

@@ -43,6 +43,9 @@ class Settings(BaseSettings):
     # can't be hit by drive-by traffic. Health + OpenAPI metadata routes stay
     # exempt.
     public_api_key: SecretStr | None = None
+    # Comma-separated allowed origins for CORS, set when the frontend is served
+    # from a separate host (decoupled deploy). Empty = same-origin only, no CORS.
+    cors_origins: str = ""
     # ADR 0027: caged OpenRouter key for the keyless demo path (/demo/chat).
     # Deliberately separate from `openrouter_api_key` so it can carry a hard
     # provider-side credit limit and be rotated or killed without touching

web/app/api.js

@@ -9,6 +9,10 @@
    These helpers return data; the components own the rendering. */
 (function () {
   const ORIGIN = window.location.origin;
+  // API base: same-origin by default (local dev + the monolith deploy). When the
+  // frontend is hosted separately, the page sets window.SPECTRARAG_API_BASE to the
+  // API service URL (via a local-only config.js) and every call routes there.
+  const API = window.SPECTRARAG_API_BASE || ORIGIN;
 
   // The real, supported model slate (mirrors the prior chat's <select>).
   // The ":free" entries are the demo chain's models, selectable here so a
@@ -38,7 +42,7 @@
   }
 
   function pageImageUrl(paperId, page) {
-    return `${ORIGIN}/pages/${encodeURIComponent(paperId)}/${encodeURIComponent(paperId)}_p${page}.png`;
+    return `${API}/pages/${encodeURIComponent(paperId)}/${encodeURIComponent(paperId)}_p${page}.png`;
   }
 
   // Pre-rendered figure/table thumbnail (scripts/render_figure_thumbs.py). The
@@ -47,12 +51,12 @@
   // full-page CSS-crop when a thumb is absent (e.g. a freshly uploaded paper).
   function figThumbUrl(paperId, chunkId) {
     const safe = chunkId.replace(/:/g, "_");
-    return `${ORIGIN}/pages/${encodeURIComponent(paperId)}/thumbs/${encodeURIComponent(safe)}.webp`;
+    return `${API}/pages/${encodeURIComponent(paperId)}/thumbs/${encodeURIComponent(safe)}.webp`;
   }
 
   async function loadPapers() {
     try {
-      const r = await fetch("/papers");
+      const r = await fetch(`${API}/papers`);
       return r.ok ? await r.json() : [];
     } catch {
       return [];
@@ -61,7 +65,7 @@
 
   async function loadHealth() {
     try {
-      const r = await fetch("/health");
+      const r = await fetch(`${API}/health`);
       return await r.json();
     } catch {
       return {};
@@ -72,7 +76,7 @@
   // docling role/label. Used by the Figures gallery and the corpus counts.
   async function loadFigures(limit = 1000) {
     try {
-      const r = await fetch(`/figures?limit=${limit}`);
+      const r = await fetch(`${API}/figures?limit=${limit}`);
       return r.ok ? await r.json() : [];
     } catch {
       return [];
@@ -105,7 +109,7 @@
       if (!apiKey) {
         throw new Error("Agentic search runs server-side and needs your OpenRouter key.");
       }
-      const res = await fetch("/query/dci", {
+      const res = await fetch(`${API}/query/dci`, {
         method: "POST",
         headers: { "Content-Type": "application/json", "X-OpenRouter-Key": apiKey },
         body: JSON.stringify(body),
@@ -124,7 +128,7 @@
     // but say which one is happening; give the permanent case a short budget.
     const start = performance.now();
     while (true) {
-      const res = await fetch("/query", {
+      const res = await fetch(`${API}/query`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify(body),
@@ -444,7 +448,7 @@
   // server-side — the browser only sends messages. A 429 means the shared
   // demo quota ran out; callers surface the bring-your-own-key prompt.
   async function streamDemoChat(messages, onDelta) {
-    const res = await fetch("/demo/chat", {
+    const res = await fetch(`${API}/demo/chat`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({ messages }),
@@ -507,7 +511,7 @@
   async function ingestPdf(file) {
     const form = new FormData();
     form.append("file", file);
-    const res = await fetch("/ingest", { method: "POST", body: form });
+    const res = await fetch(`${API}/ingest`, { method: "POST", body: form });
     if (!res.ok) {
       let detail = await res.text();
       try { detail = JSON.parse(detail).detail || detail; } catch { /* keep raw text */ }

web/app/config.js

@@ -0,0 +1,10 @@
+/* Frontend → API base URL.
+
+   Empty string means "same origin" — the default for local dev and the combined
+   (single-service) deploy, so api.js falls back to window.location.origin.
+
+   When the frontend is served from its own host (decoupled deploy), the build
+   overwrites this file with the API service URL — see Dockerfile.web's
+   `--build-arg API_BASE=...`. The URL itself is supplied at build time and is
+   not committed. */
+window.SPECTRARAG_API_BASE = "";

web/index.html

@@ -18,6 +18,7 @@
   <script src="https://unpkg.com/react-dom@18.3.1/umd/react-dom.development.js" integrity="sha384-u6aeetuaXnQ38mYT8rp6sbXaQe3NL9t+IBXmnYxwkUI2Hw4bsp2Wvmx4yRQF1uAm" crossorigin="anonymous"></script>
   <script src="https://unpkg.com/@babel/standalone@7.29.0/babel.min.js" integrity="sha384-m08KidiNqLdpJqLq95G/LEi8Qvjl/xUYll3QILypMoQ65QorJ9Lvtp2RXYGBFj1y" crossorigin="anonymous"></script>
 
+  <script src="app/config.js"></script>
   <script src="app/api.js"></script>
   <script type="text/babel" src="app/shared.jsx"></script>
   <script type="text/babel" src="app/tweaks-panel.jsx"></script>