flow-funding/DESIGN.md

13 KiB
Raw Blame History

Flow Funding Visual Interface Design

Core Concept: Threshold-Based Flow Funding (TBFF)

Unlike traditional discrete grants, TBFF enables continuous resource flows that respond dynamically to conditions. Funds stream like water through a network, with thresholds acting as gates that open, close, or modulate flow rates.


Visual Metaphors

1. The River System

  • Sources = Springs/tributaries (funding origins)
  • Flows = Rivers/streams (animated fund movement)
  • Recipients = Lakes/deltas (fund destinations)
  • Thresholds = Dams/locks (control points)

2. The Circulatory System

  • Sources = Heart (pumping resources)
  • Flows = Arteries/veins (distribution network)
  • Recipients = Organs (entities needing resources)
  • Thresholds = Valves (flow regulation)

3. The Electrical Grid

  • Sources = Power plants (generation)
  • Flows = Transmission lines (distribution)
  • Recipients = Consumers (utilization)
  • Thresholds = Circuit breakers (protection/regulation)

Key Visual Elements

Flow Nodes

┌─────────────────────────────────────────────────────────┐
│                      SOURCE NODE                        │
│  ┌─────────────────────────────────────────────────┐   │
│  │  ╭──────────────╮                               │   │
│  │  │   Treasury   │  Balance: $50,000             │   │
│  │  │      💰      │  Flow Rate: $100/hr           │   │
│  │  ╰──────┬───────╯  Status: ● Active             │   │
│  │         │                                       │   │
│  │    ═════╧═════▶  (animated particles)           │   │
│  └─────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────┐
│                    RECIPIENT NODE                       │
│  ┌─────────────────────────────────────────────────┐   │
│  │    ═════╤═════▶  (incoming flow)                │   │
│  │         │                                       │   │
│  │  ╭──────┴───────╮                               │   │
│  │  │   Project    │  Received: $12,340            │   │
│  │  │      🎯      │  Rate: $85/hr                 │   │
│  │  ╰──────────────╯  Health: ████████░░ 80%       │   │
│  └─────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘

Threshold Visualization

THRESHOLD STATES:

  Below Threshold        At Threshold          Above Threshold
  (Flow Blocked)         (Flow Starting)       (Full Flow)

       ╱╲                     ╱╲                    ╱╲
       ⛔ ╲                  ⚠️ ╲                 ✅ ╲
    ╱──────╲               ╱──────╲              ╱──────╲
    │░░░░░░│               │▓▓▓░░░│              │██████│
    │░░░░░░│               │▓▓▓░░░│              │██████│
    └──────┘               └──────┘              └──────┘
    $2,000                  $4,500                $8,000
    ───────                 ───────               ───────
    Threshold: $5,000       Threshold: $5,000     Threshold: $5,000

Flow Animation Styles

1. PARTICLE FLOW (recommended)
   ○───○───○───○───○───▶
   Dots flowing along the path, speed indicates rate

2. GRADIENT PULSE
   ████▓▓▒▒░░░░░░░░░░░▶
   Color gradient pulses along the line

3. DASHED ANIMATION
   ─ ─ ─ ─ ─ ─ ─ ─ ─ ─▶
   Animated dashes moving toward recipient

4. THICKNESS ENCODING
   ═══════════════════▶  High flow
   ────────────────────▶  Medium flow
   ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌▶  Low flow

Interactive Features

1. Threshold Slider

Users can drag thresholds to see how changes affect flow dynamics:

┌────────────────────────────────────────────────────────┐
│  THRESHOLD CONTROL                                     │
│                                                        │
│  Min ├────────────●────────────────────────────┤ Max  │
│      $0          $5,000                      $50,000   │
│                    ▲                                   │
│                    │                                   │
│              Current: $5,000                           │
│                                                        │
│  Flow activates when source balance > threshold        │
└────────────────────────────────────────────────────────┘

2. Flow Rate Dial

Adjust how fast funds flow when threshold is met:

        ╭─────────────╮
              │       ╲
      │    ────●────    │
      │            ╲   │
       ╲      │     ╲ 
        ╰──────┴──────╯
          $10    $100    $1000
               /hr

     Current Rate: $50/hr

