From bf489189814fd9bcd1821a44dfe7ea1142cf77fb Mon Sep 17 00:00:00 2001
From: Timothy Oluwatobi Ojebiyi <tobiojebiyi@gmail.com>
Date: Sat, 10 Oct 2026 23:41:53 +0100
Subject: [PATCH] docs: document API_URL for running the frontend without nginx

The frontend's /api proxy needs API_URL when nginx is not in front
(npm run dev, Vercel). Add it to the README's environment table and
local-dev steps, and as a commented entry in .env.example.
---
 .env.example | 5 +++++
 README.md    | 5 ++++-
 2 files changed, 9 insertions(+), 1 deletion(-)

diff --git a/.env.example b/.env.example
index 164bc5b..2c04c68 100644
--- a/.env.example
+++ b/.env.example
@@ -32,3 +32,8 @@ ADZUNA_API_KEY=your_adzuna_api_key
 
 # Job-site login credentials are set per user on the Profile page (stored encrypted with
 # CREDENTIALS_KEY) — they are not configured here.
+
+# Frontend only — NOT read from this file and not needed with Docker Compose (nginx routes
+# /api to the API). When the frontend runs without nginx (npm run dev, Vercel), its /api
+# proxy forwards to API_URL: set it in frontend/.env or the Vercel project's env vars.
+# API_URL=http://localhost:8000
diff --git a/README.md b/README.md
index 2795379..b0e2145 100644
--- a/README.md
+++ b/README.md
@@ -94,9 +94,11 @@ Local (non-Docker) dev:
 
 ```bash
 cd api && uvicorn app.main:app --reload      # needs the env vars above, the data files and a reachable Ollama
-cd frontend && npm run dev
+cd frontend && npm run dev                   # needs API_URL (below)
 ```
 
+**Frontend without nginx** (`npm run dev`, Vercel): the browser calls `/api/*` on the frontend's own origin, and `frontend/src/app/api/[...path]/route.ts` forwards those calls to `API_URL`. Set it to the API's base URL — for local dev, put `API_URL=http://localhost:8000` in `frontend/.env` (git-ignored); on Vercel, add it to the project's environment variables. Without it every `/api/*` call returns 503. Under Docker Compose nginx routes `/api` straight to the API, so `API_URL` isn't needed. On Vercel, streamed responses (analysis, the apply session) end at the function duration limit.
+
 ---
 
 ## Environment Variables
@@ -113,6 +115,7 @@ cd frontend && npm run dev
 | `BRAVE_SEARCH_API_KEY` | Optional | Enables the Brave `site:` search job source |
 | `ECONOMIC_INDEX_PATH` / `TASK_PENETRATION_PATH` | No | Data file paths (default `/data/...`) |
 | `APP_DATA_PATH` | No | SQLite DBs, PDFs and uploaded CVs (compose: `/appdata`) |
+| `API_URL` | Frontend, without nginx | Base URL of the API that the frontend's `/api/*` proxy forwards to (e.g. `http://localhost:8000`). Set in the frontend's environment, not the root `.env`; not needed under Docker Compose |
 
 Job-site login details are set per user on the Profile page, not via env vars.