# Helpdesk

A phone helpdesk for field technicians. A technician calls a stationary GrapheneOS Pixel in the office;
before the operator picks up, the caller's card pops up on the operator's screen. The call is recorded,
transcribed, and summarised, and filed against the caller as an event. Operators work in a web console;
the phone talks to the backend over its own signed channel.

The backend is one Ruby process: WEBrick and the standard library, plus the pg and sequel gems when it
runs on PostgreSQL. In production it runs on `moje.al.army` - operators reach the console over mutual
TLS on 443, the phone posts to its own TLS door on 8443.

## Run it locally

Ruby 3.2+ and nothing else. The default mode stores everything in a JSON file, so there is no database
to set up:

```
ruby components/backend/server.rb
```

That starts the console and the device API on http://127.0.0.1:4000 in dev mode: operator auth off, a
few demo contacts seeded. Open http://127.0.0.1:4000 for the console.

To run on PostgreSQL instead, point `HELPDESK_DATABASE_URL` at a database and the backend switches
stores:

```
createdb helpdesk_dev
psql helpdesk_dev -f components/backend/db/migrate/001_init.sql
HELPDESK_DATABASE_URL=postgres://localhost/helpdesk_dev ruby components/backend/server.rb
```

Tests run from `components/backend`: `make test`, or any file directly (`ruby test/test_domain.rb`).
To watch a whole call go through without a phone, start the server and run `ruby sim/simulator.rb`.

## Layout

- `components/backend` - the deployed service: operator console, operator API, device API, storage,
  the AI pipeline. Start reading at `server.rb`.
- `components/backend/lib/helpdesk` - the domain core: `domain.rb` (the Store seam and the Service,
  including the call state machine), `pg_store.rb` (PostgreSQL), `ledger.rb` (the resolutions ledger),
  `business_hours.rb`, `reporting.rb`.
- `components/backend/wiki` - wiki grounding for summaries: GraphQL client, embedder, cosine index,
  build script.
- `components/transcription-worker` - recording to speaker-tagged transcript: `remote_transcriber.rb`
  (hosted Whisper, what production uses) and `transcriber.rb` (local WhisperX fallback).
- `components/dialer-patch` - the GrapheneOS Dialer patch: a Java overlay plus nine source patches.
  Built only on the build box (see `docs/runbooks/`), never in CI.
- `components/sepolicy-patch` - one SELinux patch so the patched Dialer can read its
  `*.helpdesk.*` config properties.
- `deploy/` - reference copies of the production config: systemd units, nginx vhosts, the deploy and
  backup scripts.
- `ci/` - the end-to-end script the pipeline runs.
- `docs/` - the human docs, listed below.
- `resources/` - fetch scripts for the (huge, git-ignored) GrapheneOS sources, and the local Whisper
  CLI the fallback transcriber drives.

## Docs

- `docs/architecture.md` - how the pieces fit: the two auth planes, a call's path through the system,
  storage, the AI subsystem.
- `docs/operations.md` - the production server: deploy, roll back, logs, backups, secrets, CI.
- `docs/device-api.md` - the wire contract between the phone and the backend.
- `docs/phone-connectivity.md` - how the patched Dialer finds, authenticates to, and talks to the
  backend, with troubleshooting.
- `docs/onboarding.md` - accounts, certificates, SSH, first run.
- `docs/runbooks/` - building and flashing the Pixel: `graphene-build.md`,
  `pixel10a-flash-manual.md`, `windows-wsl2-build.md`. Plus `cert-renewal.md`, for the vmin
  certificates, which do not renew themselves.