Enhnace Code Archiecture

Author: Mohammed-coder-dev

.env.example

@@ -0,0 +1,28 @@
+# OmanX example environment variables
+# Copy to .env and fill values before running in production
+
+# OpenAI API (optional for degraded mode)
+OPENAI_API_KEY=
+OPENAI_MODEL=gpt-4o-mini
+
+# Node environment
+NODE_ENV=development
+
+# Rate limiting: max requests per 15 minutes
+RATE_LIMIT_MAX=120
+
+# Admin key for admin endpoints in production
+ADMIN_KEY=
+
+# Comma-separated allowed origins for CORS (leave blank for open during dev)
+ALLOWED_ORIGINS=
+
+# Knowledge reload interval (ms)
+KNOWLEDGE_RELOAD_MS=30000
+
+# Cache settings
+CACHE_TTL_MS=600000
+CACHE_MAX_ENTRIES=500
+
+# Optional logging level: debug, info, warn, error
+LOG_LEVEL=debug

.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: CI
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [18.x]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+      - name: Install dependencies
+        run: npm ci
+      - name: Syntax checks
+        run: |
+          node --check server.js || true
+          node --check router.js || true
+          node --check localResponder.js || true
+          node --check app.js || true
+      - name: Run package tests
+        run: npm test
+      - name: Lint (optional)
+        run: |
+          if [ -f package.json ]; then
+            if npm run | grep -q lint; then
+              npm run lint || true
+            fi
+          fi

.gitignore

@@ -1,2 +1,11 @@
-node_modules
-.env
+node_modules/
+.env
+.env.local
+
+# OS
+.DS_Store
+
+# Logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

README.md

