# Wallet Domain Map (Apps Mode)

## 1. Purpose
Define public responsibilities, key commands, key queries, and domain events per OTP app. This is the implementation contract map for teams.

## 2. Domain Apps

## wallet_web
Responsibilities:
- API/BFF delivery layer for web, admin, and partner/mobile clients.
- Request validation, auth enforcement, response shaping.

Commands (delegated):
- `AuthenticateUser`
- `CreateTransfer`
- `CreditWallet`
- `DebitWallet`

Queries (delegated):
- `GetWalletBalance`
- `GetTransferStatus`

Events published:
- None (delivery layer should not emit business events directly).

## wallet_auth
Responsibilities:
- Authentication, token lifecycle, OTP/MFA, session/device trust.

Commands:
- `LoginWithPassword`
- `IssueAccessToken`
- `RefreshToken`
- `StartOtpChallenge`
- `VerifyOtpChallenge`
- `RevokeSession`

Queries:
- `ValidateTokenClaims`
- `GetTrustedDevices`

Events:
- `AuthSessionStarted.v1`
- `AuthSessionRevoked.v1`
- `OtpChallengeVerified.v1`

## wallet_accounts
Responsibilities:
- Wallet account lifecycle and profile-account association.

Commands:
- `OpenWalletAccount`
- `FreezeWalletAccount`
- `UnfreezeWalletAccount`
- `UpdateWalletTier`

Queries:
- `GetWalletAccount`
- `GetWalletStatus`

Events:
- `WalletAccountOpened.v1`
- `WalletAccountFrozen.v1`
- `WalletAccountUnfrozen.v1`
- `WalletTierChanged.v1`

## wallet_ledger
Responsibilities:
- Double-entry posting engine and immutable journal.

Commands:
- `PostJournalEntry`
- `AuthorizeDebit`
- `ApplyCredit`
- `ReversePosting`

Queries:
- `GetCurrentBalance`
- `GetLedgerEntries`
- `GetPostingByReference`

Events:
- `LedgerPosted.v1`
- `LedgerReversed.v1`
- `BalanceUpdated.v1`

## wallet_transfers
Responsibilities:
- Transfer lifecycle and state transitions for P2P/internal/external transfer intents.

Commands:
- `InitiateTransfer`
- `ReserveTransferFunds`
- `CompleteTransfer`
- `FailTransfer`
- `CancelTransfer`

Queries:
- `GetTransfer`
- `ListUserTransfers`

Events:
- `TransferInitiated.v1`
- `TransferReserved.v1`
- `TransferCompleted.v1`
- `TransferFailed.v1`
- `TransferCanceled.v1`

## wallet_limits_fees
Responsibilities:
- Policy evaluation for limits, fees, and rule decisions.

Commands:
- `UpsertLimitPolicy`
- `UpsertFeePolicy`

Queries:
- `EvaluateTransferLimits`
- `CalculateFee`

Events:
- `LimitPolicyUpdated.v1`
- `FeePolicyUpdated.v1`
- `PolicyDecisionCaptured.v1`

## wallet_risk
Responsibilities:
- Fraud and risk scoring orchestration using rules/stream signals.

Commands:
- `FlagRiskSignal`
- `EscalateCase`

Queries:
- `ScoreTransferRisk`
- `GetRiskProfile`

Events:
- `RiskScored.v1`
- `RiskEscalated.v1`
- `RiskCleared.v1`

## wallet_journey
Responsibilities:
- End-to-end process orchestration for transfer and onboarding journeys.

Commands:
- `StartJourney`
- `AdvanceJourneyStep`
- `CompensateJourney`

Queries:
- `GetJourneyState`

Events:
- `JourneyStarted.v1`
- `JourneyStepAdvanced.v1`
- `JourneyCompensated.v1`
- `JourneyCompleted.v1`

## wallet_settlement
Responsibilities:
- Batch settlement and reconciliation workflows.

Commands:
- `RunSettlementBatch`
- `RunReconciliation`
- `ResolveSettlementException`

Queries:
- `GetSettlementBatch`
- `GetReconciliationReport`

Events:
- `SettlementBatchStarted.v1`
- `SettlementBatchCompleted.v1`
- `ReconciliationCompleted.v1`
- `SettlementExceptionRaised.v1`

## wallet_notifications
Responsibilities:
- Template-based user notifications and delivery state tracking.

Commands:
- `QueueNotification`
- `SendNotification`
- `UpdateNotificationPreferences`

Queries:
- `GetNotificationHistory`
- `GetNotificationPreferences`

Events:
- `NotificationQueued.v1`
- `NotificationSent.v1`
- `NotificationFailed.v1`

## wallet_integrations
Responsibilities:
- External adapters (payments, CBS, VAS, external fraud providers).

Commands:
- `DispatchProviderRequest`
- `HandleProviderWebhook`

Queries:
- `GetProviderTransactionStatus`

Events:
- `ProviderRequestDispatched.v1`
- `ProviderCallbackAccepted.v1`
- `ProviderRequestFailed.v1`

## wallet_events
Responsibilities:
- Event schema registry, outbox/inbox handling, publish-subscribe reliability.

Commands:
- `AppendOutboxEvent`
- `AcknowledgeInboxEvent`

Queries:
- `ListPendingOutboxEvents`
- `ListUnackedInboxEvents`

Events:
- Infrastructure events only (no domain ownership).

## wallet_state
Responsibilities:
- Non-financial distributed state (idempotency keys, locks, workflow cache).

Commands:
- `AcquireLock`
- `ReleaseLock`
- `RegisterIdempotencyKey`

Queries:
- `GetIdempotencyResult`
- `GetWorkflowSnapshot`

Events:
- Optional state instrumentation only.

## wallet_observability
Responsibilities:
- Central metrics, tracing helpers, audit emission, health checks.

Commands:
- `EmitAuditEvent`

Queries:
- `GetHealthSummary`

Events:
- `AuditEventRecorded.v1`

## wallet_compliance
Responsibilities:
- KYC/KYB, AML case orchestration, compliance evidence workflow.

Commands:
- `SubmitKycCase`
- `ReviewKycCase`
- `FileSuspiciousActivityReport`

Queries:
- `GetKycStatus`
- `ListComplianceAlerts`

Events:
- `KycCaseSubmitted.v1`
- `KycCaseApproved.v1`
- `KycCaseRejected.v1`
- `SarFiled.v1`

## wallet_api_contracts
Responsibilities:
- Versioned API schema contracts and standard error envelopes.

Commands:
- None (contract package).

Queries:
- Schema lookups and validation helpers.

Events:
- None.

## wallet_shared_kernel
Responsibilities:
- Minimal shared primitives and behaviors.

Allowed content:
- Typed IDs
- Money primitives
- Time/correlation helpers
- Behavior definitions

Forbidden content:
- Domain workflows
- DB-specific logic
- Cross-domain command handlers

## 3. Critical Cross-App Flows
1. Transfer flow:
- `wallet_web` -> `wallet_auth` -> `wallet_transfers` -> `wallet_limits_fees` + `wallet_risk` -> `wallet_ledger` -> `wallet_events` -> async consumers.

2. Settlement flow:
- `wallet_settlement` -> `wallet_integrations` + `wallet_ledger` + `wallet_events` -> reconciliation report.

3. Compliance flow:
- `wallet_compliance` consumes onboarding/transfer risk events and emits compliance outcomes.

## 4. Naming and Versioning Rules
- Commands are imperative verbs in PascalCase.
- Queries are read-oriented and side-effect free.
- Events are past tense with semantic version suffix (`.v1`, `.v2`).
- Breaking event change requires version bump.