Prd/docs/architecture.md

Architecture

Helpdesk answers a technician's cellular call on an office GrapheneOS Pixel, shows the operator who's calling before they pick up, records and transcribes the call, and files a summary against the caller.

The pieces

• Backend (components/backend) - one Ruby process: WEBrick and the standard library, no web framework. It serves the operator console, the operator API, and the phone's device API. This is what gets deployed. Entry point is server.rb; the business logic is the Service class in lib/helpdesk/domain.rb; storage sits behind a Store seam.
• Phone (components/dialer-patch + sepolicy-patch) - a patched GrapheneOS Dialer that records the call and posts webhooks to the backend. Privileged call-audio capture only works in a self-signed build, so this is baked into the OS, not shipped as an app. Built on the dedicated build box (see docs/runbooks/).
• Transcription (components/transcription-worker) - sends the recording to Whisper. Production uses the hosted Whisper (whisper.cajk.org, over mTLS, selected by WHISPER_URL); without that variable it falls back to a local WhisperX subprocess. A two-channel recording is split and each speaker transcribed separately (below); the result then passes through lib/helpdesk/glossary.rb, which repairs domain words the model cannot know.
• AI (summariser.rb, context_maintainer.rb, wiki/) - turns transcripts into summaries and keeps a per-caller dossier. Described in its own section below.

The operator PC and the phone are both clients of the backend and never talk to each other directly. The voice call is cellular (phone to carrier) and never touches the server.

The call, start to finish

1. A call comes in. The phone posts /api/v1/calls/incoming with the caller's number and the number that was dialed.
2. The backend matches the number to a person and the dialed number to an operator, then pushes a screen-pop to that operator's console.
3. The operator answers; the phone starts recording and posts /calls/answered.
4. On hangup the phone posts /calls/ended and uploads the recording (PUT /recordings/<uuid>).
5. The backend transcribes it, then summarises it, and stores both on the event.

Outgoing calls work too: the operator types a number in the console (or clicks one), the backend queues a dial command, the phone places the call and reports it back through /calls/outgoing. From there the recording and AI pipeline are the same as for an inbound call. The audio always stays on the phone - the PC can't carry call audio, and the server can't inject any (so there is no server-played greeting).

If a webhook goes missing, a reconcile pass on a 60-second timer fixes stuck calls: ring timeouts, a recording that never arrived, an expired quarantine. The exact rules are in docs/device-api.md.

Two auth planes

Operators and the phone authenticate in completely different ways, and it matters that you don't mix them.

• Operators use a vmin client certificate (the same PKI as whisper.cajk.org). nginx terminates the TLS, checks the cert against the vmin CA, and passes the identity to the backend as headers (X-Operator-Cert plus a shared X-Proxy-Secret). The backend itself is plain HTTP on loopback behind nginx. Enforced by HELPDESK_OP_AUTH=1; checked in operator_authed? in server.rb.

  A valid signature is not by itself permission. ca.vmin.cz belongs to the hosting provider, so being signed by it proves who issued the cert, not that the holder works here. HELPDESK_OPERATOR_CNS lists the cert CNs allowed on the console, and it doubles as the revocation we own: no CRL is configured, so removing a CN is how a lost laptop's certificate is turned off. Left unset, any cert the CA verified is accepted, which is the older behaviour and what local dev relies on. The matching rule is pure and tested - Server.cert_cn and Server.operator_allowed?, grep anchor operator-allowlist.

  The identity is also kept, not just checked: resolutions an operator records carry a by field with their CN, so the ledger says who decided. nginx logs the same subject via the helpdesk_console log format, which is the only access attribution at the edge.

• The phone has no certificate. It signs every request with an HMAC: a bearer token plus a signature over timestamp.nonce.body, with nonce replay protection and a clock-skew window. Enforced by HELPDESK_AUTH=1; checked in authed?. In production the phone posts to its own door, https://moje.al.army:8443/api/v1 - TLS without a client cert (the phone can't hold one), with nginx allowlisting only the device paths and blanking the operator-identity headers.

In dev mode (HELPDESK_DEV=1, the default) operator auth is off so you can open the console directly, and the device plane accepts the built-in dev credentials.