3. Time Simulation

Scrub through time to see how flows evolve:

┌─────────────────────────────────────────────────────────┐
│  ◀◀  ◀  ▶  ▶▶   │▒▒▒▒▒▒▒▒▒▒▒░░░░░░░░░░░░░░░░░░│        │
│                  ▲                                      │
│               NOW                                       │
│                                                         │
│  Jan 2025 ─────────────────────────────────── Dec 2025 │
└─────────────────────────────────────────────────────────┘

Screen Layouts

Main Canvas View

┌──────────────────────────────────────────────────────────────────┐
│  FLOW FUNDING                                    [+] [⚙] [?]     │
├──────────────────────────────────────────────────────────────────┤
│                                                                  │
│     ╭─────────╮                          ╭─────────╮             │
│     │ Treasury│                          │Project A│             │
│     │  $50K   │══════════════════════════│  $12K   │             │
│     ╰────┬────╯                         ╰─────────╯             │
│          │                                                      │
│          │     ┌──────┐                                          │
│          ├═════│ GATE │═══════╗          ╭─────────╮             │
│          │     │$5K TH│       ║          │Project B│             │
│          │     └──────┘       ╚══════════│  $8K    │             │
│          │                               ╰─────────╯             │
│          │                                                       │
│          │                               ╭─────────╮             │
│          ╰═══════════════════════════════│Project C│             │
│                                          │  $5K    │             │
│                                          ╰─────────╯             │
│                                                                  │
├──────────────────────────────────────────────────────────────────┤
│  Total Flowing: $300/hr │ Active Flows: 3 │ Blocked: 1          │
└──────────────────────────────────────────────────────────────────┘

Detail Panel (on node click)

┌─────────────────────────────────────┐
│  PROJECT A                     [×]  │
├─────────────────────────────────────┤
│                                     │
│  Current Balance    $12,340.50      │
│  Incoming Rate      $85.00/hr       │
│  ────────────────────────────────   │
│                                     │
│  THRESHOLD STATUS                   │
│  ████████████████░░░░  80%          │
│  $12,340 / $15,000 threshold        │
│                                     │
│  When threshold met:                │
│  → Unlock outgoing flow to Proj D   │
│  → Increase rate to $150/hr         │
│                                     │
│  ────────────────────────────────   │
│  FLOW HISTORY                       │
│  ┌─────────────────────────────┐   │
│  │    ╱╲    ╱╲                 │   │
│  │     ╲    ╱╲          │   │
│  │      ╲╱    ╲    ╲         │   │
│  │             ╲╱    ╲        │   │
│  └─────────────────────────────┘   │
│   Jan  Feb  Mar  Apr  May  Jun     │
│                                     │
└─────────────────────────────────────┘

Color System

State Color Hex Usage
Active Flow Electric Blue #3B82F6 Flowing connections
Threshold Met Emerald #10B981 Success states
Near Threshold Amber #F59E0B Warning/attention
Below Threshold Rose #F43F5E Blocked/inactive
Pending Purple #8B5CF6 Processing states
Background Slate #0F172A Canvas background

Interaction Patterns

Creating a New Flow

  1. Click source node → drag to recipient
  2. Release to open threshold configuration
  3. Set threshold amount and flow rate
  4. Flow appears with animation

Adjusting Threshold

  1. Click on threshold gate icon
  2. Drag slider or enter exact value
  3. See real-time preview of flow state change
  4. Changes apply immediately or on confirm

Time Travel

  1. Pause current state
  2. Drag timeline scrubber
  3. See historical or projected flow states
  4. Resume real-time or stay at selected time

Technical Implementation

React Flow Integration

  • Custom node types: SourceNode, RecipientNode, ThresholdGate
  • Custom edge type: AnimatedFlowEdge with particle animation
  • Minimap for large networks
  • Pan/zoom controls

Animation System

  • Canvas-based particle system for flow animation
  • 60fps smooth animations
  • Performance-optimized for 100+ nodes

State Management

  • Real-time flow calculations
  • Threshold state machine
  • Time-series data for history/projections