Zahlen Documentation

Phase 2 — Quick Start Experience

2.1 — First-Time Operator Workflow

 

2.1 — First-Time Operator Workflow

The first-time operator workflow is the guided path a user follows during their first operational session in Zahlen. It is designed to build confidence quickly by showing how uploaded payment-event data becomes issuer intelligence, dashboard visibility, alerts, investigations, telemetry evidence, and recommended operational actions.

The workflow is intentionally practical. It begins with a CSV upload and ends with an operator understanding which issuer behavior deserves attention, what evidence supports that conclusion, and which operational surface should be used next.

Workflow at a Glance

Upload CSV  →  Run Analysis  →  Review Dashboard  →  Inspect Issuer Health  →  Review Alerts  →  Investigate Anomalies  →  Review Radar  →  Observe Telemetry  →  Review Recommendations

A CSV upload is the starting point because it gives Zahlen a structured set of payment events to analyze. A payment event is a row of operational evidence, usually containing details such as issuer identity, response code, card brand, country, and recovery outcome. Zahlen uses these events to construct issuer-health signals and downstream operational evidence.

Step 1 — Upload CSV

The operator begins on the Home page by uploading a CSV transaction-event file in the New issuer diagnostics run panel. The CSV file is the evidence source for the first analysis run. In Zahlen, a CSV is not simply a spreadsheet; it is an ingestion package that allows the platform to transform transaction rows into issuer-level operational signals.

The CSV file should contain the payment-event fields needed for issuer analysis. The current user interface exposes a Bank column field because the system needs to know which CSV column identifies the issuer, bank, or issuer-like entity. The Bank column is the mapping instruction that tells Zahlen where to find issuer identity in the uploaded file.

The Use state control tells the system whether to use persisted operational state during analysis. Persisted state is the saved operating memory that lets the platform connect a run to prior knowledge, previous artifacts, or accumulated processing context. For a normal first-time operator workflow, this should usually remain enabled because it supports continuity.

Enable spike alerts controls whether the run should identify abnormal concentration or sudden increases in issuer-response behavior. A spike alert is an operational warning that a particular issuer, response code, or payment condition may be appearing at a higher-than-expected rate.

Enable AI mode is an optional enhancement path for assisted interpretation. The core Zahlen workflow remains deterministic and evidence-driven; AI mode should be understood as a supplemental interpretation layer rather than the source of operational truth.

Step 2 — Run Analysis

After the operator clicks Run issuer analysis, Zahlen creates a saved investigation run. A run is a durable processing record that captures the uploaded file, processing status, generated findings, telemetry artifacts, exports, and follow-up evidence. Runs are important because they preserve the operational history behind each analysis session.

The job lifecycle normally moves from created to running to completed. Created means the run record exists. Running means the platform is processing the uploaded evidence. Completed means the run finished and generated artifacts that operators can inspect. Failed means the system could not complete processing and the operator should review the error output or System Health surface.

The run output may include findings, records, summaries, telemetry reports, alerts, and downstream issuer-health signals. A finding is an operator-facing conclusion generated from the uploaded data. A record is the row-level evidence that supports analysis. A telemetry report is the system’s structured interpretation of evidence quality, truth linkage, external status, and response-code behavior.

Step 3 — Review Dashboard

The Dashboard provides the operator with the first consolidated view of operational activity after analysis. It surfaces alerts, queue items, issuers, severity counts, escalation pressure, and recent system events.

An alert is a system-generated operational signal indicating that issuer behavior may require attention. A queue item is an actionable work item derived from signals that need review, investigation, routing, or resolution. Severity describes how urgent or operationally important the item appears. Escalation pressure describes whether the item may require supervisor attention due to age, ownership gaps, or operational risk.

The Dashboard should be read as an orientation surface rather than a final diagnosis surface. Its role is to tell the operator where attention is needed and which page should be opened next.

Step 4 — Inspect Issuer Health

Issuer Health is where the operator inspects the health rows generated from issuer behavior signals. An issuer-health row represents an issuer cohort or issuer-related signal that the platform believes is operationally meaningful.

An issuer cohort is a grouping of payment behavior associated with an issuer identity, usually refined by country, card brand, response-code pattern, or operational window. Cohorts are important because issuer behavior may not be uniform globally. One issuer may appear stable in one region and degraded in another.

Issuer health allows the operator to move from general dashboard awareness into issuer-specific review. The operator should look for warning counts, critical states, repeated issuer BINs, response-code recovery metrics, and low-confidence patterns that may require more evidence.

A warning state means the signal deserves review but may not yet represent a severe operational issue. A critical state indicates a stronger operational concern. A low-confidence signal means the platform has detected a pattern, but the supporting evidence may be sparse, immature, or not yet truth-linked.

Step 5 — Review Alerts

Alerts are the operational bridge between raw analysis and human attention. An alert indicates that Zahlen has identified an issuer behavior pattern, recovery issue, response-code concentration, or health condition that should be reviewed.

The Alerts surface should be used to understand which issuers, countries, brands, and metrics are currently producing elevated signals. Metric refers to the specific measurement that caused the alert, such as a response-code recovery rate. A response-code recovery rate measures how often payments associated with a particular processor or issuer response code eventually recover.

The operator should not treat every alert as a confirmed outage. Alerts are prompts for structured review. The correct next step is to evaluate the issuer, inspect the summary, open records when necessary, and decide whether the signal should be investigated further.

Step 6 — Investigate Anomalies

An anomaly is behavior that differs meaningfully from expected or historical patterns. In Zahlen, an anomaly may appear as declining recovery, unusual response-code behavior, issuer degradation, elevated entropy, replay inconsistency, or concentrated activity for one issuer cohort.

