# WalletCards

OTP application managing card lifecycle within the MercuryPay umbrella.

## Public Interface

```elixir
# Physical / virtual card management
WalletCards.CardStore.store(card)
WalletCards.CardStore.get(card_id)
WalletCards.CardStore.update(card)
WalletCards.CardStore.list_by_user(user_id)
WalletCards.CardStore.list_all()

# Externally-linked (top-up) cards
WalletCards.LinkedCardStore.store(linked_card)
WalletCards.LinkedCardStore.get(linked_card_id)
WalletCards.LinkedCardStore.update(linked_card)
WalletCards.LinkedCardStore.list_by_user(user_id)

# Card BIN validation
WalletCards.BinValidator.validate(pan)

# Card tokenization
WalletCards.CardTokenizer.tokenize(card_id)

# Balance sync tracking
WalletCards.CardBalanceSyncStore.store(sync_record)
WalletCards.CardBalanceSyncStore.get(sync_id)
WalletCards.CardBalanceSyncStore.update(sync_record)
```

## Responsibilities
- Card lifecycle: issue, freeze, unfreeze, block, limits update, PIN reset.
- Externally-linked card management: link, unlink.
- BIN validation and card tokenization.
- Balance drift reconciliation and sync record tracking.

## Forbidden Dependencies
- **wallet_ledger** — no direct ledger writes from this app.
- **wallet_auth** — no auth logic in this app.
- **wallet_accounts** — card domain does not own account state.

## Dependencies
- `wallet_shared_kernel` — TypedId, Money, Correlation.
- `wallet_observability` — AuditEvent, Telemetry.
- `wallet_events` — DomainEvent behaviour.
- `wallet_database` — write-through persistence (CardPersistence, LinkedCardPersistence, CardBalanceSyncRecordPersistence).

## TypedId Prefixes
- `crd_` — wallet cards.
- `lnk_` — linked (external) cards.
- `csync_` — card balance sync records.

## Events Emitted
- `WalletCards.Events.VirtualCardRequested.v1`
- `WalletCards.Events.CardFrozen.v1`
- `WalletCards.Events.CardUnfrozen.v1`
- `WalletCards.Events.CardBlocked.v1`
- `WalletCards.Events.CardUnblocked.v1`
- `WalletCards.Events.CardLimitsUpdated.v1`
- `WalletCards.Events.CardPinResetRequested.v1`
- `WalletCards.Events.ExternalCardLinked.v1`
- `WalletCards.Events.ExternalCardUnlinked.v1`
- `WalletCards.Events.CardBalanceSynced.v1`
- `WalletCards.Events.BalanceDriftReconciled.v1`

## Stores
- `WalletCards.CardStore` — ETS-backed GenServer; MySQL write-through via `CardPersistence`.
- `WalletCards.LinkedCardStore` — ETS-backed GenServer; MySQL write-through via `LinkedCardPersistence`.
- `WalletCards.CardBalanceSyncStore` — ETS-backed GenServer; MySQL write-through via `CardBalanceSyncRecordPersistence`.