post-app-website-new/lib/tbff-flow/README.md

Flow-Based Flow Funding Module

Status: Initial Implementation Complete ✅ Route: /tbff-flow Last Updated: 2025-11-09

---

Overview

This module implements a flow-based visualization of Flow Funding, focusing on resource circulation rather than accumulation. Unlike the stock-based model (/tbff), this visualizes how resources move through networks in real-time.

Core Concepts

Flow vs Stock

Stock Model (/tbff):

• Accounts have balances (accumulated resources)
• Distribution adds to balances
• Thresholds define states (deficit, healthy, overflow)
• Overflow triggers redistribution

Flow Model (/tbff-flow):

• Nodes have flow rates (resources in motion)
• Flow continuously circulates
• Thresholds define absorption capacity
• Real-time animation shows circulation

1. Flow Node

Each node receives flow, absorbs what it needs, and passes excess onward.

Properties:

• minAbsorption: Minimum flow needed to function (survival level)
• maxAbsorption: Maximum flow that can be absorbed (capacity)
• externalFlow: Flow injected by user (source)
• inflow: Total flow entering (external + from allocations)
• absorbed: Amount kept (between min and max)
• outflow: Excess flow leaving (to allocations)

Status:

• 🔴 Starved: absorbed < minAbsorption
• 🟡 Minimum: absorbed ≈ minAbsorption
• 🔵 Healthy: minAbsorption < absorbed < maxAbsorption
• 🟢 Saturated: absorbed ≥ maxAbsorption

2. Flow Propagation

Algorithm:

1. Start with external flows (user-set inputs)
2. For each iteration:
   • Calculate absorption: min(inflow, maxAbsorption)
   • Calculate outflow: max(0, inflow - absorbed)
   • Distribute outflow via allocations
   • Update inflows for next iteration
3. Repeat until convergence (flows stabilize)
4. Create overflow sink if needed

Convergence: Flows change by less than 0.01 between iterations

3. Overflow Sink

Auto-created when network has unallocated outflow.

Purpose: Capture excess flow that has nowhere to go

Behavior:

• Appears automatically when needed
• Disappears when no longer needed
• Infinite absorption capacity
• Visualized with "SINK" label

4. Flow Particles

Animation: Particles move along allocation arrows

Properties:

• Position along arrow (0.0 to 1.0)
• Amount (affects size and color)
• Speed (faster for higher flow)
• Continuous loop (resets at end)

Purpose: Visual feedback of resource circulation

---

Module Structure

lib/tbff-flow/
├── types.ts              # Flow-based types (FlowNode, FlowNetwork, etc.)
├── utils.ts              # Utility functions (absorption, status, etc.)
├── algorithms.ts         # Flow propagation algorithm
├── rendering.ts          # Canvas rendering with particles
├── sample-networks.ts    # Demo networks (linear, split, circular)
└── README.md            # This file

app/tbff-flow/
└── page.tsx             # Main page with real-time animation

---

Features

✅ Implemented

1. Flow Propagation Algorithm

   • Iterative flow distribution
   • Convergence detection
   • Comprehensive console logging
   • Automatic overflow node creation

2. Real-Time Animation

   • Continuous particle movement
   • Pause/play with spacebar
   • Smooth 60fps rendering
   • Visual flow indicators

3. Interactive Controls

   • Click node to set external flow
   • Create allocations with arrow tool
   • Edit allocation percentages
   • Delete allocations

4. Sample Networks

   • Linear Flow (A → B → C)
   • Split Flow (Projects + Commons)
   • Circular Flow (A ↔ B ↔ C)
   • Empty Network (build your own)

5. Visual Design

   • Flow bars show inflow/absorption/outflow
   • Status colors (red/yellow/blue/green)
   • Arrow thickness = flow amount
   • Particle density = flow volume
   • External flow indicators (green dots)

---

Usage

Setting Flow

1. Select a node (click on it)
2. Enter external flow value in sidebar
3. Watch flow propagate automatically
4. See particles animate along arrows

Creating Allocations

1. Click "Create Arrow" tool
2. Click source node
3. Click target node
4. Allocation created with 50% default
5. Flow re-propagates automatically

Observing Flow

• Inflow bars (blue): Total flow entering
• Absorption bars (status color): Amount kept
• Outflow bars (green): Excess leaving
• Particles: Moving resources
• Arrow thickness: Flow amount

Keyboard Shortcuts

• Space: Pause/play animation
• Escape: Cancel creation, deselect
• Delete: Remove selected allocation

---

Sample Networks

1. Linear Flow

Structure: A → B → C

Setup: Alice receives 100 flow, passes excess to Bob, who passes to Carol

Demonstrates: Sequential absorption and propagation

2. Split Flow

Structure: Source → Projects (A, B) → Commons

Setup: Source splits 60/40 between projects, which merge at Commons

Demonstrates: Branching and merging flows

