d-bis/CurrenciCombo
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
CurrenciCombo/docs/UI_UX_Specification_Builder_V2.md

19 KiB
Raw Permalink Blame History

UI/UX Specification: ISO-20022 Combo Builder v2

Overview

This document specifies the user interface and user experience for the Combo Builder v2, which enables users to compose multi-step financial workflows combining DeFi protocols and traditional banking rails (ISO-20022). The UI is inspired by Furucombo's Create page but extends it with compliance overlays, hybrid adapter support, and optional simulation.

Design Principles

  1. Composability: Drag-and-drop interface for building complex financial workflows
  2. Transparency: Clear display of compliance status, fees, and execution risks
  3. Flexibility: Support for both DeFi and fiat/DTL adapters with selection control
  4. User Control: Optional simulation for advanced users, mandatory compliance checks
  5. Accessibility: Intuitive for non-developers while providing advanced features

1. Main Builder Canvas

Layout Structure

┌─────────────────────────────────────────────────────────────────┐
│ Header: [Combo Builder] [User Identity] [Wallet] [Settings]     │
├─────────────┬─────────────────────────────────────────────────────────┤
│             │                                                      │
│  Adapter    │              Canvas (Drop Zone)                     │
│  Palette    │              ┌─────────────────────┐               │
│             │              │  Step 1: Borrow     │               │
│  [DeFi]     │              │  💰 CBDC_USD: 100k  │               │
│  - Swap     │              └─────────────────────┘               │
│  - Borrow   │              ┌─────────────────────┐               │
│  - Deposit  │              │  Step 2: Swap       │               │
│  - Bridge   │              │  🔄 USD → EUR       │               │
│             │              └─────────────────────┘               │
│  [Fiat]     │              ┌─────────────────────┐               │
│  - Pay      │              │  Step 3: Pay         │               │
│  - Repay    │              │  📤 EUR to IBAN     │               │
│  - Transfer │              └─────────────────────┘               │
│             │                                                      │
│  [Compliance]│                                                    │
│  ✓ LEI     │                                                      │
│  ✓ KYC     │                                                      │
│  ✓ AML     │                                                      │
└─────────────┴─────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ Summary Panel:                                                   │
│ Initial Funds: 100,000 CBDC_USD                                 │
│ You will receive: ~78,000 EUR                                   │
│ Fees: 0.2% (200 USD) | Compliance: ✓ | Simulation: [Toggle]   │
│ [Review & Sign] [Simulate] [Save Draft]                        │
└─────────────────────────────────────────────────────────────────┘

Key Components

A. Adapter Palette (Left Sidebar)

  • DeFi Section: Swappable protocols (Uniswap, Aave, Compound, etc.)
  • Fiat/DTL Section: Banking rails (ISO-20022 pay, SWIFT, SEPA, etc.)
  • Compliance Badge: Shows current user compliance status (LEI/DID/KYC/AML)
  • Filter Toggle: "Show All" / "Show Whitelisted Only" / "Show DeFi Only" / "Show Fiat Only"

B. Canvas (Center)

  • Drop Zone: Visual area where users place workflow steps
  • Step Cards: Each step shows:
    • Step number (1, 2, 3...)
    • Icon (💰, 🔄, 💳, 📤)
    • Step type and summary
    • Compliance badge (if applicable)
    • Drag handle (⋮⋮) for reordering
    • Edit/Remove buttons

C. Summary Panel (Bottom)

  • Initial Funds: What user must supply (from wallet or borrow)
  • You will receive: Expected output at workflow end
  • Fee Display: "Included 0.2% fee" (if applicable)
  • Compliance Status: Visual indicators (✓ LEI, ✓ KYC, ✓ AML, ✓ DID)
  • Simulation Toggle: Optional checkbox for advanced users
  • Action Buttons: Review & Sign, Simulate (optional), Save Draft

2. Step Configuration Drawer

Layout

┌────────────────────────────────────────────────────────┐
│ Configure Step: Swap                    [X]            │
├────────────────────────────────────────────────────────┤
│                                                        │
│ From Token: [CBDC_USD ▼]                              │
│ Amount: [100,000]                                      │
│                                                        │
│ To Token: [CBDC_EUR ▼]                                 │
│ Min Receive: [90,000] (auto-calculated)                │
│                                                        │
│ Slippage: [0.5%] (default)                            │
│                                                        │
│ ────────────────────────────────────────────────────── │
│                                                        │
│ Compliance Requirements:                               │
│ ☑ LEI Required: [5493000IBP32UQZ0KL24]                │
│ ☑ KYC Status: ✓ Verified                              │
│ ☑ AML Check: ✓ Passed                                 │
│                                                        │
│ [Save] [Cancel]                                        │
└────────────────────────────────────────────────────────┘

Features

  • Token/Asset Selection: Dropdown with supported tokens (DeFi) or currencies (Fiat)
  • Amount Input: Numeric input with validation
  • Compliance Fields: Auto-populated from user session (LEI, KYC, AML status)
  • Dependency Visualization: Shows which previous steps feed into this step
  • Validation Feedback: Real-time error messages (insufficient balance, invalid IBAN, etc.)

