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

Threshold-Based Flow Funding (TBFF) Module

Status: Milestone 3 Complete ✅ Route: /tbff Last Updated: 2025-11-09

---

Overview

This module implements the Threshold-Based Flow Funding mechanism described in threshold-based-flow-funding.md. It's built as a self-contained, modular system that can evolve independently without affecting other parts of the application.

Module Structure

lib/tbff/
├── types.ts                # TypeScript interfaces and types
├── utils.ts                # Utility functions (status calculations, formatting)
├── sample-networks.ts      # Pre-configured demo networks
├── rendering.ts            # Canvas rendering functions
├── algorithms.ts           # Flow funding algorithms (future)
└── README.md              # This file

app/tbff/
└── page.tsx               # Main page component

Core Concepts

1. Account (Participant)

Each account has:

• Balance: Current funds held
• Min Threshold: Minimum viable funding (survival level)
• Max Threshold: Overflow point (abundance level)
• Status: Derived state (deficit, minimum, healthy, overflow)

Visual Representation: Rectangle with fill height showing balance vs thresholds.

Color Coding:

• 🔴 Red (Deficit): balance < minThreshold
• 🟡 Yellow (Minimum): balance ≈ minThreshold
• 🔵 Blue (Healthy): minThreshold < balance < maxThreshold
• 🟢 Green (Overflow): balance ≥ maxThreshold

2. Allocation (Connection)

Represents where overflow flows when an account exceeds its maximum threshold.

Properties:

• sourceAccountId: Account that overflows
• targetAccountId: Account that receives overflow
• percentage: Portion of overflow to send (0.0 to 1.0)

Visual Representation: Arrow with thickness based on percentage.

3. Network

Collection of accounts and their allocations, forming a resource flow network.

Computed Properties:

• Total Funds: Sum of all balances
• Total Shortfall: Sum of all deficits
• Total Capacity: Sum of all remaining capacity
• Total Overflow: Sum of all overflows

Current Implementation (Milestone 1-3)

✅ What's Working

1. Static Visualization

   • Accounts rendered as colored rectangles
   • Fill height shows balance vs max threshold
   • Threshold lines (dashed) show min/max
   • Status badges show current state
   • Center dots show connection points

2. Allocations

   • Arrows between accounts
   • Thickness based on allocation percentage
   • Color indicates if source has overflow
   • Percentage labels at midpoint

3. Interactive Selection

   • Click accounts to select
   • Click arrows to select allocations
   • Sidebar shows detailed info
   • Account list for quick navigation
   • Keyboard shortcuts (Delete, Escape)

4. Interactive Allocation Creation ✨ New in M2

   • Two-tool system (Select, Create Arrow)
   • Click source, then target to create allocation
   • Default 50% percentage
   • Auto-normalization with existing allocations
   • Visual feedback during creation

5. Allocation Editing ✨ New in M2

   • Select arrow to edit
   • Percentage slider (0-100%)
   • Real-time updates
   • Auto-normalization
   • Delete button
   • Delete key shortcut

6. Sample Networks

   • States Demo: Shows all 4 account states
   • Simple Linear: A → B → C flow
   • Mutual Aid Circle: A ↔ B ↔ C circular support
   • Commons Pool: Everyone → Pool → Everyone

7. Initial Distribution Algorithm ✨ New in M3

   • Add external funding input field
   • "Distribute Funding" button
   • Algorithm fills minimums first, then distributes by capacity
   • Distribution summary shows changes
   • Console logging for debugging
   • Real-time balance updates

8. Network Stats

   • Real-time totals displayed in corner
   • Sidebar shows aggregated metrics

📋 What's Not Yet Implemented

• ❌ Overflow redistribution algorithm
• ❌ Animated flow particles
• ❌ Adding/editing accounts
• ❌ Editing account balances/thresholds
• ❌ Multi-round simulation with overflow
• ❌ Persistence (save/load)

Sample Networks

1. States Demo (Default)

Four accounts showing all possible states:

• Deficit (balance: 30, min: 100, max: 200)
• Minimum (balance: 100, min: 100, max: 200)
• Healthy (balance: 150, min: 100, max: 200)
• Overflow (balance: 250, min: 100, max: 200)

Purpose: Understand visual language and status colors.

2. Simple Linear Flow

Three accounts in a chain: Alice → Bob → Carol

Purpose: Demonstrates basic flow through a linear network.

3. Mutual Aid Circle

Three accounts in circular support: Alice ↔ Bob ↔ Carol ↔ Alice

Purpose: Shows how resources can circulate through mutual aid relationships.

4. Commons Pool

Four accounts where everyone contributes to a central pool, which redistributes equally.

Purpose: Demonstrates hub-and-spoke pattern with commons-based allocation.

API Reference

Types (types.ts)

interface FlowFundingAccount {
  id: string
  name: string
  balance: number
  minThreshold: number
  maxThreshold: number
  x: number
  y: number
  width: number
  height: number
  status: AccountStatus
  shortfall: number
  capacity: number
  overflow: number
}

interface Allocation {
  id: string
  sourceAccountId: string
  targetAccountId: string
  percentage: number
}

interface FlowFundingNetwork {
  name: string
  accounts: FlowFundingAccount[]
  allocations: Allocation[]
  totalFunds: number
  totalShortfall: number
  totalCapacity: number
  totalOverflow: number
}

Utils (utils.ts)

// Status calculation
getAccountStatus(account: FlowFundingAccount): AccountStatus
updateAccountComputedProperties(account: FlowFundingAccount): FlowFundingAccount

// Network calculations
calculateNetworkTotals(network: FlowFundingNetwork): FlowFundingNetwork

