Skip to content

Implemented the Sender & Receipt User Flow Diagram #34

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
phertyameen merged 1 commit into from
Mar 6, 2026
Merged

Implemented the Sender & Receipt User Flow Diagram #34

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
199 changes: 199 additions & 0 deletions docs/flows/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
172 changes: 172 additions & 0 deletions docs/flows/error-flows.mmd
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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:<br/>This claim link is invalid<br/>Possible reasons:<br/>- Link malformed<br/>- Link corrupted]
EXPIRED_TOKEN --> DISPLAY_EXPIRED[Display:<br/>This claim link has expired<br/>Contact sender for new link]
ALREADY_CLAIMED --> DISPLAY_CLAIMED[Display:<br/>This payment was already claimed<br/>on [Date]<br/>View transaction on explorer]
ACCOUNT_NOT_FOUND --> DISPLAY_NOT_FOUND[Display:<br/>Claim not found<br/>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:<br/>Wallet not installed<br/>Please install Freighter<br/>or use mobile wallet]
USER_REJECTED --> DISPLAY_REJECTED[Display:<br/>Connection cancelled<br/>Please try again]
NETWORK_MISMATCH --> DISPLAY_MISMATCH[Display:<br/>Wallet on wrong network<br/>Please switch to Testnet]
TX_REJECTED --> DISPLAY_TX_REJECTED[Display:<br/>Transaction declined in wallet<br/>You can retry]
TIMEOUT --> DISPLAY_TIMEOUT[Display:<br/>Connection timed out<br/>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:<br/>Invalid Stellar address<br/>Requirements:<br/>- Must start with G<br/>- Must be 56 characters<br/>Example: GD5J6H...]
INVALID_AMOUNT --> DISPLAY_AMOUNT_ERROR[Display:<br/>Please enter valid amount<br/>- Must be positive<br/>- Max 2 decimal places]
INVALID_ASSET --> DISPLAY_ASSET_ERROR[Display:<br/>Selected asset is invalid<br/>Please select from list]
INVALID_EXPIRY --> DISPLAY_EXPIRY_ERROR[Display:<br/>Expiry must be between<br/>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:<br/>Claim failed<br/>Your funds are safe<br/>Please try again]
NETWORK_UNAVAILABLE --> DISPLAY_NETWORK[Display:<br/>Network temporarily unavailable<br/>We're having trouble connecting<br/>to Stellar network]
RATE_LIMITED --> DISPLAY_RATE_LIMIT[Display:<br/>Too many attempts<br/>Please wait [countdown]<br/>before retrying]
SERVER_ERROR --> DISPLAY_SERVER[Display:<br/>Something went wrong on our end<br/>Please try again or contact support]
INSUFFICIENT_BALANCE --> DISPLAY_BALANCE[Display:<br/>Insufficient balance<br/>to create payment<br/>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<br/>2s, 4s, 8s...]
R2[Status Polling<br/>Check current state]
R3[Graceful Degradation<br/>Show cached data]
R4[Clear Error Messages<br/>No technical jargon]
R5[Support Contact<br/>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
```
Loading