3. Simulation Results Panel (Optional)

Layout

┌────────────────────────────────────────────────────────┐
│ Simulation Results                    [Close]          │
├────────────────────────────────────────────────────────┤
│ Status: ✓ Simulation Successful                        │
│                                                        │
│ Execution Summary:                                     │
│ • Step 1 (Borrow): ✓ 100,000 CBDC_USD                 │
│ • Step 2 (Swap): ✓ 90,000 CBDC_EUR (estimated)        │
│ • Step 3 (Pay): ✓ 78,000 EUR to beneficiary           │
│                                                        │
│ Gas Estimate: 450,000 gas                             │
│ Estimated Cost: $25.50 (at 50 gwei)                    │
│                                                        │
│ Slippage Risk: Low (0.2% expected)                    │
│ Liquidity Check: ✓ Sufficient                          │
│                                                        │
│ Compliance: ✓ All checks passed                        │
│                                                        │
│ [Run Simulation Again] [Proceed to Sign]              │
└────────────────────────────────────────────────────────┘

Features

  • Step-by-Step Results: Shows success/failure for each step
  • Gas Estimation: Calculated gas cost for entire workflow
  • Slippage Analysis: Expected slippage for swaps
  • Liquidity Checks: Verifies sufficient liquidity for trades
  • Compliance Status: Confirms all compliance requirements met
  • Error Warnings: Highlights any potential failure points

4. Compliance Status Dashboard Overlay

Layout

┌────────────────────────────────────────────────────────┐
│ Compliance Status                    [Dismiss]          │
├────────────────────────────────────────────────────────┤
│                                                        │
│ Identity Verification:                                 │
│ ✓ LEI: 5493000IBP32UQZ0KL24                            │
│ ✓ DID: did:web:example.com:user:123                    │
│ ✓ KYC: Level 2 Verified (Expires: 2026-12-31)         │
│ ✓ AML: Passed (Last check: 2025-01-15)                 │
│                                                        │
│ Current Workflow Compliance:                           │
│ • All steps require LEI: ✓ Provided                   │
│ • KYC Level Required: 2 ✓ Met                           │
│ • AML Screening: ✓ Passed                              │
│                                                        │
│ Missing Requirements: None                             │
│                                                        │
│ [Update Identity] [View Compliance Details]           │
└────────────────────────────────────────────────────────┘

Features

  • Always Visible Badge: Small indicator in header showing compliance status
  • Detailed View: Expandable overlay with full compliance details
  • Workflow-Specific Checks: Validates compliance for current workflow
  • Expiration Warnings: Alerts if KYC/AML checks are expiring soon
  • Update Actions: Quick links to update identity or run new checks

5. Adapter Selection Modal

Layout

┌────────────────────────────────────────────────────────┐
│ Select Adapter Type                    [X]             │
├────────────────────────────────────────────────────────┤
│                                                        │
│ Filter: [All] [DeFi] [Fiat/DTL] [Whitelisted Only]   │
│                                                        │
│ ┌──────────────────┐  ┌──────────────────┐           │
│ │ DeFi Protocols   │  │ Fiat/DTL Rails   │           │
│ ├──────────────────┤  ├──────────────────┤           │
│ │ 🔄 Uniswap V3    │  │ 📤 ISO-20022 Pay │           │
│ │ 💰 Aave          │  │ 💳 SWIFT MT      │           │
│ │ 📊 Compound      │  │ 🌐 SEPA          │           │
│ │ 🌉 Bridge        │  │ 🏦 FedNow        │           │
│ │                  │  │                  │           │
│ └──────────────────┘  └──────────────────┘           │
│                                                        │
│ Selected: ISO-20022 Pay                               │
│                                                        │
│ [Add to Palette] [Cancel]                            │
└────────────────────────────────────────────────────────┘

Features

  • Category Filtering: Separate DeFi and Fiat/DTL adapters
  • Whitelist Toggle: Show only approved/whitelisted adapters
  • Adapter Status: Visual indicators (✓ Approved, ⚠ Deprecated, 🔒 Restricted)
  • Search: Quick search for specific adapters
  • Version Info: Shows adapter version and last updated date

6. User Flows

Flow 1: Building a Simple Combo (DeFi Only)

  1. User opens Builder page
  2. User drags "Borrow" from DeFi palette → Canvas
  3. Configures borrow step (asset, amount, collateral)
  4. Drags "Swap" from palette → Canvas (after borrow step)
  5. Configures swap step (from/to tokens, amount)
  6. Summary panel updates automatically
  7. User clicks "Review & Sign" (compliance auto-checked)
  8. Redirected to preview/sign page

Flow 2: Building Hybrid Combo (DeFi + Fiat)

  1. User opens Builder page
  2. Compliance badge shows: ✓ LEI, ✓ KYC, ✓ AML
  3. User drags "Borrow" (DeFi) → Canvas
  4. User drags "Swap" (DeFi) → Canvas
  5. User drags "Pay" (Fiat/DTL) → Canvas
  6. Configures pay step (IBAN, amount, beneficiary)
  7. Compliance overlay appears: "Fiat step requires LEI"
  8. LEI auto-populated from user session
  9. User optionally enables simulation toggle
  10. Clicks "Simulate" → sees results
  11. Clicks "Review & Sign" → proceeds

