Adding opencode files

README.md

@@ -1,5 +1,9 @@
 # kme-content-adapter
 
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Build Status](https://img.shields.io/badge/build-passing-brightgreen)](#)
+
 An HTTP proxy adapter that searches and fetches content from KME (Knowledge Management Engine) and exposes it as a Sitemaps-compliant XML feed and individual HTML article pages. Business logic runs in an isolated Node.js VM sandbox, mirroring the IVA Studio proxy script execution environment.
 
 ## Requirements
@@ -69,16 +73,16 @@ Returns a [Sitemaps protocol 0.9](https://www.sitemaps.org/protocol.html) XML do
 
 Results are paginated automatically using `hydra:view['hydra:last']`. The response is capped at **50,000 URLs** per the Sitemaps protocol.
 
-```
-GET /sitemap.xml?query=temple&size=50&category=vkm:ArticleCategory
+```bash
+curl "http://localhost:3000/sitemap.xml?query=temple&size=50&category=vkm:ArticleCategory"
 ```
 
 ### `GET /?kmeURL=<upstream-article-url>`
 
 Fetches a single KME article by its upstream URL and returns it as a full HTML document.
 
-```
-GET /?kmeURL=https%3A%2F%2F<kme-host>%2Fkm-content-service%2F...
+```bash
+curl "http://localhost:3000/?kmeURL=https%3A%2F%2Fexample.com%2Fkm-content-service%2Farticles%2F123"
 ```
 
 **Response:** `200 text/html; charset=utf-8` — a complete HTML document:
@@ -130,20 +134,68 @@ Tests use the Node.js built-in `node:test` runner. No external test framework.
 
 ## Architecture
 
-The server loads `src/proxyScripts/kmeContentSourceAdapter.js` once at startup via `vm.Script`, then executes it in a **fresh isolated VM context per request** via `vm.createContext`.
+The server loads `src/proxyScripts/kmeContentSourceAdapter.js` once at startup via `vm.Script`, then executes it in a **fresh isolated VM context per request** via `vm.createContext`. This mirrors the IVA Studio proxy script execution environment.
+
+```mermaid
+flowchart TD
+    subgraph Client["Client/Crawler"]
+        A[Request]
+    end
+    
+    subgraph Server["Node.js Server (server.js)"]
+        B[HTTP Request Handler]
+        C[VM Context Per Request]
+    end
+    
+    subgraph ProxyScript["Proxy Script (proxy.js)"]
+        D[Business Logic]
+        E[API Calls via axios]
+        F[Redis Token Cache]
+    end
+    
+    subgraph External["External Services"]
+        G[KME Search API]
+        H[KME Content API]
+        I[OIDC Token Service]
+    end
+    
+    A --> B
+    B --> C
+    C --> D
+    D --> E
+    E --> G
+    E --> H
+    D --> F
+    F --> I
+    
+    style C fill:#e1f5ff,stroke:#0288d1,stroke-width:2px
+    style D fill:#fff3e0,stroke:#fb8c00,stroke-width:2px
+    style F fill:#e8f5e9,stroke:#43a047,stroke-width:2px
+```
+
+### Request Flow
+
+1. **Request arrives** → `server.js` HTTP handler extracts routing metadata (`workspaceId`, `branch`, `route`) from URL params
+2. **VM context created** → Fresh isolated sandbox with injected globals (`console`, `crypto`, `axios`, `jwt`, `redis`, etc.)
+3. **Proxy script executes** → Business logic in `proxy.js` runs, using injected helpers and settings
+4. **Token caching** → OIDC tokens cached in Redis under key `authorization`; stampede guard prevents cache thrashing
+5. **Response returned** → XML sitemap or HTML article rendered via `xmlbuilder2`
+
+### File Structure
 
 ```
 src/
 ├── proxyScripts/
 │   └── kmeContentSourceAdapter.js          # All business logic (zero imports/exports)
 ├── globalVariables/
-│   ├── kme_CSA_settings.json               # Credentials & API config (gitignored)
+│   ├── kme_CSA_settings.json               # Credentials & API config (gitignored, runtime only)
 │   ├── kme_CSA_settings.json.example       # Template for version control
-│   └── kmeContentSourceAdapterHelpers.js   # Pure utilities (literal function body)
+│   └── kmeContentSourceAdapterHelpers.js   # Pure utilities (literal function body pattern)
 ├── logger.js                               # Structured JSON logger
 └── server.js                               # HTTP server bootstrap only
+
 config/
-└── default.json                            # Infrastructure settings
+└── default.json                            # Infrastructure settings (port, host, log level)
 ```
 
 ### VM Context Globals