BizGaze_Remote/CLAUDE.md

# BizGaze Connect — project brief

Place this file at the repo root (`remote-access-app/CLAUDE.md`). Claude Code reads
it automatically each session.

## What this is
**BizGaze Connect** — a no-install, browser-based remote support / screen-sharing
tool for the BizGaze ecosystem. A customer opens a page, gets a 6-digit code; a
signed-in BizGaze agent enters the code, the customer taps Allow, and the agent
sees the customer's screen with two-way voice + chat. Live at **remote.bizgaze.com**.
Roadmap: grow into a communication platform (meetings + persistent chat) for
registered BizGaze users.

## Tech stack (intentionally minimal — keep it this way)
- **Node.js >= 22.5**. npm deps: `ws`, `pg`, `redis`, `web-push` (+ optional `nodemailer`).
- **PostgreSQL** via the async adapter (`server/dbx.js` → `server/db/pg.js`). SQLite was RETIRED 2026-08-12:
  there is now ONE schema source of truth, **`server/db/schema.pg.sql`** — every schema change goes there
  (and post-cutover COLUMNS need an explicit `ALTER TABLE … ADD COLUMN IF NOT EXISTS`, since the file is
  applied idempotently on every boot and `CREATE TABLE IF NOT EXISTS` won't alter an existing table).
- **WebRTC** peer-to-peer for media (screen video + voice + data channels).
- **No build step, no framework.** Each page is a single self-contained HTML file
  with inline `<style>` and `<script>`. Do not introduce React/bundlers.
- Auth: scrypt password hashing, HttpOnly session cookie. (SSO migration in progress.)

## Repo layout
```
server/
  server.js      # thin entry: HTTP dispatch + WS attach + listeners (HTTP/HTTPS)
  config.js      # env + filesystem paths (PORT, dirs, SESSION_TTL)
  lib.js         # HTTP helpers: json / readBody / parseCookies / now
  session.js     # currentUser (cookie -> user) + audit()
  presence.js    # shared in-memory live state (onlineAgents/liveSessions/pendingShares)
  routes.js      # HTTP JSON API (/api/*, /sso) -> { "METHOD /path": handler } map
  static.js      # static file serving + authenticated recording/transcript downloads
  signaling.js   # WebSocket signaling (consent + SDP/ICE relay)
  repos.js       # data-access layer — ALL SQL lives here (tenant-scoped, async)
  bizgaze.js     # BizGaze identity provider (validate login, env-gated)
  dbx.js         # async DB adapter facade -> db/pg.js (Postgres; only backend)
  db/pg.js       # Postgres backend; db/schema.pg.sql = the single schema source of truth
  auth.js        # scrypt hashing, token/id generation, TOTP helpers
  package.json   # { "dependencies": { "ws": "^8.18" }, engines node>=22.5 }
  test/e2e.js    # 21-check backend e2e (register->login->session->signaling->audit)
  public/
    index.html    # public landing (Log in with BizGaze / share without login)
    home.html     # post-login shell: chat rail + Share/Connect (iframe) + Meeting (/home)
    dashboard.html# login + role-scoped session report (/dashboard, replaces /console)
    connect.html  # agent: enter code, view screen, control bar (/connect)
    share.html    # customer: get code, share screen (/share)
    home-mockup.html # locked design reference for home
    logo.png
  recordings/    # saved session recordings (.webm)  [created at runtime]
  transcripts/   # saved transcripts (.txt)           [created at runtime]
```
Architecture/roadmap detail lives in `ARCHITECTURE.md`. Backend SQL must go through
`repos.js` (never inline in routes/signaling). ANY schema change goes in `db/schema.pg.sql` (see stack note).
After backend edits, run the tests against a DISPOSABLE Postgres (they no longer bundle SQLite):
`DATABASE_URL=postgres://…/bizgaze_test node test/db-smoke.js`.

## Run locally
```
# Start a local Postgres (or use the compose one), then:
docker compose up -d bizgazepg
cd server && npm install
DB_BACKEND=pg DATABASE_URL=postgres://bizgaze:bizgaze_local@localhost:5432/bizgaze node server.js
# HTTP on :8090 (HTTPS on :8443 only if cert.pem + key.pem exist in server/)
# Env: ALLOW_REGISTRATION=1 opens the first-team registration
```
First registered user becomes admin; registration then closes (unless ALLOW_REGISTRATION=1).

## Key HTTP routes (server.js)
- `POST /api/register|login|logout`, `GET /api/me`, `GET/POST /api/users`,
  `POST /api/users/manage`, `GET /api/setup-state`, `GET /api/report`
- `GET /api/ice` — returns STUN, plus managed TURN **only for mobile clients**
  (TURN creds come from env: `TURN_URLS`, `TURN_USERNAME`, `TURN_CREDENTIAL`)
- `POST /api/recording?sessionId=` / `POST /api/transcript?sessionId=` — uploads
- `GET /recordings/<sid>.webm` / `GET /transcripts/<sid>.txt` — authed downloads (streamed w/ Content-Length)
- `GET /sso?token=` — SSO entry (HMAC today; JWT migration planned)
- Page routes: `/`, `/console`, `/connect`, `/share`

## WebSocket signaling (`/ws`)
`liveSessions` map (sessionId -> {agentWs, viewerWs, ...}). Message cases:
`agent-hello`, `viewer-connect`, `consent`, `share-create`, `code-connect`,
`offer`/`answer`/`ice-candidate` (relayed peer-to-peer), `recording`, `transcript`,
`end-session`. Keepalive ping every 25s. Media never traverses the server.

## Current features (all working on desktop)
- Code-based no-install screen share (customer shares, agent views).
- Two-way voice; in-session chat (logged-in sharer's name shown).
- **Session recording**: agent presses Record; mixes customer screen + both voices;
  uploads `.webm`; downloadable from the report. Customer sees a "being recorded"
  banner + live timer.
- **Auto-transcript**: each side runs Web Speech API on its own mic; lines stream to
  the agent; combined `.txt` (voices + chat) uploaded; downloadable from the report.
- **Session report**: filter by agent/date, CSV + PDF export, pagination (5/page),
  agent search, recording/transcript download links.
- Agent management (admin invites, roles admin/technician/viewer), remember-me,
  case-insensitive email, password show/hide, session-end webhook to BizGaze.

## Hard constraints (do not try to "fix" these)
- **Mobile browsers CANNOT share their screen.** Android Chrome and iOS Safari do
  not expose `getDisplayMedia` screen capture to web pages. Only a native app can
  capture a phone screen. The share page detects mobile and shows a clear message.
  (Desktop screen share works fully.)
- Screen capture requires a user gesture → `getDisplayMedia` is called directly from
  the customer's "Allow" tap (see share.html `beginCapture`).
- Recording/transcript use browser MediaRecorder + Web Speech API → Chrome/Edge only.

## Production
- `remote.bizgaze.com`, Linux, Docker, behind a reverse proxy.
- Proxy MUST: upgrade `/ws` with long timeouts; allow large bodies on
  `/api/recording`; not buffer `/recordings/` downloads. (See IT-HANDOFF-PROXY.md.)
- Env vars: `TURN_URLS`, `TURN_USERNAME`, `TURN_CREDENTIAL` (Metered TURN),
  `SSO_SECRET`, `BIZGAZE_WEBHOOK_URL`, `BIZGAZE_LOGIN_URL` (identity provider for `/api/login`),
  `ALLOW_REGISTRATION`, `DB_PATH`, `PORT`, `HTTPS_PORT`.

## In progress / roadmap
1. **SSO with BizGaze** (active): BizGaze becomes the identity provider. It issues a
   signed token; `/sso` verifies it and creates a local session. Supports both
   "from inside BizGaze" and a "Log in with BizGaze" button at our URL. Waiting on
   the dev team for: shared secret, token format (JWT preferred), SSO start URL,
   signup URL, role mapping. (See BizGaze-Connect-SSO-SPEC.md.)
2. **New post-login home (NEXT TASK)** — see below.
3. **Persistent chat** — 1:1 messaging is BUILT (messages table, `/api/v1/messages/*`, live delivery
   over `/ws` via `chat-hello`/`chat-message`, wired into home.html). Group chat is the remaining part.
4. **Meetings** (multi-party video) — **mesh (P2P) MVP BUILT**: in-memory rooms + signaling
   (`meeting-create/join/signal/leave` in signaling.js), video-grid UI in home.html's Meeting tab
   (start/join by 6-digit code, mic/cam toggles, leave). Good for small groups; **SFU upgrade** is
   the next step for larger rooms.
5. **Downloadable Android app** — the only way to support phone screen-sharing.

## NEXT TASK: new post-login home (start with a mockup)
After login, replace the current dashboard with a BizGaze Connect "home":
- **Left sidebar (Slack-style):** list of recent chats/contacts with avatar,
  name, last-message preview, unread badge. (Mock data first — no chat backend yet.)
- **Main area with tabs:** **Meeting** (placeholder "coming soon"), **Share Screen**
  (links to the existing share flow), **Connect Screen** (existing agent connect flow).
- Top bar: BizGaze Connect wordmark (brand blue #1F3B73 / yellow #FFC708, logo.png),
  profile dropdown (existing pattern in the HTML).
- Build a **standalone static mockup first** (e.g. `public/home-mockup.html`) to lock
  the layout, then wire the real tabs/sidebar. Keep the single-file, no-framework style.

## Conventions
- Brand: blue `#1F3B73`, yellow `#FFC708`, logo at `/logo.png`.
- Single-file HTML pages; reuse the existing `profileHTML()`/`wireProfile()` and
  brand patterns already in console.html/connect.html.
- Always `node --check` extracted inline scripts after edits; test against a local
  `node server.js` before committing.