Flow 3: Advanced User with Simulation

  1. User enables "Simulation" toggle in summary panel
  2. Builds workflow as normal
  3. Before signing, clicks "Simulate" button
  4. Simulation results panel shows:
    • Gas estimate
    • Slippage analysis
    • Liquidity checks
    • Failure predictions
  5. User reviews results, adjusts workflow if needed
  6. Clicks "Proceed to Sign" after simulation passes

Flow 4: Compliance Validation Failure

  1. User builds workflow with fiat step requiring LEI
  2. User has not provided LEI in settings
  3. Compliance badge shows: ⚠ LEI Missing
  4. User attempts to sign
  5. Error modal: "LEI required for this workflow. Please update your identity in Settings."
  6. User redirected to Settings page to add LEI
  7. Returns to Builder, workflow auto-validated

7. Responsive Design

Desktop (≥1024px)

  • Full layout with sidebar palette, canvas, and summary panel
  • All features visible simultaneously

Tablet (768px - 1023px)

  • Collapsible sidebar palette
  • Canvas takes full width when palette collapsed
  • Summary panel remains at bottom

Mobile (<768px)

  • Palette accessible via bottom sheet/modal
  • Canvas scrollable vertically
  • Step cards stack vertically
  • Summary panel sticky at bottom

8. Accessibility Requirements

  • Keyboard Navigation: Full keyboard support for drag-and-drop (arrow keys, space/enter)
  • Screen Reader Support: ARIA labels for all interactive elements
  • Color Contrast: WCAG AA compliance for all text and UI elements
  • Focus Indicators: Clear focus states for all interactive elements
  • Error Messages: Clear, actionable error messages for all validation failures

9. Performance Requirements

  • Initial Load: < 2 seconds for Builder page
  • Step Addition: < 500ms for drag-and-drop response
  • Summary Calculation: Real-time updates < 200ms
  • Simulation: < 5 seconds for full workflow simulation
  • Compliance Check: < 1 second for status validation

10. Integration Points

Frontend → Backend API

  • POST /api/plans - Create execution plan
  • GET /api/plans/:id/simulate - Run simulation (optional)
  • GET /api/compliance/status - Fetch compliance status
  • GET /api/adapters - List available adapters (filtered by type/whitelist)

Frontend → Smart Contracts

  • Wallet connection via Wagmi
  • Plan signing via wallet signature
  • Transaction submission via handler contract

11. Visual Design System

Color Palette

  • Primary: Black (#000000) for actions
  • Secondary: Blue (#3B82F6) for compliance/info
  • Success: Green (#10B981) for valid states
  • Warning: Yellow (#F59E0B) for warnings
  • Error: Red (#EF4444) for errors
  • Background: White (#FFFFFF) for cards, Gray-50 (#F9FAFB) for canvas

Typography

  • Headings: Inter, 24px/32px (h1), 18px/24px (h2)
  • Body: Inter, 14px/20px
  • Code/Monospace: Fira Code, 12px/16px for addresses/IDs

Icons

  • Emoji icons for step types (💰, 🔄, 💳, 📤)
  • Lucide React icons for UI elements (Edit, Remove, Drag, etc.)

12. Error States & Edge Cases

Insufficient Balance

  • Red warning badge on step card
  • Error message: "Insufficient balance. You need 100,000 CBDC_USD but have 50,000."

Invalid Workflow

  • Step dependency error: "Step 2 requires output from Step 1. Please reorder steps."
  • Visual connection lines between dependent steps

Compliance Failure

  • Modal overlay: "This workflow requires LEI verification. Please update your identity in Settings."
  • Link to Settings page

Simulation Failure

  • Results panel shows: "⚠ Simulation Failed"
  • Detailed error: "Step 2 (Swap) would fail due to insufficient liquidity."

Network/Chain Mismatch

  • Warning: "Selected adapter (Uniswap) is on Ethereum, but you're connected to Polygon."
  • Option to switch network or select different adapter

13. Future Enhancements (Out of Scope for v2)

  • Workflow Templates: Pre-built combo templates for common strategies
  • Workflow Sharing: Share workflows with other users (with compliance validation)
  • Multi-user Workflows: Collaborative workflow building
  • Advanced Analytics: Historical performance tracking for workflows
  • Mobile App: Native mobile app for workflow building

Acceptance Criteria

  1. ✅ User can drag adapters from palette to canvas
  2. ✅ User can reorder steps by dragging
  3. ✅ User can configure each step via drawer
  4. ✅ Compliance status is always visible and validated
  5. ✅ Optional simulation works for advanced users
  6. ✅ Summary panel updates in real-time
  7. ✅ Hybrid adapters (DeFi + Fiat) are selectable
  8. ✅ Error states are clearly communicated
  9. ✅ Responsive design works on mobile/tablet/desktop
  10. ✅ Accessibility requirements are met

Document Version: 1.0
Last Updated: 2025-01-15
Author: Engineering Team

Reference in New Issue View Git Blame Copy Permalink