diff --git a/docs/flows/README.md b/docs/flows/README.md new file mode 100644 index 0000000..a83aaa2 --- /dev/null +++ b/docs/flows/README.md @@ -0,0 +1,199 @@ +# Bridgelet User Flow Diagrams + +This directory contains comprehensive user flow diagrams for the Bridgelet crypto onboarding platform. These diagrams represent the complete user journeys for both Senders and Recipients, including all error scenarios and decision points. + +## Overview + +Bridgelet is a crypto onboarding solution that enables users to send cryptocurrency to recipients who don't have wallets yet. The core concept is "send first, recipient claims later" - similar to a Venmo request but for crypto. + +## Files + +| File | Description | +|------|-------------| +| `sender-flow.mmd` | Complete sender journey from entry to success | +| `recipient-flow.mmd` | Complete recipient journey from claim link to funds received | +| `error-flows.mmd` | All error scenarios and recovery paths | + +## Entry Points + +### Sender Entry Points +1. **Homepage** (`bridgelet.io`) - Primary entry via "Send Funds" CTA +2. **Direct Link** - Direct access to create claim form +3. **Integrated Widget** - Embedded in partner applications + +### Recipient Entry Points +1. **SMS Link** - Claim link sent via text message +2. **Email Link** - Claim link sent via email +3. **WhatsApp** - Claim link shared via messaging +4. **QR Code Scan** - Physical or digital QR code +5. **Direct URL** - Manual entry of claim URL + +## Decision Points Legend + +Decision points in the diagrams are represented as diamond shapes (`{Decision}`) with the following outcomes: + +| Symbol | Meaning | +|--------|---------| +| Yes/No | Binary decision paths | +| Valid/Invalid | Validation results | +| Success/Error | Operation outcomes | +| Multiple options | Branched paths (e.g., wallet types) | + +## System vs User Actions + +### System Actions (Automated) +- Token generation and verification +- Blockchain transaction submission +- Address validation +- Status polling +- Error detection and display + +### User Actions (Interactive) +- Form input and submission +- Wallet connection and signing +- Link sharing via preferred method +- Address entry and confirmation +- Retry/cancel decisions + +## Mobile-First Assumptions + +The diagrams assume a mobile-first design approach, as most recipients will access claim links via mobile devices: + +- **Touch Targets**: Minimum 44x44px for all interactive elements +- **Layout**: Single column, minimal horizontal scrolling +- **Input**: Keyboard-friendly with appropriate input types +- **Performance**: Optimized for mobile networks +- **Browser Support**: iOS Safari and Chrome Android + +## Diagram Notation + +### Node Types +```mermaid +flowchart TD + START([Start/End]) --> PROCESS[Process Step] + PROCESS --> DECISION{Decision} + DECISION -->|Yes| SUBGRAPH[Subgraph Section] + DECISION -->|No| ERROR[Error State] +``` + +### Color Coding (in Mermaid syntax) +- **Start/End**: Rounded rectangles `([ ])` +- **Processes**: Rectangles `[ ]` +- **Decisions**: Diamonds `{ }` +- **Subgraphs**: Grouped sections with labels +- **Errors**: Connected to error handling paths + +## Alignment with Roadmap + +These flows represent the **MVP scope (Q1 2026)**: + +### Implemented (Q1 MVP) +- Basic ephemeral account creation +- XLM and USDC support +- Time-based expiration (1 day to 90 days) +- Wallet-based authentication (Freighter, WalletConnect) +- Claim link generation and sharing +- Sweep execution for claims +- Sender dashboard for tracking + +### Future Enhancements (Post-MVP) +The following are noted but NOT included in current flows: +- Multi-asset claims (one link, multiple tokens) - Q3 2026 +- Scheduled claims (claimable after specific date) - Future +- Conditional claims (email verification required) - Future +- Recurring payments - Future +- Fiat off-ramp (claim to bank account) - Future +- WebSocket real-time updates (currently using polling) - Q2 2026 + +## Key User Flows + +### Sender Journey Summary +1. Entry via homepage or direct link +2. Connect Stellar wallet (if not connected) +3. Fill claim form (amount, asset, recipient name, message, expiry) +4. Review and confirm payment +5. Sign blockchain transaction +6. Receive shareable claim link and QR code +7. Optional: Track status in dashboard + +### Recipient Journey Summary +1. Receive and open claim link +2. System verifies claim token validity +3. View claim details (amount, sender, message, expiry) +4. Enter destination Stellar wallet address +5. Confirm claim details +6. Wait for sweep execution (5-10 seconds) +7. Receive confirmation with transaction details + +### Error Handling Summary +All errors follow a consistent pattern: +1. **Detection**: System identifies error condition +2. **Display**: User-friendly error message (no technical jargon) +3. **Explanation**: Clear description of what happened +4. **Action**: Suggested next steps or recovery options +5. **Support**: Contact information when needed + +## Security Considerations + +- JWT tokens are single-use and time-bound +- Wallet addresses validated client-side and server-side +- No private keys stored or transmitted +- Rate limiting on all endpoints +- HTTPS only for all communications + +## Testing Scenarios + +Based on these flows, the following test scenarios should be covered: + +### Sender Tests +- [ ] Complete happy path from entry to success +- [ ] Wallet connection failures and retries +- [ ] Form validation errors +- [ ] Transaction failures and recovery +- [ ] Dashboard operations (view, cancel, reclaim) + +### Recipient Tests +- [ ] Valid claim link flow +- [ ] Invalid/expired token handling +- [ ] Already claimed scenario +- [ ] Invalid address validation +- [ ] Sweep failure and retry +- [ ] Mobile responsiveness + +### Error Tests +- [ ] All token error states +- [ ] Wallet connection errors +- [ ] Network unavailability +- [ ] Rate limiting behavior +- [ ] Server error handling + +## Viewing the Diagrams + +These diagrams are written in [Mermaid](https://mermaid.js.org/) syntax and can be viewed: + +1. **GitHub/GitLab**: Automatically rendered when viewing `.mmd` files +2. **VS Code**: Install Mermaid extension for live preview +3. **Mermaid Live Editor**: Copy content to [mermaid.live](https://mermaid.live) +4. **Documentation**: Export to PNG/SVG using Mermaid CLI + +## Maintenance + +When updating these diagrams: +1. Ensure changes align with roadmap priorities +2. Update this README if notation or structure changes +3. Verify all acceptance criteria are still met +4. Test diagram rendering after modifications + +## Questions or Feedback + +For questions about these flows: +- Technical implementation: See `/docs/FRONTEND_TECHNICAL_SPEC.md` +- UI/UX requirements: See `/docs/bridgelet-frd-ui-ux.md` +- Project timeline: See `/ROADMAP.md` + +--- + +**Document Version**: 1.0 +**Last Updated**: March 2026 +**Status**: MVP Complete +**Next Review**: After Q2 2026 enhancements diff --git a/docs/flows/error-flows.mmd b/docs/flows/error-flows.mmd new file mode 100644 index 0000000..af3eeb2 --- /dev/null +++ b/docs/flows/error-flows.mmd @@ -0,0 +1,172 @@ +# Bridgelet - Error Flows Diagram + +```mermaid +flowchart TD + START([Error Occurs]) --> ERROR_TYPE{Error Category} + + %% Token/Claim Errors + ERROR_TYPE -->|Token/Claim| TOKEN_ERRORS[Token & Claim Errors] + + subgraph TOKEN_ERROR_SECTION [Token & Claim Errors] + TOKEN_ERRORS --> INVALID_TOKEN[Invalid Token Format] + TOKEN_ERRORS --> EXPIRED_TOKEN[Token Expired] + TOKEN_ERRORS --> ALREADY_CLAIMED[Already Claimed] + TOKEN_ERRORS --> ACCOUNT_NOT_FOUND[Account Not Found] + + INVALID_TOKEN --> DISPLAY_INVALID[Display:
This claim link is invalid
Possible reasons:
- Link malformed
- Link corrupted] + EXPIRED_TOKEN --> DISPLAY_EXPIRED[Display:
This claim link has expired
Contact sender for new link] + ALREADY_CLAIMED --> DISPLAY_CLAIMED[Display:
This payment was already claimed
on [Date]
View transaction on explorer] + ACCOUNT_NOT_FOUND --> DISPLAY_NOT_FOUND[Display:
Claim not found
Link may be invalid] + + DISPLAY_INVALID --> ACTION_INVALID{User Action} + DISPLAY_EXPIRED --> ACTION_EXPIRED{User Action} + DISPLAY_CLAIMED --> ACTION_CLAIMED{User Action} + DISPLAY_NOT_FOUND --> ACTION_NOT_FOUND{User Action} + + ACTION_INVALID -->|Contact Sender| CONTACT_SENDER_1[Contact Sender] + ACTION_INVALID -->|Go Home| GO_HOME_1[Go to Homepage] + ACTION_EXPIRED -->|Contact Sender| CONTACT_SENDER_1 + ACTION_EXPIRED -->|Go Home| GO_HOME_1 + ACTION_CLAIMED -->|View Tx| VIEW_TX_1[View Transaction] + ACTION_CLAIMED -->|Go Home| GO_HOME_1 + ACTION_NOT_FOUND -->|Contact Sender| CONTACT_SENDER_1 + ACTION_NOT_FOUND -->|Go Home| GO_HOME_1 + end + + %% Wallet Errors + ERROR_TYPE -->|Wallet| WALLET_ERRORS[Wallet Connection Errors] + + subgraph WALLET_ERROR_SECTION [Wallet Errors] + WALLET_ERRORS --> NOT_INSTALLED[Wallet Not Installed] + WALLET_ERRORS --> USER_REJECTED[User Rejected Connection] + WALLET_ERRORS --> NETWORK_MISMATCH[Network Mismatch] + WALLET_ERRORS --> TX_REJECTED[Transaction Rejected] + WALLET_ERRORS --> TIMEOUT[Connection Timeout] + + NOT_INSTALLED --> DISPLAY_NOT_INSTALLED[Display:
Wallet not installed
Please install Freighter
or use mobile wallet] + USER_REJECTED --> DISPLAY_REJECTED[Display:
Connection cancelled
Please try again] + NETWORK_MISMATCH --> DISPLAY_MISMATCH[Display:
Wallet on wrong network
Please switch to Testnet] + TX_REJECTED --> DISPLAY_TX_REJECTED[Display:
Transaction declined in wallet
You can retry] + TIMEOUT --> DISPLAY_TIMEOUT[Display:
Connection timed out
Please try again] + + DISPLAY_NOT_INSTALLED --> ACTION_WALLET{User Action} + DISPLAY_REJECTED --> ACTION_WALLET + DISPLAY_MISMATCH --> ACTION_WALLET + DISPLAY_TX_REJECTED --> ACTION_WALLET + DISPLAY_TIMEOUT --> ACTION_WALLET + + ACTION_WALLET -->|Install Wallet| INSTALL_WALLET[Redirect to Install] + ACTION_WALLET -->|Retry| RETRY_WALLET[Retry Connection] + ACTION_WALLET -->|Try Different| TRY_DIFF[Try Different Wallet] + ACTION_WALLET -->|Cancel| CANCEL_WALLET[Cancel] + + INSTALL_WALLET --> WALLET_RETRY{Retry?} + RETRY_WALLET --> WALLET_RETRY + TRY_DIFF --> WALLET_RETRY + WALLET_RETRY -->|Yes| WALLET_ERRORS + WALLET_RETRY -->|No| END_WALLET([End - Cancelled]) + CANCEL_WALLET --> END_WALLET + end + + %% Validation Errors + ERROR_TYPE -->|Validation| VALIDATION_ERRORS[Input Validation Errors] + + subgraph VALIDATION_ERROR_SECTION [Validation Errors] + VALIDATION_ERRORS --> INVALID_ADDRESS[Invalid Wallet Address] + VALIDATION_ERRORS --> INVALID_AMOUNT[Invalid Amount] + VALIDATION_ERRORS --> INVALID_ASSET[Invalid Asset] + VALIDATION_ERRORS --> INVALID_EXPIRY[Invalid Expiration] + + INVALID_ADDRESS --> DISPLAY_ADDR_ERROR[Display:
Invalid Stellar address
Requirements:
- Must start with G
- Must be 56 characters
Example: GD5J6H...] + INVALID_AMOUNT --> DISPLAY_AMOUNT_ERROR[Display:
Please enter valid amount
- Must be positive
- Max 2 decimal places] + INVALID_ASSET --> DISPLAY_ASSET_ERROR[Display:
Selected asset is invalid
Please select from list] + INVALID_EXPIRY --> DISPLAY_EXPIRY_ERROR[Display:
Expiry must be between
1 hour and 90 days] + + DISPLAY_ADDR_ERROR --> FIX_INPUT[Fix Input] + DISPLAY_AMOUNT_ERROR --> FIX_INPUT + DISPLAY_ASSET_ERROR --> FIX_INPUT + DISPLAY_EXPIRY_ERROR --> FIX_INPUT + + FIX_INPUT --> REVALIDATE{Re-validate?} + REVALIDATE -->|Yes| VALIDATION_ERRORS + REVALIDATE -->|No| END_VALIDATION([End - Cancelled]) + end + + %% System Errors + ERROR_TYPE -->|System| SYSTEM_ERRORS[System & Network Errors] + + subgraph SYSTEM_ERROR_SECTION [System Errors] + SYSTEM_ERRORS --> SWEEP_FAILED[Sweep Execution Failed] + SYSTEM_ERRORS --> NETWORK_UNAVAILABLE[Stellar Network Unavailable] + SYSTEM_ERRORS --> RATE_LIMITED[Rate Limit Exceeded] + SYSTEM_ERRORS --> SERVER_ERROR[Server Error 500] + SYSTEM_ERRORS --> INSUFFICIENT_BALANCE[Insufficient Balance] + + SWEEP_FAILED --> DISPLAY_SWEEP_FAIL[Display:
Claim failed
Your funds are safe
Please try again] + NETWORK_UNAVAILABLE --> DISPLAY_NETWORK[Display:
Network temporarily unavailable
We're having trouble connecting
to Stellar network] + RATE_LIMITED --> DISPLAY_RATE_LIMIT[Display:
Too many attempts
Please wait [countdown]
before retrying] + SERVER_ERROR --> DISPLAY_SERVER[Display:
Something went wrong on our end
Please try again or contact support] + INSUFFICIENT_BALANCE --> DISPLAY_BALANCE[Display:
Insufficient balance
to create payment
Check wallet balance] + + DISPLAY_SWEEP_FAIL --> ACTION_SYSTEM{User Action} + DISPLAY_NETWORK --> ACTION_SYSTEM + DISPLAY_RATE_LIMIT --> ACTION_SYSTEM + DISPLAY_SERVER --> ACTION_SYSTEM + DISPLAY_BALANCE --> ACTION_SYSTEM + + ACTION_SYSTEM -->|Retry| RETRY_SYSTEM[Retry with Backoff] + ACTION_SYSTEM -->|Check Status| CHECK_TX_STATUS[Check Transaction Status] + ACTION_SYSTEM -->|Contact Support| CONTACT_SUPPORT[Contact Support] + ACTION_SYSTEM -->|Cancel| CANCEL_SYSTEM[Cancel] + + RETRY_SYSTEM --> RETRY_COUNT{Retry Count} + RETRY_COUNT -->|< 3| SYSTEM_ERRORS + RETRY_COUNT -->|>= 3| MAX_RETRIES[Max Retries Reached] + MAX_RETRIES --> CONTACT_SUPPORT + + CHECK_TX_STATUS --> TX_STATUS{Transaction Status?} + TX_STATUS -->|Success| SHOW_SUCCESS[Show Success] + TX_STATUS -->|Failed| SYSTEM_ERRORS + TX_STATUS -->|Pending| WAIT_PENDING[Wait & Retry] + WAIT_PENDING --> RETRY_SYSTEM + + CONTACT_SUPPORT --> END_SUPPORT([End - Support]) + CANCEL_SYSTEM --> END_SYSTEM([End - Cancelled]) + SHOW_SUCCESS --> END_SUCCESS([End - Success]) + end + + %% Recovery Strategies + subgraph RECOVERY [Recovery Strategies] + direction LR + R1[Exponential Backoff
2s, 4s, 8s...] + R2[Status Polling
Check current state] + R3[Graceful Degradation
Show cached data] + R4[Clear Error Messages
No technical jargon] + R5[Support Contact
Request ID provided] + end + + %% Error Handling Best Practices + subgraph BEST_PRACTICES [Error Handling Best Practices] + direction LR + BP1[Explain what happened] + BP2[Suggest next steps] + BP3[Provide support contact] + BP4[No raw error codes] + BP5[Don't blame user] + end + + %% Connect recovery to errors + RETRY_SYSTEM -.->|Uses| R1 + CHECK_TX_STATUS -.->|Uses| R2 + CONTACT_SUPPORT -.->|Provides| R5 + + %% Final End States + GO_HOME_1 --> END_TOKEN([End]) + VIEW_TX_1 --> END_TOKEN + END_WALLET --> END_ALL + END_VALIDATION --> END_ALL + END_SUPPORT --> END_ALL + END_SYSTEM --> END_ALL + END_TOKEN --> END_ALL([END]) + END_SUCCESS --> END_ALL +``` diff --git a/docs/flows/recipient-flow.mmd b/docs/flows/recipient-flow.mmd new file mode 100644 index 0000000..ad4ceb8 --- /dev/null +++ b/docs/flows/recipient-flow.mmd @@ -0,0 +1,152 @@ +# Bridgelet - Recipient User Flow Diagram + +```mermaid +flowchart TD + %% Entry Points + START([START]) --> ENTRY{Entry Point} + ENTRY -->|SMS Link| SMS_OPEN[Open SMS Link] + ENTRY -->|Email Link| EMAIL_OPEN[Open Email Link] + ENTRY -->|WhatsApp| WA_OPEN[Open WhatsApp Link] + ENTRY -->|QR Code Scan| QR_OPEN[Scan QR Code] + ENTRY -->|Direct URL| DIRECT_OPEN[Enter Claim URL] + + SMS_OPEN --> EXTRACT_TOKEN + EMAIL_OPEN --> EXTRACT_TOKEN + WA_OPEN --> EXTRACT_TOKEN + QR_OPEN --> EXTRACT_TOKEN + DIRECT_OPEN --> EXTRACT_TOKEN[Extract Token from URL
https://claim.bridgelet.io/c/{token}] + + %% Token Verification + subgraph VERIFICATION [Claim Verification] + EXTRACT_TOKEN --> CHECK_TOKEN{Token Extracted?} + CHECK_TOKEN -->|No| INVALID_URL[Show Invalid URL Error] + INVALID_URL --> END_INVALID([END - Invalid Link]) + + CHECK_TOKEN -->|Yes| VERIFY_BACKEND[Verify with Backend
POST /api/claims/verify] + VERIFY_BACKEND --> TOKEN_STATUS{Token Status?} + end + + %% Token Error States + TOKEN_STATUS -->|Invalid| ERROR_INVALID[Error: Invalid Token] + TOKEN_STATUS -->|Expired| ERROR_EXPIRED[Error: Link Expired] + TOKEN_STATUS -->|Already Claimed| ERROR_CLAIMED[Error: Already Claimed] + TOKEN_STATUS -->|Account Not Found| ERROR_NOT_FOUND[Error: Claim Not Found] + + ERROR_INVALID --> CONTACT_SENDER[Contact Sender for New Link] + ERROR_EXPIRED --> CONTACT_SENDER + ERROR_CLAIMED --> VIEW_TX[View Transaction on Explorer] + ERROR_NOT_FOUND --> CONTACT_SENDER + + CONTACT_SENDER --> END_ERROR([END - Error]) + VIEW_TX --> END_ERROR + + %% Valid Token Flow + TOKEN_STATUS -->|Valid| SHOW_CLAIM[Display Claim Landing Page] + + subgraph CLAIM_DISPLAY [Claim Details Display] + SHOW_CLAIM --> SHOW_HEADER[Header: You've Received Crypto!] + SHOW_HEADER --> SHOW_SENDER[Show Sender Name
From: Alice] + SHOW_HEADER --> SHOW_MESSAGE[Show Message
Happy Birthday!] + SHOW_HEADER --> SHOW_AMOUNT[Show Amount
50 USDC ≈ $50.00] + SHOW_HEADER --> SHOW_EXPIRY[Show Expiry Date
Expires: March 15, 2026] + + SHOW_SENDER --> CLAIM_CTA + SHOW_MESSAGE --> CLAIM_CTA + SHOW_AMOUNT --> CLAIM_CTA + SHOW_EXPIRY --> CLAIM_CTA[CTA: Claim Your Funds] + end + + CLAIM_CTA --> CHECK_WALLET{Have Wallet?} + + %% No Wallet Path + CHECK_WALLET -->|No| WALLET_HELP[Show Wallet Help] + WALLET_HELP --> WALLET_OPTIONS{Select Platform} + WALLET_OPTIONS -->|Mobile| MOBILE_WALLET[LOBSTR App] + WALLET_OPTIONS -->|Desktop| DESKTOP_WALLET[Freighter Extension] + + MOBILE_WALLET --> REDIRECT_STORE[Redirect to App Store] + DESKTOP_WALLET --> REDIRECT_INSTALL[Redirect to Install Page] + + REDIRECT_STORE --> WALLET_CREATED{Wallet Created?} + REDIRECT_INSTALL --> WALLET_CREATED + + WALLET_CREATED -->|No| END_NO_WALLET([END - No Wallet]) + WALLET_CREATED -->|Yes| ENTER_ADDRESS + + %% Wallet Entry + CHECK_WALLET -->|Yes| ENTER_ADDRESS[Enter Wallet Address] + + subgraph ADDRESS_ENTRY [Wallet Address Input] + ENTER_ADDRESS --> INPUT_FIELD[Input Field:
Enter Stellar Address (starts with G)] + INPUT_FIELD --> REALTIME_VALIDATE[Real-time Validation] + REALTIME_VALIDATE --> ADDR_VALID{Address Valid?} + + ADDR_VALID -->|No| SHOW_ADDR_ERROR[Show Error:
- Must start with G
- Must be 56 characters] + SHOW_ADDR_ERROR --> INPUT_FIELD + + ADDR_VALID -->|Yes| SHOW_CHECKMARK[Show Green Checkmark] + SHOW_CHECKMARK --> PREV_ADDR{Previous Address?} + PREV_ADDR -->|Yes| SUGGEST_PREV[Suggest Previous Address] + SUGGEST_PREV --> USE_PREV{Use Previous?} + USE_PREV -->|Yes| AUTO_FILL[Auto-fill Address] + USE_PREV -->|No| CONTINUE_ADDR + PREV_ADDR -->|No| CONTINUE_ADDR + AUTO_FILL --> CONTINUE_ADDR[Continue Button] + end + + CONTINUE_ADDR --> CONFIRM_CLAIM[Confirm Claim Screen] + + %% Confirmation + subgraph CONFIRMATION [Claim Confirmation] + CONFIRM_CLAIM --> REVIEW_DETAILS[Review Details:
- Amount: 50 USDC
- To: GD5J6H...4XR
- Warning: Cannot be reversed] + REVIEW_DETAILS --> CONFIRM_CTA{Confirm?} + CONFIRM_CTA -->|No| BACK_TO_ADDR[Back to Address Entry] + BACK_TO_ADDR --> ENTER_ADDRESS + end + + CONFIRM_CTA -->|Yes| PROCESSING[Processing Claim] + + %% Processing + subgraph PROCESSING_CLAIM [Sweep Execution] + PROCESSING --> VERIFY_TOKEN[Verify Token] + VERIFY_TOKEN --> AUTH_TRANSFER[Authorize Transfer] + AUTH_TRANSFER --> EXECUTE_SWEEP[Execute Sweep
~5-10 seconds] + EXECUTE_SWEEP --> SWEEP_STATUS{Sweep Success?} + + SWEEP_STATUS -->|No| SWEEP_ERROR[Show Sweep Error] + SWEEP_ERROR --> CHECK_STATUS{Check Status} + CHECK_STATUS -->|Unclaimed| RETRY_SWEEP{Retry?} + RETRY_SWEEP -->|Yes| PROCESSING + RETRY_SWEEP -->|No| END_FAILED([END - Failed]) + CHECK_STATUS -->|Claimed| SHOW_ALREADY_CLAIMED[Show Already Claimed] + SHOW_ALREADY_CLAIMED --> END_FAILED + end + + SWEEP_STATUS -->|Yes| SUCCESS[Claim Success] + + %% Success + subgraph SUCCESS_SECTION [Success Screen] + SUCCESS --> SUCCESS_MSG[Success Message:
You've received 50 USDC!] + SUCCESS_MSG --> TX_DETAILS[Transaction Details:
- Amount
- Destination Address
- Transaction Hash] + TX_DETAILS --> VIEW_EXPLORER[View on Stellar Explorer] + + VIEW_EXPLORER --> NEXT_STEPS{Next Steps?} + NEXT_STEPS -->|Check Balance| OPEN_VIEWER[Open Stellar Account Viewer] + NEXT_STEPS -->|Send Crypto| CREATE_ACCOUNT[Create Bridgelet Account] + NEXT_STEPS -->|Done| DONE_BTN[Done] + + OPEN_VIEWER --> END_SUCCESS + CREATE_ACCOUNT --> END_SUCCESS + DONE_BTN --> END_SUCCESS([END - Success]) + end + + %% Mobile Considerations Note + subgraph MOBILE_NOTE [Mobile-First Design] + direction LR + NOTE1[Large tap targets
min 44x44px] + NOTE2[Single column layout] + NOTE3[Minimal scrolling] + NOTE4[Keyboard-friendly] + NOTE5[iOS Safari &
Chrome Android] + end +``` diff --git a/docs/flows/sender-flow.mmd b/docs/flows/sender-flow.mmd new file mode 100644 index 0000000..f8f0e26 --- /dev/null +++ b/docs/flows/sender-flow.mmd @@ -0,0 +1,147 @@ +# Bridgelet - Sender User Flow Diagram + +```mermaid +flowchart TD + %% Entry Points + START([START]) --> ENTRY{Entry Point} + ENTRY -->|Homepage| HP[Homepage
bridgelet.io] + ENTRY -->|Direct Link| CL[Create Claim Link] + ENTRY -->|Widget| WIDGET[Integrated App Widget] + + %% Homepage Flow + HP --> SEND_FUNDS{Click Send Funds?} + SEND_FUNDS -->|No| HOW_IT_WORKS[Show How It Works] + HOW_IT_WORKS --> SEND_FUNDS + SEND_FUNDS -->|Yes| CHECK_WALLET{Wallet Connected?} + + CL --> CHECK_WALLET + WIDGET --> CHECK_WALLET + + %% Wallet Connection + CHECK_WALLET -->|No| WALLET_MODAL[Show Wallet Selection Modal] + WALLET_MODAL --> WALLET_TYPE{Select Wallet} + WALLET_TYPE -->|Freighter| CONNECT_F[Connect Freighter] + WALLET_TYPE -->|Mobile| CONNECT_WC[Connect WalletConnect] + WALLET_TYPE -->|Albedo| CONNECT_A[Connect Albedo] + + CONNECT_F --> WALLET_SUCCESS{Connection Success?} + CONNECT_WC --> WALLET_SUCCESS + CONNECT_A --> WALLET_SUCCESS + + WALLET_SUCCESS -->|No| WALLET_ERROR[Show Connection Error] + WALLET_ERROR --> WALLET_MODAL + + WALLET_SUCCESS -->|Yes| AUTH[Authenticate with Backend] + AUTH --> AUTH_SUCCESS{Auth Success?} + AUTH_SUCCESS -->|No| AUTH_ERROR[Show Auth Error] + AUTH_ERROR --> WALLET_MODAL + AUTH_SUCCESS -->|Yes| CREATE_FORM + + CHECK_WALLET -->|Yes| CREATE_FORM[Create Claim Form] + + %% Create Claim Form + subgraph FORM_SECTION [Create Claim Form] + CREATE_FORM --> INPUT_AMOUNT[Enter Amount] + INPUT_AMOUNT --> SELECT_ASSET[Select Asset
XLM/USDC/etc] + SELECT_ASSET --> INPUT_NAME[Recipient Name
(Optional)] + INPUT_NAME --> INPUT_MESSAGE[Message
(Optional)] + INPUT_MESSAGE --> SET_EXPIRY[Set Expiration
24h/7d/30d/90d] + SET_EXPIRY --> VALIDATE_FORM{Form Valid?} + end + + VALIDATE_FORM -->|No| SHOW_ERRORS[Show Validation Errors] + SHOW_ERRORS --> CREATE_FORM + + VALIDATE_FORM -->|Yes| COST_BREAKDOWN[Show Cost Breakdown
Amount + Network Fee] + COST_BREAKDOWN --> CONTINUE{Click Continue?} + CONTINUE -->|No| CREATE_FORM + CONTINUE -->|Yes| CONFIRM_SCREEN[Confirm Payment Screen] + + %% Confirmation + subgraph CONFIRM_SECTION [Confirm Payment] + CONFIRM_SCREEN --> REVIEW[Review Summary
Amount, Recipient, Expiry] + REVIEW --> WALLET_STATUS{Wallet Still Connected?} + WALLET_STATUS -->|No| RECONNECT[Reconnect Wallet] + RECONNECT --> CONFIRM_SCREEN + WALLET_STATUS -->|Yes| SIGN_TX{Sign Transaction?} + SIGN_TX -->|No| BACK_TO_FORM[Back to Form] + BACK_TO_FORM --> CREATE_FORM + end + + SIGN_TX -->|Yes| PROCESSING[Processing Transaction] + + %% Processing + subgraph PROCESSING_SECTION [Blockchain Processing] + PROCESSING --> GENERATE_EPHEMERAL[Generate Ephemeral Account] + GENERATE_EPHEMERAL --> CREATE_JWT[Create JWT Claim Token] + CREATE_JWT --> SUBMIT_TX[Submit to Stellar Network] + SUBMIT_TX --> WAIT_CONFIRM[Wait for Confirmation
~5 seconds] + WAIT_CONFIRM --> TX_SUCCESS{Transaction Success?} + end + + TX_SUCCESS -->|No| TX_ERROR[Show Transaction Error] + TX_ERROR --> RETRY_TX{Retry?} + RETRY_TX -->|Yes| PROCESSING + RETRY_TX -->|No| CANCEL_TX[Cancel Payment] + CANCEL_TX --> CREATE_FORM + + TX_SUCCESS -->|Yes| SUCCESS_SCREEN[Payment Success Screen] + + %% Success + subgraph SUCCESS_SECTION [Success & Sharing] + SUCCESS_SCREEN --> SHOW_LINK[Display Claim Link
https://claim.bridgelet.io/c/xxx] + SHOW_LINK --> SHOW_QR[Display QR Code] + SHOW_QR --> SHARE_OPTIONS[Share Options] + SHARE_OPTIONS --> COPY[Copy Link] + SHARE_OPTIONS --> SMS[Share via SMS] + SHARE_OPTIONS --> EMAIL[Share via Email] + SHARE_OPTIONS --> WHATSAPP[Share via WhatsApp] + end + + COPY --> NEXT_ACTION + SMS --> NEXT_ACTION + EMAIL --> NEXT_ACTION + WHATSAPP --> NEXT_ACTION + + NEXT_ACTION{Next Action?} + NEXT_ACTION -->|Track Status| DASHBOARD[Sender Dashboard] + NEXT_ACTION -->|Send Another| CREATE_FORM + NEXT_ACTION -->|Done| END_SUCCESS([END - Success]) + + %% Dashboard + subgraph DASHBOARD_SECTION [Sender Dashboard] + DASHBOARD --> LIST_CLAIMS[List All Sent Claims] + LIST_CLAIMS --> FILTER{Filter By} + FILTER -->|All| SHOW_ALL[Show All] + FILTER -->|Unclaimed| SHOW_UNCLAIMED[Show Unclaimed] + FILTER -->|Claimed| SHOW_CLAIMED[Show Claimed] + FILTER -->|Expired| SHOW_EXPIRED[Show Expired] + + SHOW_ALL --> SELECT_CLAIM{Select Claim} + SHOW_UNCLAIMED --> SELECT_CLAIM + SHOW_CLAIMED --> SELECT_CLAIM + SHOW_EXPIRED --> SELECT_CLAIM + + SELECT_CLAIM --> VIEW_DETAILS[View Claim Details] + VIEW_DETAILS --> CLAIM_STATUS{Claim Status?} + + CLAIM_STATUS -->|Unclaimed| SHOW_UNCLAIMED_ACTIONS[Actions:
- Cancel
- Wait for Claim] + CLAIM_STATUS -->|Expired| SHOW_EXPIRED_ACTIONS[Actions:
- Reclaim Funds] + CLAIM_STATUS -->|Claimed| SHOW_CLAIMED_INFO[Show Claim Info
- Claimed Date
- Transaction Hash] + + SHOW_UNCLAIMED_ACTIONS --> CANCEL_CLAIM{Cancel?} + CANCEL_CLAIM -->|Yes| PROCESS_CANCEL[Process Cancel] + PROCESS_CANCEL --> REFUND[Refund to Sender] + REFUND --> DASHBOARD + CANCEL_CLAIM -->|No| DASHBOARD + + SHOW_EXPIRED_ACTIONS --> RECLAIM{Reclaim?} + RECLAIM -->|Yes| PROCESS_RECLAIM[Process Reclaim] + PROCESS_RECLAIM --> REFUND + RECLAIM -->|No| DASHBOARD + + SHOW_CLAIMED_INFO --> DASHBOARD + end + + DASHBOARD --> END_DASHBOARD([END - Dashboard]) +```