ArchitectureAdrADR-0017: Adoption of CheckEye Architecture (Voice & Security)

ADR-0017: Adoption of CheckEye Architecture (Voice & Security)

ADR-0017: Adoption of CheckEye Architecture (Voice & Security)

Date: 2026-01-10 Status: ACCEPTED Context: Post-CheckEye Analysis Components: Voice Gateway, UI Filter, Vertex Pipe

1. Context

Analysis of the CheckEye Assistant artifacts revealed superior architectural patterns for Voice (Latency/Interruptibility) and Enterprise UX (Kiosk Mode) compared to the standard OpenAI-based implementation in Jorvis.

2. Decision

We will adopt the following CheckEye patterns for Jorvis v0.6.2:

A. "Voice Gateway" (Gemini Live) — Dual-Mode

  • Strategy: Run CheckEye Voice Gateway alongside Open WebUI native voice.
  • Rationale: A/B testing to determine best production solution.
  • Adopt: A dedicated voice-gateway Microservice (Port 8787) as optional profile.
  • Protocol: WebSocket (bi-directional, interruptible).
  • Client: CheckEye Voice Open WebUI Function (Client-side WebSocket handler).
  • Default: Open WebUI native voice remains default; gateway is opt-in via JORVIS_VOICE_MODE=gateway.

B. "Kiosk Mode" (UI Hardening)

  • Problem: Default Open WebUI exposes too many settings (Temperature, Models, System Prompt) to end-users.
  • Adopt: checkeye_voice_filter (Python Valve).
  • Mechanism: Injects CSS/JS to hide settings-button, model-selector, and controls.

C. Native Vertex Identity

  • Replace: GEMINI_API_KEY (User/API Key).
  • Adopt: GOOGLE_APPLICATION_CREDENTIALS (Service Account JSON).
  • Benefit: Audit logging, strict IAM scopes, Search Grounding support.

3. Consequences

  • Deployment: Requires voice-gateway container in docker-compose.yaml.
  • Config: Requires mounting GCP Service Account JSON into containers.
  • UX: Non-admin users will lose access to settings (Intentional).

4. Nuance & Rejection

  • Accepted: Voice Gateway (Ephemeral Tokens), Kiosk Mode, Vertex Auth.
  • Rejected: Apache Tika (Too heavy for Cloud Run demo; stick to Node/Python parsers for Task-088).

5. Implementation Plan

  1. Task-092: Deploy Voice Gateway (Dual-Mode) — optional Docker profile.
  2. Task-093: Import CheckEye Functions (Filter + Pipe) — Kiosk Mode.
  3. Task-094: Configure Service Account Auth (Vertex Identity).

6. Approval

  • Accepted by: George (User/Product Owner)
  • Date: 2026-01-10
  • Rationale: Dual-mode allows A/B testing before full commitment.