Both planes rest on certificates that expire, and the two ways they can fail are both silent: the vmin CA has no renewal at all, and the server certificate's automatic renewal writes its output to /dev/null. lib/helpdesk/cert_watch.rb makes that visible - it rides along on the /status poll the console already makes and puts a badge in the navbar when anything is inside the warning window, staying invisible otherwise. It reads the server certificate over TLS rather than from disk, both because the key directory is unreadable to the service user and because the served certificate is the honest one: a file check would not notice a certificate renewed on disk but never loaded by nginx. For a client certificate it reports the earliest date in the whole chain, since a leaf that outlives its CA stops working when the CA does.

Operators are a separate problem: there is one certificate per person, they live in browsers, and the server holds no copy, so none of them can be watched from a file. nginx knows the expiry of whichever certificate was just presented, and passes it as X-Operator-Cert-Days / X-Operator-Cert-Expires, so each operator is warned about their own and nobody needs an inventory of who holds what. Grep anchors: cert-watch-sources, cert-watch-severity, cert-watch-cache, cert-watch-presented.

Dual-channel transcription

When the phone records the two call legs as separate channels (persist.helpdesk.rec_dual_leg), the pipeline splits the file and transcribes each channel on its own, then merges the two transcripts on their timestamps. Speaker attribution stops being something a diariser infers from two similar voices on a narrowband line and becomes a fact about which channel the words came from.

Splitting is mandatory rather than an optimisation: Whisper resamples to 16 kHz mono before decoding, so handing it the stereo file puts both people back into one channel and discards exactly what the phone went to the trouble of capturing. Each channel is then transcribed with the diariser pinned to one speaker, since anything higher would invent a second voice out of crosstalk.

It costs two transcription jobs per call, so roughly double the turnaround on a CPU-only service.

Every failure path falls back to transcribing the original file: a leg that fails, a split that will not parse, or two channels whose transcripts come back identical (which means the legs were never really separated). A correctly attributed transcript is a bonus; a transcript is not. lib/helpdesk/wav_split.rb and lib/helpdesk/dual_transcript.rb, grep anchor dual-channel-transcribe.

The transcript glossary

Whisper has never seen "yamt" and the hosted service accepts no vocabulary hint - it takes exactly five form fields, none of them a prompt - so it writes the sound it heard, "jamt". Better audio cannot fix that, because nothing in the signal says how the word is spelt. lib/helpdesk/glossary.rb corrects a curated list of terms after transcription and before summarising, matching near-misses only.

Two limits are deliberate. Only distinctive terms belong in the list - system names, sites, operators. Ordinary words must not be added: "balíček" is one edit from "malíček" (little finger), and nothing in the text distinguishes a misheard word from a different one, so listing common words would eventually rewrite correct Czech. Common-word errors come from poor audio and are fixed at the recorder instead. And Czech inflection is left alone: "na Vodafonu" is the correct locative, so a difference confined to the ending is treated as grammar rather than a mistake.

Every substitution is returned and logged. A transcript records what a caller was told, so it is never edited silently. Grep anchors: glossary-load, glossary-correct, glossary-match.

Storage

Everything goes through the Store seam, so the backend doesn't care which storage it's on. Reads hit an in-memory cache; writes are explicit put_*/delete_* calls. There are two backends:

• JSON file (default) - the whole store is dumped to ~/.config/helpdesk/state.json. Zero setup, good for local work.
• PostgreSQL (set HELPDESK_DATABASE_URL) - a Sequel-backed write-through cache, PgStore. This is what production runs. The schema is db/migrate/001_init.sql, and that file is the source of truth for the data model. db/parity_check.rb proves the two backends behave identically.

One rule about the record shape: top-level fields are symbol keys (ev[:state]); nested JSON sub-documents are string keys (action_items[i]["text"]). The tests enforce it.

The AI subsystem

All model calls go through OpenRouter with one key (OPENROUTER_API_KEY). Three parts:

