biometry-fraud-decision

Files

decide/orchestrator.go · decide/orchestrator.go (ports) · vendors/auraya/client.go · vendors/evaforensics/client.go

Problem

Phone vendors sit behind a clean PhoneVendor seam — two real adapters (real + mock) per vendor, fanned out uniformly. Voice does not. The orchestrator holds a raw *auraya.Client and special-cases it in resolveVoice() / callAuraya(): it decodes audio, parses crossmatch speakers, decides whether to call EVA Forensics, times EVA, and falls back to a hidden syntheticMockHits(). EVA is not an adapter — it's a case branch baked into the voice path. The three voice inputs (pre-computed from EVA-for-Genesys, raw-audio ArmorVox, synthetic detection) are entangled in one ~55-line method on the orchestrator.

Why it's friction

• Leaky seam: the orchestrator knows Auraya's async internals. The CLAUDE.md says the EVA spec is likely to change — that edit lands inside orchestration, not in an adapter.
• Untestable: there's no way to mock the voice path. Tests pass Auraya: nil and exercise only the pre-computed branch. The "fraudster matches the legit user" voice-spoof edge case can't be tested without hand-faking HTTP.
• Can't wire EVA independently (e.g. standalone synthetic detection) — it's trapped inside callAuraya().

Solution (plain English)

Lift voice resolution to the same shape as PhoneVendor: a small VoiceVendor seam that takes the request and returns []RawSignal. Three adapters behind it — pre-computed (reads voice.result/synthetic/watchlist_hit), ArmorVox crossmatch (raw audio), EVA synthetic — selected by the same auto/real/mock policy the phone vendors use. The orchestrator then fans voice out exactly like every other vendor and stops knowing how voice is computed.

Before / After

Benefits

Leverage: the orchestrator's fan-out becomes one uniform loop over vendors — voice included. Locality: all "how is voice computed" knowledge moves behind one interface; an EVA spec change touches one adapter. Tests: the interface becomes the test surface — fake a VoiceVendor in-process and assert the spoof edge cases that are impossible today. Deletion test: collapsing it back would scatter audio-decode + crossmatch-parse + EVA-dispatch across the orchestrator again — it earns its keep.

Files

