| 1 |
|
defmodule WalletJourney do |
| 2 |
|
@moduledoc """ |
| 3 |
|
Public interface for the WalletJourney application. |
| 4 |
|
|
| 5 |
|
## Responsibilities |
| 6 |
|
- End-to-end transfer journey orchestration. |
| 7 |
|
- Coordinates limits checks, fee calculation, transfer initiation, fund |
| 8 |
|
reservation, and transfer completion as a sequential step pipeline. |
| 9 |
|
- Emits domain events and structured audit events at each lifecycle transition. |
| 10 |
|
- Supports compensation (cancellation) when a failure occurs after funds |
| 11 |
|
have been initiated. |
| 12 |
|
|
| 13 |
|
## Delegated to sub-modules |
| 14 |
|
- `WalletJourney.Commands.StartJourney` — execute a full transfer journey. |
| 15 |
|
- `WalletJourney.Commands.AdvanceJourneyStep` — record an individual step completion. |
| 16 |
|
- `WalletJourney.Commands.CompensateJourney` — compensate a journey after failure. |
| 17 |
|
- `WalletJourney.Queries.GetJourneyState` — retrieve journey state by ID. |
| 18 |
|
|
| 19 |
|
## Journey steps (in order) |
| 20 |
|
1. `:limits_check` — verify transfer is within configured limits |
| 21 |
|
2. `:fee_calculation` — compute applicable fees |
| 22 |
|
3. `:initiate_transfer` — create the transfer record via wallet_transfers |
| 23 |
|
4. `:reserve_funds` — reserve funds on the transfer |
| 24 |
|
5. `:complete_transfer` — complete the reserved transfer |
| 25 |
|
|
| 26 |
|
## Events broadcast on `"wallet_journey:events"` topic |
| 27 |
|
- `JourneyStarted.v1` |
| 28 |
|
- `JourneyStepAdvanced.v1` |
| 29 |
|
- `JourneyCompleted.v1` |
| 30 |
|
- `JourneyCompensated.v1` |
| 31 |
|
|
| 32 |
|
## Forbidden |
| 33 |
|
- Direct ledger writes (responsibility of `wallet_ledger`). |
| 34 |
|
- Auth logic (responsibility of `wallet_auth`). |
| 35 |
|
- Circular dependencies on `wallet_ledger` or `wallet_accounts`. |
| 36 |
|
""" |
| 37 |
|
|
| 38 |
|
alias WalletJourney.Commands.{StartJourney, AdvanceJourneyStep, CompensateJourney} |
| 39 |
|
alias WalletJourney.Queries.GetJourneyState |
| 40 |
|
|
| 41 |
|
@doc "Start and execute a full transfer journey." |
| 42 |
:-( |
defdelegate start_journey(params), to: StartJourney, as: :execute |
| 43 |
|
|
| 44 |
|
@doc "Advance a journey by recording a step as completed." |
| 45 |
:-( |
defdelegate advance_step(journey_id, step, result \\ :ok), |
| 46 |
|
to: AdvanceJourneyStep, |
| 47 |
|
as: :execute |
| 48 |
|
|
| 49 |
|
@doc "Compensate a journey by cancelling its associated transfer." |
| 50 |
:-( |
defdelegate compensate(journey_id, reason), to: CompensateJourney, as: :execute |
| 51 |
|
|
| 52 |
|
@doc "Retrieve the current state of a journey by ID." |
| 53 |
:-( |
defdelegate get_journey(journey_id), to: GetJourneyState, as: :execute |
| 54 |
|
end |