• Per-call summary (summariser.rb). After transcription, the transcript goes to google/gemini-3.6-flash (override with SUMMARISER_MODEL) with a strict JSON schema. Out come a Czech summary, advisory action items, a context digest, durable caller facts, and yes/no decision deltas with verbatim quotes. The reply is validated client-side; if the strict schema isn't honoured the call is retried in a looser mode, and if that fails too the event is flagged for human review. Everything the AI produces is advisory - the operator sets the resolution.
• Wiki grounding (wiki/). When an index file exists (WIKI_INDEX_PATH, default wiki/wiki_index.json), the pipeline retrieves the 15 wiki chunks closest to the transcript (cosine over OpenRouter embeddings) and passes them to the summariser. The prompt tells the model to state the concrete value or standard when the excerpts contain it, name the source wiki page in the action item's target, and never invent a number that isn't in the excerpts. Retrieval beat stuffing the whole wiki into the prompt in a side-by-side test: same grounded specifics, each one traceable to its page, at about 1.5% of the cost. The index is built offline by wiki/build_index.rb and is not in git.
• Per-caller dossier (context_maintainer.rb). Each person carries an AI-maintained context: a short "who is this caller" summary plus other useful facts, stored as jsonb on the person with an optimistic-locking revision. After each summarised call (and on demand from the console) the backend rebuilds it - incrementally for small updates, from full history every few revisions or when the operator asks (both on google/gemini-3.6-flash; override with MAINTAINER_MODEL / MAINTAINER_REBUILD_MODEL). Operators can pin a section, and pinned text is never overwritten. Alongside the dossier sits a deterministic resolutions ledger (ledger.rb): yes/no decisions, where a reversal never deletes the old entry - it appends, marks the old one superseded, and flags the contradiction for a human. Entries come from two places: the summariser extracts them from call transcripts (ledger_deltas -> Helpdesk::Ledger.apply), and an operator can record one by hand from the console ("+ add" under Previous resolutions -> add_resolution in domain.rb, tagged source: operator) - useful when a policy is set outside a call and would otherwise only live in the dossier prose. Any active resolution is editable at any time (the pencil on its row -> edit_resolution), which supersedes it by id with the new decision or wording - so a decision that turned out wrong can be corrected without waiting for a conflict, and history is still kept. The operator resolves a flagged conflict from the console too: a review window shows both decisions with their quotes and source calls, and the operator sets the authoritative answer (which appends an operator-sourced entry, keeping the ledger append-only) or dismisses it (the current decision stands). resolve_contradiction, add_resolution, and edit_resolution in domain.rb are those seams.

Key decisions that still hold

• Cellular, not landline. The audio is good enough for diarization and it's what technicians already use.
• Record by patching the GrapheneOS Dialer inside a self-signed build. A normal app can't capture call audio.
• The phone is the only audio endpoint. The server can't inject audio into the call, so there's no server-side greeting played to the caller.
• Transcription is hosted Whisper over mTLS, with a local fallback. The summary is advisory: a human sets the resolution, the AI only suggests.
• One dedicated inbound number per operator, so the dialed number says who should get the screen-pop.
• Wiki grounding is retrieval of relevant chunks, not the whole wiki in the prompt. Cheaper, and every claim is traceable to a page.

Where things live

• server.rb - HTTP routes, both auth checks (authed?, operator_authed?), the transcription trigger, the dossier refresh latch.
• lib/helpdesk/domain.rb - the Store seam and the Service: call state machine, people, AI memory, reconcile.
• lib/helpdesk/pg_store.rb - the PostgreSQL backend.
• lib/helpdesk/cert_watch.rb - certificate expiry for the console's warning badge.
• lib/helpdesk/glossary.rb + glossary_terms.txt - domain vocabulary applied to transcripts.
• lib/helpdesk/wav_split.rb - splits a two-channel call recording into one file per speaker.
• lib/helpdesk/dual_transcript.rb - merges the two per-speaker transcripts back into one.
• db/migrate/001_init.sql - the schema.
• summariser.rb, context_maintainer.rb, pipeline.rb, lib/helpdesk/ledger.rb, wiki/ - the AI path.
• public/console.html - the whole operator console, one file.
• sim/simulator.rb - drives the device API over HTTP; the quickest way to see the whole flow.

The device wire contract (endpoints, auth recipe, state machine, reconciliation timings) is in docs/device-api.md.