# rFunds — Funding Flows & Treasury

**Module ID:** `rfunds`
**Domain:** `rfunds.online`
**Version:** 0.1.0
**Framework:** Next.js 14 / React 18 / React Flow / Zustand (client-side only)
**Status:** Active

## Purpose

Visual funding flow designer using threshold-based conviction funding. Users create directed graphs of funnel nodes (with min/max thresholds) feeding into outcome nodes. Integrates with rVote for governance-linked funding and Gnosis Safe for on-chain treasury management. Currently client-side only with URL-based sharing.

## Data Model

### Client-Side Types (no database)

| Type | Key Fields | Description |
|------|-----------|-------------|
| **FunnelNodeData** | minThreshold, maxThreshold, inflowRate, overflowAllocations, spendingAllocations | Funding funnel with configurable thresholds |
| **OutcomeNodeData** | fundingReceived, fundingTarget | Target outcome that receives funds |
| **FlowNode** | id, type (funnel/outcome), position, data | React Flow graph node |
| **AllocationEdgeData** | percentage, type (overflow/spending) | Edge connecting funnels to outcomes |
| **IntegrationSource** | rvoteSpace, safeAddress | Links to rVote proposals or Safe treasury |
| **FundingSource** | type (fiat/crypto/safe/bank), config | Payment source configuration |

### Storage

- **Local:** `rfunds-space-<name>` in localStorage
- **Sharing:** LZ-compressed state encoded in URL
- **No server persistence** — future: Automerge CRDT + space-scoped storage

## Permission Model

### Space Integration

- **SpaceVisibility:** PUBLIC by default (anyone can view flow diagrams)
- **Default role for open spaces:** PARTICIPANT (can create/edit flows)

### Capabilities

| Capability | Required SpaceRole | AuthLevel | Description |
|-----------|-------------------|-----------|-------------|
| `view_flows` | VIEWER | BASIC | See funding flow diagrams |
| `create_flow` | PARTICIPANT | STANDARD | Create new funding flows |
| `contribute_funds` | PARTICIPANT | STANDARD | Allocate funds to flows |
| `moderate_flows` | MODERATOR | STANDARD | Edit/archive others' flows |
| `configure_treasury` | ADMIN | ELEVATED | Manage Safe integration, treasury settings |

### Current Auth Implementation

- EncryptID optional (anonymous creation allowed)
- Auth state in Zustand + localStorage (`rfunds-auth`)
- No server-side permission checks

## API Endpoints

| Method | Path | Auth Required | Capability | Description |
|--------|------|---------------|------------|-------------|
| GET | /api/proxy/rvote | No | view_flows | Proxy to rvote.online for space/proposal data |

No native CRUD API — all state is client-side.

## Canvas Integration

Embeds as shapes on rSpace canvas:
- **`folk-budget`**: Budget tracker summary
- **`demo-expense`**: Individual expense with split tracking
- Click to expand into full React Flow diagram

## Cross-Module Dependencies

| Module | Integration |
|--------|------------|
| **rVote** | Governance-linked funding (proposals trigger flows) |
| **rWallet** | Gnosis Safe treasury management |
| **rSpace** | Canvas shape embedding |

## Local-First / Offline Support

- Fully client-side already — works offline by default
- URL sharing for collaboration (no real-time sync)
- Future: Automerge CRDT for real-time collaborative flow editing

## Migration Plan

1. Add server-side persistence (Prisma or Automerge) for spaces
2. Add EncryptID auth middleware to new API routes
3. Import `RFUNDS_PERMISSIONS` from SDK
4. Add `hasCapability()` checks when server API routes are added
5. Add space membership for MEMBERS_ONLY treasury spaces