@@ -30,6 +30,13 @@ RATE_LIMIT_MAX=120
 ADMIN_KEY=optional_admin_key
 ```
 
+You can use the provided example environment file as a starting point:
+
+```bash
+cp .env.example .env
+# then edit .env to add your OPENAI_API_KEY and other values
+```
+
 ## Deployment (Vercel)
 This repository is configured for Vercel (`vercel.json`).
 

app.js

@@ -52,7 +52,28 @@ const createMessage = (role, text, meta = "") => {
   if (meta) {
     const metaEl = document.createElement("div");
     metaEl.className = "message-meta";
-    metaEl.textContent = meta;
+
+    // Render KB refs as clickable links when present: "... • Refs: ID1, ID2"
+    const refsMatch = /Refs:\s*(.+)$/i.exec(meta);
+    if (refsMatch) {
+      const before = meta.slice(0, refsMatch.index).trim();
+      if (before) metaEl.appendChild(document.createTextNode(before + " "));
+
+      const ids = refsMatch[1].split(/\s*,\s*/).filter(Boolean);
+      ids.forEach((id, idx) => {
+        const a = document.createElement('a');
+        a.href = apiUrl(`/kb/${encodeURIComponent(id)}`);
+        a.target = '_blank';
+        a.rel = 'noopener noreferrer';
+        a.className = 'kb-ref';
+        a.textContent = id;
+        metaEl.appendChild(a);
+        if (idx < ids.length - 1) metaEl.appendChild(document.createTextNode(', '));
+      });
+    } else {
+      metaEl.textContent = meta;
+    }
+
     bubble.appendChild(metaEl);
   }
 
@@ -125,6 +146,16 @@ const sendMessage = async (message) => {
     const payload = await response.json().catch(() => null);
 
     if (!response.ok) {
+      // If the server returned a helpful `text` field, show it to the user instead
+      const serverText = payload?.text || payload?.error;
+      if (serverText) {
+        const laneMeta = payload?.lane === "strict" ? "Compliance mode • Verified KB only" : "Community mode";
+        const refs = Array.isArray(payload?.kbRefs) && payload.kbRefs.length ? ` • Refs: ${payload.kbRefs.join(", ")}` : "";
+        addMessage("bot", serverText, `${laneMeta}${refs}`);
+        setStatus("online", "Online");
+        return;
+      }
+
       setStatusBanner(response.status === 404 ? API_BASE_ERROR_MESSAGE : DEFAULT_OFFLINE_MESSAGE);
       throw new Error(payload?.error ? `${payload.error} (HTTP ${response.status})` : `Request failed: HTTP ${response.status}`);
     }

package.json

@@ -7,7 +7,7 @@
   "scripts": {
     "start": "node server.js",
     "dev": "NODE_ENV=development node server.js",
-    "test": "node --check server.js && node --check router.js && node --check localResponder.js && node --check app.js"
+    "test": "node test/smoke.js"
   },
   "engines": {
     "node": ">=18.0.0"

server.js

@@ -83,6 +83,20 @@ if (!OPENAI_API_KEY) {
   logger.warn("OPENAI_API_KEY is missing. Chat responses will use safe fallback guidance only.");
 }
 
+// In production, require ADMIN_KEY and ALLOWED_ORIGINS to be explicitly configured
+if (IS_PROD) {
+  if (!ADMIN_KEY) {
+    logger.error("ADMIN_KEY is required in production. Set ADMIN_KEY in environment.");
+    // Fail fast in production to avoid accidentally exposing admin endpoints.
+    process.exit(1);
+  }
+
+  if (!ALLOWED_ORIGINS.length) {
+    logger.error("ALLOWED_ORIGINS must be set in production to restrict CORS.");
+    process.exit(1);
+  }
+}
+
 // -----------------------------
 // OpenAI client
 // -----------------------------
@@ -209,7 +223,19 @@ app.set("trust proxy", 1);
 // Security headers
 app.use(
   helmet({
-    contentSecurityPolicy: false,
+    // In production enable a reasonable CSP; disable only when developing locally.
+    contentSecurityPolicy: IS_PROD
+      ? {
+          directives: {
+            defaultSrc: ["'self'"],
+            scriptSrc: ["'self'"],
+            styleSrc: ["'self'", "https:"] ,
+            imgSrc: ["'self'", 'data:'],
+            connectSrc: ["'self'"],
+            frameAncestors: ["'self'"],
+          },
+        }
+      : false,
     crossOriginEmbedderPolicy: false,
   })
 );
@@ -221,9 +247,7 @@ app.use(
       // allow same-origin / curl / server-to-server requests
       if (!origin) return cb(null, true);
 
-      // if not configured, default open for MVP
-      if (!ALLOWED_ORIGINS.length) return cb(null, true);
-
+      // In production ALLOWED_ORIGINS is required (validated at startup).
       if (ALLOWED_ORIGINS.includes(origin)) return cb(null, true);
       return cb(new Error(`CORS blocked: ${origin}`), false);
     },
@@ -254,7 +278,8 @@ app.use(
     stream: {
       write: (msg) => logger.info(msg.trim()),
     },
-    skip: () => IS_PROD === false,
+    // In development we want request logs visible. Only skip morgan in production.
+    skip: () => IS_PROD === true,
   })
 );
 
@@ -351,6 +376,29 @@ app.get("/metrics", (req, res) => {
   });
 });
 
+// Serve knowledge base entry (simple JSON) for frontend citations
+app.get('/kb/:id', (req, res) => {
+  try {
+    const kb = knowledge.getJson();
+    if (!kb) return res.status(503).json({ error: 'Knowledge base not available' });
+
+    const id = req.params.id;
+    let entry = null;
+
+    if (Array.isArray(kb.documents)) {
+      entry = kb.documents.find((d) => d.id === id);
+    } else if (kb[id]) {
+      entry = kb[id];
+    }
+
+    if (!entry) return res.status(404).json({ error: 'KB entry not found' });
+    return res.json({ id, entry });
+  } catch (e) {
+    logger.error('KB fetch error', { error: e?.message || String(e) });
+    return res.status(500).json({ error: 'KB lookup failed' });
+  }
+});
+
 // -----------------------------
 // Admin endpoints
 // - In production: requires ADMIN_KEY via x-admin-key header OR {adminKey} body
@@ -378,6 +426,30 @@ app.post("/admin/knowledge/reload", requireAdmin, async (req, res) => {
   }
 });
 
+// Admin: upload new knowledge JSON (protected in production)
+app.post('/admin/knowledge/upload', requireAdmin, express.json({ limit: '1mb' }), async (req, res) => {
+  try {
+    const payload = req.body;
+    if (!payload || (typeof payload !== 'object')) {
+      return res.status(400).json({ ok: false, error: 'Invalid JSON payload', requestId: req.requestId });
+    }
+
+    // Basic validation: must contain metadata and documents OR be object-based
+    const hasDocs = Array.isArray(payload.documents) && payload.documents.length > 0;
+    const hasObj = Object.keys(payload).length > 0 && (payload.metadata || hasDocs);
+    if (!hasDocs && !hasObj) {
+      return res.status(400).json({ ok: false, error: 'Knowledge JSON missing required fields', requestId: req.requestId });
+    }
+
+    await fs.writeFile(KNOWLEDGE_PATH, JSON.stringify(payload, null, 2), 'utf8');
+    await knowledge.load(true);
+    return res.json({ ok: true, updated: true, requestId: req.requestId });
+  } catch (e) {
+    logger.error('KB upload failed', { error: e?.message || String(e) });
+    return res.status(500).json({ ok: false, error: 'KB upload failed', requestId: req.requestId });
+  }
+});
+
 // -----------------------------
 // Chat endpoint - UNIFIED MODE
 // Body: { message: string, stream?: boolean }
@@ -639,8 +711,13 @@ app.use((err, req, res, _next) => {
     error: err?.message || String(err),
     stack: err?.stack,
   });
+  const userMessage = IS_PROD
+    ? "Server error. Please try again later or contact support."
+    : (err?.message || "Error") + (err?.stack ? `\n${err.stack}` : "");
+
   res.status(500).json({
     error: IS_PROD ? "Internal server error" : (err?.message || "Error"),
+    text: userMessage,
     requestId: req.requestId,
   });
 });

test/smoke.js

@@ -0,0 +1,58 @@
+import { spawn } from 'child_process';
+
+const PORT = process.env.PORT || 3001;
+const SERVER_URL = `http://localhost:${PORT}`;
+
+function sleep(ms) { return new Promise((r) => setTimeout(r, ms)); }
+
+(async () => {
+  console.log('Starting smoke test...');
+
+  const server = spawn(process.execPath, ['server.js'], {
+    env: { ...process.env, PORT: String(PORT) },
+    stdio: ['ignore', 'inherit', 'inherit'],
+  });
+
+  try {
+    // wait for /health to be OK
+    const deadline = Date.now() + 15_000;
+    let healthy = false;
+    while (Date.now() < deadline) {
+      try {
+          const r = await fetch(`${SERVER_URL}/health`);
+        if (r.ok) {
+          healthy = true;
+          break;
+        }
+      } catch (e) {
+        // ignore
+      }
+      await sleep(500);
+    }
+
+    if (!healthy) throw new Error('Server did not become healthy in time');
+    console.log('Server healthy. Running chat test...');
+
+    const r2 = await fetch(`${SERVER_URL}/chat`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ message: 'What are the steps to get OPT?' }),
+    });
+
+    if (!r2.ok) {
+      const txt = await r2.text().catch(() => '');
+      throw new Error(`Chat endpoint failed: ${r2.status} ${txt}`);
+    }
+
+    const payload = await r2.json();
+    if (!payload || !payload.text) throw new Error('Chat returned no text');
+
+    console.log('Chat returned text, kbRefs:', payload.kbRefs || []);
+    console.log('Smoke test passed.');
+  } catch (e) {
+    console.error('Smoke test failed:', e?.message || String(e));
+    process.exitCode = 2;
+  } finally {
+    try { server.kill(); } catch {}
+  }
+})();