3. Circular Flow

Structure: A → B → C → A

Setup: Alice injects 50 flow, which circulates continuously

Demonstrates: Circular resource circulation

4. Empty Network

Structure: 3 unconnected nodes

Purpose: Build custom flow patterns from scratch

---

Algorithm Details

Flow Propagation Example

Initial State:
  Alice: externalFlow = 100, maxAbsorption = 50
  Bob: externalFlow = 0, maxAbsorption = 30
  Alice → Bob (100%)

Iteration 1:
  Alice: inflow = 100, absorbed = 50, outflow = 50
  Bob: inflow = 0 (not yet received)

Iteration 2:
  Alice: inflow = 100, absorbed = 50, outflow = 50
  Bob: inflow = 50, absorbed = 30, outflow = 20

Iteration 3 onwards:
  (Converged - no change)

Result:
  Alice absorbs 50, passes 50 to Bob
  Bob absorbs 30, has 20 outflow (needs overflow node)

Convergence

Condition: max(|inflow[i] - inflow[i-1]|) < 0.01 for all nodes

Max Iterations: 100

Typical: Converges in 10-20 iterations for most networks

---

Technical Implementation

State Management

const [network, setNetwork] = useState<FlowNetwork>(...)
const [particles, setParticles] = useState<FlowParticle[]>([])
const [isAnimating, setIsAnimating] = useState(true)

Animation Loop

useEffect(() => {
  const animate = () => {
    setParticles(prev => updateFlowParticles(prev))
    requestAnimationFrame(animate)
  }
  requestAnimationFrame(animate)
}, [isAnimating])

Canvas Rendering

useEffect(() => {
  renderFlowNetwork(ctx, network, width, height, particles, ...)
}, [network, particles, selectedNodeId, selectedAllocationId])

Flow Propagation Trigger

• On network load
• On external flow change
• On allocation create/update/delete
• Automatic 100ms after change

---

Design Decisions

1. Why Separate from Stock Model?

Decision: Create /tbff-flow as separate route

Reasoning:

• Different mental models (flow vs stock)
• Different visualizations (particles vs bars)
• Different algorithms (propagation vs distribution)
• Users can compare both approaches

2. Why Real-Time Continuous Animation?

Decision: Particles move continuously at 60fps

Reasoning:

• Emphasizes circulation over states
• More engaging and dynamic
• Matches "flow" concept intuitively
• Educational - see resources in motion

Trade-off: More CPU usage vs better UX

3. Why Auto-Create Overflow Node?

Decision: Automatically create/remove overflow sink

Reasoning:

• Unallocated outflow needs destination
• Prevents "leaking" flow
• Conserves resources (total inflow = absorbed + overflow)
• User shouldn't have to manually manage

4. Why Absorption Thresholds?

Decision: Min/max thresholds define absorption capacity

Reasoning:

• Maps to real resource needs (minimum to function, maximum to benefit)
• Similar to stock model (easy to understand)
• Allows partial absorption (not all-or-nothing)
• Generates meaningful outflow for circulation

---

Comparison with Stock Model

Aspect	Stock Model (/tbff)	Flow Model (/tbff-flow)
Core Metric	Balance (accumulated)	Flow rate (per time)
Visualization	Fill height	Flow bars + particles
Input	Add funding (one-time)	Set flow (continuous)
Algorithm	Initial distribution	Flow propagation
Animation	Static (for now)	Real-time particles
Overflow	Triggers redistribution	Continuous outflow
Use Case	Budget allocation	Resource circulation

---

Future Enhancements

Phase 2

• Variable particle colors (by source)
• Flow rate history graphs
• Equilibrium detection indicator
• Save/load custom networks
• Export flow data (CSV, JSON)

Phase 3

• Multiple simultaneous external flows
• Time-varying flows (pulses, waves)
• Flow constraints (min/max on arrows)
• Network analysis (bottlenecks, unutilized capacity)

Phase 4

• Combine stock and flow models
• Hybrid visualization
• Round-based simulation mode
• Multi-network comparison

---

Resources

• Stock Model: /lib/tbff/README.md
• Design Session: /.claude/journal/FLOW_FUNDING_DESIGN_SESSION.md
• Academic Paper: ../../../threshold-based-flow-funding.md

---

Testing Checklist

• Load default network (Linear Flow)
• Switch between sample networks
• Set external flow on node
• Watch flow propagate
• See particles animate
• Create allocation with arrow tool
• Edit allocation percentage
• Delete allocation
• Pause/play animation with Space
• See overflow node appear when needed
• See overflow node disappear when not needed
• Check console for propagation logs
• Verify convergence
• Test circular flow network

---

Built with: TypeScript, React, Next.js, Canvas API, requestAnimationFrame

Module Owner: TBFF Flow Team

Philosophy: "Resources are meant to circulate, not accumulate."

---

Flow where needed, absorb what's needed, pass on the rest.