Technical Integration View

Architecture — Security — Integration Guide for IT & Focus Vendor
Technical Documentation
⚠ Architecture Notice: This page describes the technical architecture for both the current prototype and the future production integration with Focus ERP. The prototype does not connect to Focus ERP directly.

1. Production Architecture (Future — Focus ERP Integration)

Focus ERP
←
Read-only
API / SQL View
←
Backend Server
(Node.js)
←
Gemini API
←
Dashboard
(Frontend)

Data flows in one direction only: Focus ERP → API/SQL View → Backend → Gemini → Dashboard. The backend is the only component that communicates with both the data source and Gemini API. The frontend never directly accesses Focus ERP or Gemini.

Why a Backend Is Required

  • API key protection: The Gemini API key must never be exposed to the browser.
  • Data transformation: Data from Focus ERP must be cleaned, transformed, and minimised before being sent to Gemini.
  • Audit trail: All AI analysis requests must be logged and auditable.
  • Access control: The backend enforces role-based access control in production.

Data Minimisation Rules

  • Only relevant reject fields are sent to Gemini — no PII, no financial codes.
  • Batch-level details are aggregated to case level before AI processing.
  • Gemini receives no inventory quantity or location data beyond what is needed for risk scoring.

2. Current Prototype Architecture

Excel File
←
Local Backend
(backend/server.js)
←
Gemini API
or
Simulated AI
←
Dashboard
(Frontend)

The prototype now runs as a secure backend-served dashboard:

  • Backend Mode: Run npm start to start backend/server.js on port 3000. It reads the Excel file, optionally calls Gemini API, and returns data to the frontend.
  • Demo Fallback: If the Excel file is missing or unreadable, the backend serves safe demo records from the data service.

3. Security Model

  • API Key Protection: The Gemini API key is stored in .env on the server only. It is never in HTML, CSS, or browser-side JavaScript. Even if someone inspects the page source, the API key cannot be found.
  • No Direct Database Access: The frontend never connects to Focus ERP or the Excel file directly. All data passes through the backend.
  • Read-Only Access: The prototype has no write capability to Focus ERP or any data source. This is intentional and prevents accidental data changes.
  • Role-Based Access (Future): In production, access to specific views will be controlled by user roles (Executive, Finance, QC, IT).
  • HTTPS Required (Future): All communication between the dashboard and backend must use HTTPS in production.

4. Future Focus ERP Integration Options

Option 1 — Focus API (Recommended)

If Focus ERP provides a REST or SOAP API, the backend can pull reject data directly. This is the cleanest approach and supports real-time or near-real-time updates. The backend would call the Focus API on a schedule (e.g., every 5 minutes) or on-demand.

Option 2 — Read-Only SQL View

If Focus uses a SQL database, create a read-only SQL view that exposes only the required reject and destruction fields. The backend connects to this view with a read-only database account. This is secure and does not risk modifying Focus data.

Option 3 — Scheduled Excel/CSV Export

The simplest integration: schedule Focus ERP to export reject data to a shared location (e.g., network folder or SFTP server) as CSV or Excel. The backend reads the latest file on a schedule. This is the least real-time option but the easiest to implement initially.

5. API Endpoints (Current Prototype)

GET /api/health Returns server status, data source, whether Gemini is configured, Excel file status, whether auth is required, and Focus API configuration status. POST /api/login Validates a dashboard access token against DASHBOARD_TOKEN in .env. Body: { "token": "your-token" } Returns { success: true/false } GET /api/rejects Returns the full list of reject records (requires auth if DASHBOARD_TOKEN is set). Optional query params: ?source=excel (force Excel) | ?source=demo (force demo) ?department=Warehouse (filter by department, comma-separated) ?risk_level=Critical,High (filter by risk level) ?status=Pending (filter by approval status) ?from_date=2026-01-01 (filter by start date) ?to_date=2026-05-01 (filter by end date) ?search=tape (search item name, doc no, or reason) GET /api/summary Returns AI-generated or locally computed analysis summary including risk level, costs, root causes, anomalies, and predictive cost projection. Supports the same filter query params as /api/rejects. GET /api/anomalies Returns anomaly detection results — items with unusually high cost contribution (>3x average, minimum SAR 10,000). Useful for spotting abnormal rejection patterns. GET /api/root-causes Returns grouped root cause data with counts and percentages. GET /api/capa-suggestions Returns CAPA suggestions generated by AI or local analysis. GET /api/finance-alerts Returns finance-sensitive high-value reject alerts requiring finance review. GET /api/ai-analysis Comprehensive AI analysis endpoint. Returns both reject records and full analysis (executive summary, risk data, anomalies, predictive cost, CAPA, actions). Uses cached Gemini results (5-minute TTL) if available. Falls back to local simulation. POST /api/run-analysis Triggers a full AI analysis (Gemini if configured, otherwise simulated). Returns executive summary, risk data, anomalies, predictive cost, CAPA suggestions, and management actions. Results are cached for 5 minutes. GET /api/audit-log Returns the last 100 audit log entries (requires auth). Each entry contains: timestamp, IP address, action, and optional details.

6. UAT Checklist

  • ✓ Static mode: Open index.html directly — all data renders correctly
  • ✓ Backend mode: npm install && npm start — server starts without errors
  • ✓ API health check: GET /api/health returns 200 with valid JSON
  • ✓ Filter bar: Department, risk level, status, date range, and search filters work
  • ✓ Anomaly detection: Items with >3x average cost flagged and displayed
  • ✓ Predictive cost: 30-day projection calculated from daily average
  • ✓ Token-based auth: Login page, token validation, and 401 redirect work
  • ✓ Audit log: /api/audit-log returns entries and file-based logging works
  • ✓ Gemini cache: Results cached for 5 minutes, cache_age_seconds in response
  • ✗ Excel file loaded: Verify Excel data maps to reject records correctly
  • ✗ Gemini integration: Test with valid API key — analysis returns expected JSON structure
  • ✓ Graceful fallback: Remove Excel file — verify demo data loads automatically
  • ✓ Graceful fallback: Remove API key from .env — verify simulated AI runs
  • ✓ All 6 pages render with correct navigation and no broken links
  • ✓ RTL layout verified across all pages on desktop and mobile
  • ✓ No API keys exposed in frontend code or browser developer tools

7. Go-Live Readiness Checklist

  • ✗ Focus ERP integration confirmed (API, SQL view, or scheduled export)
  • ✗ Backend deployed to secure server with HTTPS enabled
  • ✗ Gemini API key configured in server environment (not in code)
  • ✗ DASHBOARD_TOKEN changed from default to a strong, unique value
  • ✗ Role-based access control implemented and tested
  • ✗ Data minimisation rules verified and documented
  • ✗ Audit logging enabled and verified for all API requests
  • ✗ FOCUS_API_URL and FOCUS_API_TOKEN configured for live data
  • ✗ User acceptance testing completed with real Focus data
  • ✗ Disaster recovery and backup plan documented
  • ✗ Training completed for all user roles (Executive, Finance, QC, IT)
  • ✗ SOP updated to include dashboard in reject and destruction workflow
  • ✗ Performance tested with full Focus ERP data volume
⚠ Important: This prototype is for demonstration and concept validation only. Production deployment requires proper security review, load testing, and Focus ERP integration validation. The architecture described here is subject to change based on Focus ERP capabilities and IT infrastructure.