# Domain Glossary

## Merchant

A business represented in the source data. A merchant owns terminals, payment sessions, and merchant users. In the MVP, detailed data is visible only within that merchant's authenticated boundary.

## Merchant User

A person/account permitted to authenticate as one merchant. The hackathon seed creates an initial demo user for each merchant; a merchant and a merchant user are not the same concept.

## Authenticated Session

A time-bounded and revocable authorization grant connecting one authenticated merchant user to exactly one merchant boundary. Logout, account disablement, idle expiry, or absolute expiry ends the grant.

## Terminal

A merchant-owned payment endpoint identified by the source terminal key.

## Payment Session

One payment journey identified by the source session key. A session belongs to one merchant and terminal and can contain one or more payment attempts.

## Payment Attempt

One try within a payment session, distinguished by its try sequence. This is the grain of a source CSV row and must not be confused with a unique payment session.

## Bank-Paid Session

A payment session whose source status is `Paid` or `Verified`. In both states the buyer completed payment at the bank and funds were deducted. This is the numerator population for payment success and paid-volume metrics.

## Verified Session

A bank-paid session whose merchant verification step is complete (`Verified`). It is finalized, and is a subset of bank-paid sessions.

## Unverified Paid Session

A bank-paid session whose bank step succeeded but whose merchant verification step has not completed (`Paid`). It is successful at the bank, not a failure, and must remain visible as an actionable verification gap.

## Merchant Fee

The Rial fee associated with one payment session. The challenge source calls it `adjusted_fee` and repeats the same value on each attempt row; the normalized model stores it once on the session as `fee_amount_rial`.

## Opaque Payer Token

The nullable `payer_card_key` source value. It is an unverified, merchant-scoped token used only for internal approximate repeat-payer analytics. It is not a card number or verified person identifier.

## Import Run

One traceable attempt to ingest a specific source archive/schema using a specific importer revision. It records outcome, counts, validation evidence, and provenance.

## Calendar Date

One civil date enriched with Gregorian and Jalali calendar attributes, Persian month/season, weekday, and reporting attributes.

## Reporting Period

An approved time window used for metrics: Tehran-local day, week, Jalali month, or Persian season.

## Analytical Metric

A deterministic numerical measure with a definition, source fields, filters, period, unit, missing-data behavior, and drill-down path.

## Analytics Projection

A rebuildable, versioned analytics result derived from normalized PostgreSQL facts and cached in Redis for one merchant/cohort revision. It is not independent business truth.

## Analytics Revision

A monotonically increasing PostgreSQL merchant or cohort version changed when a related payment fact is inserted. Redis cache keys include the revisions they represent; a mismatch causes request-triggered section jobs to calculate new keys while older keys expire through TTL.

## Analytics Section

One independently calculable and deliverable dashboard part. The MVP section ids are `overview`, `payment_performance`, `fees`, and `peer_comparison`. All four start on first dashboard access and become visible independently through authenticated SSE events.

## Peer Cohort

The other eligible merchants in the active merchant's category and selected reporting period, used for anonymized comparison. The active merchant is excluded, and a benchmark is suppressed unless at least 10 peers and 1,000 combined peer sessions contribute.

## Merchant-Weighted Cohort Median

The median of one independently calculated metric value per eligible peer merchant. Every merchant contributes one value regardless of transaction volume, so the result represents a typical peer rather than primarily representing the largest merchants.

## Peer Performance Percentile

The active merchant's position among eligible same-category peers for one metric and reporting period. A higher displayed percentile always means better performance; metrics where lower values are better are direction-adjusted before ranking.