From 55d798b45f35f23aaa7986fd6c6d9b4959c484f7 Mon Sep 17 00:00:00 2001
From: Gitead <uclach@hotmail.com>
Date: Thu, 30 Jul 2026 23:52:37 -0400
Subject: [PATCH] docs: add Google Cloud Vision setup section to root README
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Fresh-machine setup guide didn't cover the Payment OCR Service's Google
Vision credentials — add it as its own section (enable API, create
service-account key, install as google_credentials.json, verify).
---
 README.md | 49 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)

diff --git a/README.md b/README.md
index 8ec75bf3..7785cc23 100644
--- a/README.md
+++ b/README.md
@@ -839,6 +839,55 @@ since it fixes every device on the network in one place instead of requiring a h
 
 ---
 
+## Payment OCR Service Setup (Google Cloud Vision)
+
+The Payment OCR Service (`apps/PaymentOCRService`, port 5003) uses Google Cloud Vision to read
+payment/EOB documents and to locate exact text positions for the Windows Type Agent. It needs a
+Google Cloud service-account key that is **not** included in the repo (it's a live secret and is
+gitignored on purpose) — each PC needs its own copy placed locally.
+
+### Step 1 — Enable the Cloud Vision API
+
+1. Go to `console.cloud.google.com` and select (or create) the project this service should use
+2. **APIs & Services → Library** → search for **"Cloud Vision API"** → click **Enable**
+   (skip if already enabled)
+
+### Step 2 — Create a service account key
+
+1. **IAM & Admin → Service Accounts** → either pick an existing service account for this app,
+   or **Create Service Account** (any name, e.g. `ocr-service`; no special roles needed beyond
+   default — Vision API access comes from the API being enabled on the project, not a role grant)
+2. Open that service account → **Keys** tab → **Add Key → Create new key → JSON**
+
+This immediately downloads a `.json` file to your browser's Downloads folder — **this is the
+only time the private key content is shown**, so keep the file safe (a password manager or
+secure backup, not just Downloads).
+
+### Step 3 — Install the key on this PC
+
+Move the downloaded file into `apps/PaymentOCRService/` and rename it to exactly
+`google_credentials.json` — this is the filename `apps/PaymentOCRService/.env` already expects:
+
+```sh
+mv ~/Downloads/<your-downloaded-file>.json apps/PaymentOCRService/google_credentials.json
+```
+
+> `google_credentials.json` is gitignored on purpose — **never commit it**. If a key is ever
+> accidentally exposed (committed, pasted, screenshotted), go back to the Keys tab in Step 2 and
+> delete it, then generate a new one.
+
+### Step 4 — Verify
+
+With the service running (Step 15 above starts it as part of `npm run dev`, or run it directly —
+see `apps/PaymentOCRService/README.md`):
+
+```sh
+curl localhost:5003/health
+# should report "GOOGLE_APPLICATION_CREDENTIALS set: True"
+```
+
+---
+
 ## Twilio In-Browser Calling Setup (Dial Pad)
 
 The dial pad on the Patient Connection page lets staff make real phone calls directly through the browser (mic + speaker) using Twilio Voice SDK. One-time setup is required in the Twilio Console.