// Allocation helpers
normalizeAllocations(allocations: Allocation[]): Allocation[]

// Visual helpers
getAccountCenter(account: FlowFundingAccount): { x: number; y: number }
getStatusColor(status: AccountStatus, alpha?: number): string

Rendering (rendering.ts)

// Render individual elements
renderAccount(ctx: CanvasRenderingContext2D, account: FlowFundingAccount, isSelected?: boolean): void
renderAllocation(ctx: CanvasRenderingContext2D, allocation: Allocation, source: FlowFundingAccount, target: FlowFundingAccount, isSelected?: boolean): void

// Render entire network
renderNetwork(ctx: CanvasRenderingContext2D, network: FlowFundingNetwork, width: number, height: number, selectedAccountId?: string | null): void

Next Steps (Milestone 2+)

✅ Milestone 2: Add Allocations (Interactive) - COMPLETE

Goal: Draw arrows between accounts, edit percentages

Tasks:

• Arrow drawing tool (click source, click target)
• Allocation percentage editor in sidebar
• Delete allocations
• Normalize allocations automatically

✅ Milestone 3: Initial Distribution - COMPLETE

Goal: Add external funding and watch it distribute

Tasks:

• Implement initialDistribution() algorithm
• Add "Add Funding" input + button
• Distribution summary display
• Console logging for debugging
• Animate balance changes (number tweening) - Future enhancement

Milestone 4: Overflow Redistribution

Goal: Trigger overflow and watch funds flow

Tasks:

• Implement redistributeOverflow() algorithm
• Create FlowParticle animation system
• Animate particles along arrows
• Show iteration count and convergence
• "Run Redistribution" button

Milestone 5: Interactive Creation

Goal: Build custom networks from scratch

Tasks:

• "Create Account" tool with threshold inputs
• Drag accounts to reposition
• Edit account thresholds
• Edit account balances
• Save/load network (localStorage)

Milestone 6: Scenarios & Presets

Goal: Curated examples with explanations

Tasks:

• More complex preset networks
• Guided tour / tooltips
• Scenario descriptions
• Expected outcomes documentation

Milestone 7: Polish

Goal: Production-ready demo

Tasks:

• Keyboard shortcuts (Delete, Esc, etc.)
• Undo/redo for edits
• Mobile responsive sidebar
• Performance optimization
• Error handling
• Demo video recording

Integration Points

With Existing Canvas (/italism)

This module is completely separate from the existing /italism canvas. No shared code, no dependencies.

Future: Could potentially merge propagator concepts, but for now they remain independent.

With Academic Paper

This implementation directly models the concepts from threshold-based-flow-funding.md:

• Section 2.1: Mathematical Model → types.ts interfaces
• Section 2.2: Distribution Algorithm → algorithms.ts (future)
• Section 3: Theoretical Properties → Will validate through tests

With Post-Appitalism Vision

This embodies Post-Appitalism by:

• Making abstract economics tangible (visual, interactive)
• Demonstrating resource circulation vs extraction
• Showing collective intelligence (allocation networks)
• Creating malleable systems (users can experiment)

Development Notes

Design Decisions

1. Separate Module: Keeps TBFF isolated, prevents breaking existing features
2. Canvas-based: Performance for many accounts, smooth animations
3. Computed Properties: Derived from balance/thresholds, not stored separately
4. Sample Data: Hardcoded networks for quick demos, easier testing

Known Limitations

1. No persistence: Refresh loses changes (Milestone 5)
2. Static only: No algorithm execution yet (Milestone 3-4)
3. No validation: Can't detect invalid networks yet
4. No tests: Should add unit tests for algorithms

Performance Considerations

• Canvas redraws entire scene on change (acceptable for <50 accounts)
• Could optimize with dirty rectangles if needed
• Animations will use requestAnimationFrame

Testing

Manual Testing Checklist

Milestone 1:

• Load default network (States Demo)
• Switch between networks via dropdown
• Click accounts to select
• View account details in sidebar
• See color coding for different states
• See threshold lines in accounts
• See allocation arrows with percentages
• See network stats update

Milestone 2:

• Select "Create Arrow" tool
• Click source account, then target account
• New allocation appears on canvas
• Click arrow to select it
• Selected arrow highlights in cyan
• Allocation editor appears in sidebar
• Drag percentage slider
• See percentage update in real-time
• Create second allocation from same source
• See both allocations normalize
• Click "Delete Allocation" button
• Press Delete key to remove allocation
• Press Escape to deselect
• See outgoing allocations in account details

Milestone 3:

• See "Add Funding" section in sidebar
• Enter funding amount (default: 1000)
• Click "Distribute Funding" button
• See balances update immediately
• See distribution summary appear
• See list of changed accounts with deltas
• Check console for detailed logs
• Try insufficient funding (distributes proportionally)
• Try sufficient funding (fills minimums, then by capacity)
• See network totals update correctly

Future:

• Watch overflow redistribution (Milestone 4)
• See animated flow particles (Milestone 4)

Future: Automated Tests

// Example tests for Milestone 3+
describe('initialDistribution', () => {
  it('should fill minimums first when funds insufficient', () => {})
  it('should distribute by capacity when minimums met', () => {})
})

describe('redistributeOverflow', () => {
  it('should converge within max iterations', () => {})
  it('should conserve total funds', () => {})
})

Resources

• Academic Paper: ../../../threshold-based-flow-funding.md
• Design Session: ../../.claude/journal/FLOW_FUNDING_DESIGN_SESSION.md
• Project Vision: ../../.claude/journal/POST_APPITALISM_VISION.md

---

Built with: TypeScript, React, Next.js, Canvas API Module Owner: TBFF Team Questions? See design session document for detailed architecture.