| 1 |
|
defmodule WalletTransfers do |
| 2 |
|
@moduledoc """ |
| 3 |
|
Public interface for the WalletTransfers application. |
| 4 |
|
|
| 5 |
|
## Responsibilities |
| 6 |
|
- Transfer lifecycle management: initiate, reserve, complete, fail, cancel. |
| 7 |
|
- Transfer status queries: retrieve by ID or list by user. |
| 8 |
|
- Per-transfer locking to prevent concurrent state transitions (ADR 0004). |
| 9 |
|
|
| 10 |
|
## Delegated to sub-modules |
| 11 |
|
- `WalletTransfers.Commands.InitiateTransfer` — initiate a new transfer. |
| 12 |
|
- `WalletTransfers.Commands.ReserveTransferFunds` — reserve funds on an initiated transfer. |
| 13 |
|
- `WalletTransfers.Commands.CompleteTransfer` — complete a reserved transfer. |
| 14 |
|
- `WalletTransfers.Commands.FailTransfer` — fail a reserved transfer with a reason. |
| 15 |
|
- `WalletTransfers.Commands.CancelTransfer` — cancel an initiated transfer with a reason. |
| 16 |
|
- `WalletTransfers.Queries.GetTransfer` — fetch transfer by ID. |
| 17 |
|
- `WalletTransfers.Queries.ListUserTransfers` — list all transfers for a user. |
| 18 |
|
|
| 19 |
|
## Transfer state machine |
| 20 |
|
States: `:initiated`, `:reserved`, `:completed`, `:failed`, `:canceled` |
| 21 |
|
|
| 22 |
|
Allowed transitions: |
| 23 |
|
- `initiated -> reserved` (via `reserve/2`) |
| 24 |
|
- `reserved -> completed` (via `complete/2`) |
| 25 |
|
- `reserved -> failed` (via `fail/3`) |
| 26 |
|
- `initiated -> canceled` (via `cancel/3`) |
| 27 |
|
|
| 28 |
|
Terminal states: `:completed`, `:failed`, `:canceled` |
| 29 |
|
|
| 30 |
|
## Boundary constraints |
| 31 |
|
- No direct ledger writes; delegate to `wallet_ledger` from the orchestration layer. |
| 32 |
|
- No auth logic; that is the responsibility of `wallet_auth`. |
| 33 |
|
- No circular dependencies on `wallet_ledger` or `wallet_accounts`. |
| 34 |
|
- All state transitions go through command handlers with lock acquisition. |
| 35 |
|
|
| 36 |
|
## Events broadcast on `"wallet_transfers:events"` topic |
| 37 |
|
- `TransferInitiated.v1` |
| 38 |
|
- `TransferReserved.v1` |
| 39 |
|
- `TransferCompleted.v1` |
| 40 |
|
- `TransferFailed.v1` |
| 41 |
|
- `TransferCanceled.v1` |
| 42 |
|
""" |
| 43 |
|
|
| 44 |
|
alias WalletTransfers.Commands.{ |
| 45 |
|
InitiateTransfer, |
| 46 |
|
ReserveTransferFunds, |
| 47 |
|
CompleteTransfer, |
| 48 |
|
FailTransfer, |
| 49 |
|
CancelTransfer |
| 50 |
|
} |
| 51 |
|
|
| 52 |
|
alias WalletTransfers.Queries.{GetTransfer, ListUserTransfers} |
| 53 |
|
|
| 54 |
|
@doc "Initiate a new transfer between two accounts." |
| 55 |
:-( |
defdelegate initiate(user_id, from_account_id, to_account_id, amount, currency, opts \\ []), |
| 56 |
|
to: InitiateTransfer, |
| 57 |
|
as: :execute |
| 58 |
|
|
| 59 |
|
@doc "Reserve funds on an initiated transfer." |
| 60 |
:-( |
defdelegate reserve(transfer_id, opts \\ []), |
| 61 |
|
to: ReserveTransferFunds, |
| 62 |
|
as: :execute |
| 63 |
|
|
| 64 |
|
@doc "Complete a reserved transfer." |
| 65 |
:-( |
defdelegate complete(transfer_id, opts \\ []), |
| 66 |
|
to: CompleteTransfer, |
| 67 |
|
as: :execute |
| 68 |
|
|
| 69 |
|
@doc "Fail a reserved transfer with a reason." |
| 70 |
:-( |
defdelegate fail(transfer_id, reason, opts \\ []), |
| 71 |
|
to: FailTransfer, |
| 72 |
|
as: :execute |
| 73 |
|
|
| 74 |
|
@doc "Cancel an initiated transfer with a reason." |
| 75 |
:-( |
defdelegate cancel(transfer_id, reason, opts \\ []), |
| 76 |
|
to: CancelTransfer, |
| 77 |
|
as: :execute |
| 78 |
|
|
| 79 |
|
@doc "Retrieve a transfer by transfer_id." |
| 80 |
:-( |
defdelegate get_transfer(transfer_id), |
| 81 |
|
to: GetTransfer, |
| 82 |
|
as: :execute |
| 83 |
|
|
| 84 |
|
@doc "List all transfers for a user." |
| 85 |
:-( |
defdelegate list_user_transfers(user_id), |
| 86 |
|
to: ListUserTransfers, |
| 87 |
|
as: :execute |
| 88 |
|
end |