The Investigation surface gives operators a deeper view of the evidence behind a signal. Investigation is where an operator moves from “something appears unusual” to “this is what the evidence shows.”

Operators should use the investigation path to review issuer identity, affected country, card brand, time window, related task state, evidence summary, recent actions, and links to timeline or replay views. The timeline helps determine whether the anomaly is isolated or persistent. Replay helps determine whether the conclusion is reproducible under deterministic reconstruction.

Step 7 — Review Radar Detections

Radar is the higher-confidence issuer behavior detection layer. A Radar detection is a promoted signal that has crossed the system’s confidence and pattern thresholds strongly enough to deserve elevated operator attention.

A promoted signal is a signal that has moved beyond raw monitoring into a more formal detection state. Promotion matters because not every health row or alert should become a Radar detection. Radar is designed to reduce noise by surfacing stronger issuer behavior patterns.

Confidence bands help operators interpret the strength of Radar detections. A high-confidence detection has stronger evidence quality, better replay consistency, more persistent signal behavior, or broader supporting context. A low-confidence detection may still be useful, but it should be treated as an early signal rather than a fully established operational conclusion.

If the Monitor page indicates that issuer-health events exist but no Radar detections have been promoted, the operator should understand this as a normal threshold condition. It means monitoring evidence exists, but the evidence has not yet crossed the Radar promotion boundary.

Step 8 — Observe Telemetry

Telemetry is the evidence-quality and interpretation layer generated around a run or signal. In the current Zahlen workflow, telemetry may describe event counts, truth linkage, confidence bands, external status, response-code patterns, and whether enough supporting evidence exists for stronger conclusions.

Truth linkage refers to whether a telemetry event can be matched against a known truth source or validated external/internal reference. A truth-linked event has stronger interpretive value because it is connected to a known evidence anchor. No truth-linked events does not necessarily mean the signal is wrong; it means the current run has not yet been connected to validating truth data.

External status describes whether the system has associated the observed behavior with an outside condition, external lookup, or broader known event. A value such as NOT_RUN means the external-status enrichment process has not been executed for that signal. Operators should treat this as an evidence-availability state rather than a business failure.

A confidence band expresses how strongly the system trusts the current interpretation. A NONE or UNKNOWN confidence band usually indicates that the system does not yet have enough validated evidence to classify the signal with stronger confidence. As live data, truth data, and repeated observations accumulate, telemetry signals can become more informative.

Step 9 — Review Operational Recommendations

Operational recommendations translate issuer intelligence into next-step guidance. A recommendation is not merely a suggestion; it is an operator-facing interpretation of what the system believes should happen next based on current evidence.

Recommendations may appear in investigation views, action queues, escalation guidance, supervisor surfaces, or monitoring pages. A recommendation may tell the operator to monitor and gather more evidence, investigate localized cohort behavior, review an aging operational item, or open a replay or timeline view.

The operator should evaluate recommendations alongside severity, confidence, ownership state, replay evidence, telemetry context, and issuer repetition. A recommendation is strongest when it is supported by persistent signals, stable replay behavior, clear issuer identity, and coherent telemetry evidence.

Resolution should occur only after the operator has enough evidence to determine whether the signal has recovered, requires continued watch, needs escalation, or should remain open for further investigation.

First-Hour Operator Checklist

Checkpoint	Meaning
CSV uploaded	The operator has provided the payment-event evidence needed for issuer diagnostics.
Run completed	The system has generated a durable job record and analysis artifacts.
Dashboard reviewed	The operator understands the current alert, queue, issuer, and escalation state.
Issuer health inspected	The operator has identified the issuer-health rows or warning states that deserve attention.
Alerts reviewed	The operator understands which issuer signals are elevated and why.
Anomalies investigated	The operator has opened at least one investigation path for deeper evidence review.
Radar checked	The operator understands whether any higher-confidence detections have been promoted.
Telemetry interpreted	The operator understands the evidence maturity, truth linkage, confidence band, and external status of the run.
Recommendations reviewed	The operator has evaluated the recommended next operational action.

Recommended Screenshot Set

This section should eventually be illustrated with annotated screenshots. The purpose of screenshots is not decoration; screenshots help new operators connect the documentation language to the actual control surfaces inside the product.

Screenshot	Annotation Goal
Home upload panel	Highlight CSV file, Bank column, Enable spike alerts, Enable AI mode, and Run issuer analysis.
Recent runs / Run history	Highlight completed status, job ID, input file, and Open run.
Dashboard summary	Highlight Alerts, Queue Items, Issuers, Warnings, Escalations Needed, and search.
Issuer Health / Alerts	Highlight issuer BIN, country, brand, metric, severity, and summary.
Investigation view	Highlight issuer identity, evidence summary, timeline links, replay links, and related tasks.
Radar view	Highlight confidence band, detection identity, feedback state, and investigation links.
Telemetry report area	Highlight truth-linked counts, confidence band, external status, and response-code context.
Action Queue / Supervisor recommendations	Highlight recommended action, owner, task status, escalation reason, and resolution status.

Summary

The first-time operator workflow is designed to make Zahlen understandable in the first hour. The operator begins with a CSV upload, produces a durable analysis run, reviews the dashboard, inspects issuer health, evaluates alerts, investigates anomalies, checks Radar, interprets telemetry, and reviews operational recommendations.

This workflow teaches the most important product principle behind Zahlen: payment recovery is not merely a billing function. It is an observable operational system that reveals issuer behavior, recovery dynamics, evidence quality, and ecosystem stability.