domain/rules.go · domain/types.go (RawSignal) · vendors/*/client.go + mock.go · decide/orchestrator.go

Problem

The seam between vendors and the rules engine is an untyped string. Vendors emit RawSignal{Name:"sim_swap_24h"}; RulesConfig.Apply looks the name up in Weights map[string]int and — on a miss — silently skips it (if !ok { continue }). A typo in a vendor ("sim_swap24h") or a renamed weight produces a signal that contributes zero, with no error, no log, no failing test. The rules engine is tested purely in isolation; the orchestrator tests assert signals are present but never assert the resulting score/level/action. So the one seam most likely to drift has the least enforcement.

The gap, concretely

vendor emits        rules.Weights has        result
"sim_swap_24h"  →   "sim_swap_24h": 60   →   +60   ✓
"sim_swap24h"   →   (no key)             →   +0    ✗  silent
                                              no test catches this

Solution (plain English)

Make the signal vocabulary a single named set shared by both sides of the seam — vendors produce from it, the rules config is keyed by it, and seeding validates that every weight name is a known signal (and vice-versa) at startup. Pair it with one end-to-end test that injects a vendor signal and asserts the final score/level/action, plus the threshold boundaries (30/60/80) that currently have no edge-case test. The point isn't ceremony — it's turning a silent-zero into a compile error or a startup failure.

Before / After

Benefits

Locality: the signal vocabulary becomes one authority instead of being implied by string equality across ~6 files. Tests: a vendor→rules contract test makes the most drift-prone seam the test surface. Leverage: small change, removes a whole class of invisible scoring bugs. Pairs naturally with C1 (the new voice adapters emit from the same vocabulary).

Files

transport/rest/dash/handlers.go · external/decide.go · (new) a small respond/errors helper

Problem

Across the 7 dash handlers, return c.JSON(500, ErrorResponse{Error: err.Error()}) appears verbatim ~12 times, and only GetEvent knows that mongo.ErrNoDocuments → 404. That mapping knowledge isn't shared — add a semantic error (say a 409) and there's no registry to put it in; the next handler author won't know to check. Separately, query-param defaulting is done three different ways (inline strconv in ListEvents, a parseSince() helper in GetSummary, inline string default in GetAnalytics) — the generated *Params structs are accepted then ignored. No single place answers "how do we default params / map errors?"

Solution (plain English)

Concentrate the edge: one error responder that maps domain/storage errors to status+body (register ErrNoDocuments→404 once; everything else 500), wired as Echo's error handler or a one-line respondErr(c, err). And one small params decoder for the recurring limit/since/bucket defaults so handlers state intent, not parsing. Handlers shrink to: decode → call → map.

Before / After

Benefits & caveat

Locality: error-status policy and param defaults each get one home. Tests: the responder is unit-testable once instead of implicitly per handler. Honest deletion test: this is the most "hygiene" of the strong-ish candidates — the win is real but bounded (~40 duplicated lines). Do it with C1/C2, not instead of them.

Files

transport/rest/external/mappers.go · transport/rest/dash/mappers.go

Problem

domainSignals() and signalValueToBool() are byte-for-byte identical in both mapper files — the only difference is externalapi.Signal vs internalapi.Signal (codegen emits two structurally-identical types). Deletion test: removing one copy concentrates ~30 lines; it's duplication, not a missing module.

Solution & honest caveat

A generic helper (Go generics over the two structs, or map via a single canonical intermediate) folds the duplication. Caveat: the two types exist because codegen keeps the surfaces independent — forcing them to share fights that grain. Low leverage; only worth it if the signal codec grows (e.g. richer value typing). Listed for completeness, not urgency.

Files

ui/src/pages/{DecisionDetail,Feed,Analytics,Rules,Summary}.tsx · components/ui.tsx

Problem

Domain display semantics are smeared across pages as inline ternaries. The risk-colour rule — "negative weight is green (lowers risk), positive is red (raises risk)" — is hand-written in three places (DecisionDetail signal table, Rules editor, Analytics). Timestamp formatting is done three different ways (toLocaleTimeString, toLocaleString, a local formatBucket). The signal table exists only in DecisionDetail; any new view that shows signals re-implements it. LevelPill/ActionPill live correctly in ui.tsx but as generic UI, not as a "render a Decision" vocabulary.

Solution (plain English)

A thin presentational module that owns how the domain looks: a riskColor(n) / signed-number formatter, a formatDecisionTime(), and a reusable <SignalTable>. Pages compose these instead of re-deriving them. The domain's visual language gets one definition.

Before / After

Benefits

Locality: a colour-semantics or timezone change is one edit, not a grep across pages. Leverage: the hypothetical "Signals Explorer" page composes <SignalTable> for free. Tests: the formatters become pure and unit-testable; today they're trapped in JSX.

Files

ui/src/pages/*.tsx · lib/mic.ts + TryIt.tsx · (new) polling constants / useRecorder

Problem

The generated hooks are great, but the usage contract drifts: three styles of spreading queryOptions (spread+override vs bare call vs call-with-params), three error/loading conventions (early-return vs inline badge vs local-state mutation catch), and magic refetchInterval numbers (Feed 3s, Summary 5s, Analytics none — intentional?). Separately, the record→encode flow is coherent in mic.ts but TryIt carries 9 useState for the recorder sub-machine and the WINDOWS time-selector is duplicated in Summary and Analytics.

Solution (plain English)

Settle one convention and give the recurring pieces a home: a tiny polling constants object (documents why 3s vs 5s), one error/empty presentational wrapper pages share, a useRecorder() hook that swallows the 9 useStates, and a single <TimeWindowSelector>. Smaller than C5 but removes the "which pattern do I copy?" tax for the next page author.

Benefits

Locality: polling cadence and window options each get one source. Leverage: useRecorder makes the capture flow reusable beyond Try-It. AI-navigability: one obvious pattern per concern beats three.