PiePay Frontend

A web3 application for decentralized profit sharing and unit management with a hierarchical token system.

Overview

PiePay is a lightweight, focused web3 application that enables projects to manage contributors and distribute rewards through a sophisticated unit-based system. It implements a decentralized autonomous organization (DAO) structure with configurable profit-sharing mechanisms.

Architecture

Core Technology Stack

• Frontend Framework: React 19 with TypeScript
• Build Tool: Vite
• Web3 Integration: Wagmi v2 + Viem for blockchain interaction
• Wallet Connection: RainbowKit for wallet connectivity
• UI Framework: Mantine v8 (components, forms, notifications)
• State Management: TanStack React Query for server state
• Styling: Mantine's CSS-in-JS with dark theme

Key Modules & Relationships

1. Application Core

Entry Points

• main.tsx - Application bootstrap and rendering
• App.tsx - Root component with provider setup
  • WagmiProvider (blockchain connection)
  • QueryClientProvider (data fetching)
  • RainbowKitProvider (wallet UI)
  • MantineProvider (UI theming)

Configuration

• config.ts - Blockchain and contract configuration
  • Supported chains: Sepolia (testnet), Localhost, Mainnet
  • Contract addresses: PiePay, MockUSDC
  • Chain selection helpers
• vite.config.ts - Development server configuration

2. Contract Integration Layer

Central Hook

• hooks/usePiePayContract.ts - Central hub for all contract interactions
  • Unified interface for read/write operations
  • Defines unit types: Profit (0), Debt (1), Capital (2)
  • Defines contribution states: None (0), Pending (1), Approved (2), Rejected (3)
  • Connects to all components requiring contract data

Contract Interface

• abi/PiePay.json - Contract interface definition
  • Type-safe contract calls
  • Comprehensive event definitions

3. UI Components

Main Container

• PiePayDashboard.tsx - Application shell with wallet connection & navigation
  • Currently active tabs: "Contract Info" and "Admin"
  • Inactive tabs ready for activation: Contributors, Contributions, Units, Payroll

Active Components

• SimpleContractInfo.tsx - Primary active component

  • Displays contract state, roles, balances
  • Shows: project lead, payroll manager, token info, conversion multipliers
  • Uses: usePiePayContract hook

• AdminPanel.tsx - Administrative functions

  • Role management (project lead, payroll manager)
  • Conversion multiplier configuration
  • Unit capacity settings
  • Access control: Role-based permissions

Ready-to-Activate Components

• ContributorManagement.tsx - Whitelist management
• ContributionWorkflow.tsx - Submit/review contributions
• UnitManagement.tsx - Unit balances and conversions
• PayrollManagement.tsx - Funding and distributions

4. Data Flow Architecture

User Action → Component → usePiePayContract Hook → Blockchain
                ↓
     UI Updates ← React Query Cache ← Contract Events

Key Patterns

• Read Operations: React Query + Wagmi for caching and synchronization
• Write Operations: Transaction submission with status tracking
• State Synchronization: Automatic re-fetching on transaction confirmation

Features

• Contract Information: View contract details, roles, and current state
• Contributor Management: Whitelist/remove contributors (Project Lead only)
• Contribution Workflow: Submit and review contributions
• Unit Management: View and convert between P-Units, D-Units, and C-Units
• Payroll Management: Fund payroll and execute payouts (Payroll Manager only)
• Admin Panel: Manage contract settings and roles

Business Logic - Unit System

Hierarchical Unit Types

1. P-Units (Profit) - Entry level, earned through contributions
2. D-Units (Debt) - Middle tier, convertible from P-Units
3. C-Units (Capital) - Highest tier, permanent ownership rights

Conversion Rules

• P→D Multiplier: 1.5x (basis points: 15000)
• P→C Multiplier: 0.3x (basis points: 3000)
• D→C Multiplier: 0.2x (basis points: 2000)

Payout Behaviors

• P-Units & D-Units: Buyback behavior (units consumed on payout)
• C-Units: Dividend behavior (units persist through payouts)

Security & Access Control

Role-Based Access

• Project Lead: Full administrative control, contribution approval
• Payroll Manager: Payroll funding and distribution
• Whitelisted Contributors: Contribution submission and unit conversion
• Public: Read-only access to contract information

Input Validation

• Address Validation: Ethereum address format checking
• Numeric Validation: Positive values, range checking
• Transaction Validation: Role verification before execution

Development Setup

Prerequisites

• Node.js 18+
• npm or yarn
• Local blockchain (Anvil/Hardhat)

Installation

🚀 PiePay Full Stack Startup Guide

Prerequisites:

• ✅ Docker Desktop (for the indexer database)
• ✅ Node.js/npm (for frontend)
• ✅ pnpm (for indexer)

---

1. Start Docker Desktop

Make sure Docker Desktop is running on your Mac.

---

2. Start the Indexer (First!)

cd /piepay/piepay-indexer pnpm dev What this does:

• Starts PostgreSQL + Hasura GraphQL on http://localhost:8080
• Begins indexing events from Arbitrum Sepolia
• Provides GraphQL API for the frontend

Wait for: "✅ All chains are up to date" or similar success message

---

3. Start the Frontend

cd /piepay/piepay-frontend npm run dev What this does:

• Starts React app on http://localhost:5173
• Connects to your wallet (MetaMask)
• Connects to the indexer at localhost:8080

---

4. Optional: Backend/Other Services

If you have other services

cd /piepay/piepay-backend npm run dev # (if needed)

---

🔗 URLs You'll Access:

Service	URL	Purpose
Frontend	http://localhost:5173	Main PiePay UI
Indexer GraphQL	http://localhost:8080	GraphQL Playground
Indexer DB	localhost:5433	PostgreSQL (internal)

---

📱 Quick Test Flow:

1. Open Frontend: http://localhost:5173
2. Connect Wallet: Make sure you're on Arbitrum Sepolia
3. Check "Submit P Unit" tab: Should show the contribution form
4. Submit a contribution: Watch it go through the pipeline
5. Check "Contributions" tab: Should show your submission updating in real-time

---

🛠 Troubleshooting:

Indexer won't start:

• Check Docker Desktop is running
• Run docker system prune if needed
• Try pnpm install in the indexer directory

Frontend can't connect:

• Make sure indexer is running on port 8080
• Check browser console for errors
• Verify wallet is on Arbitrum Sepolia network

Transactions failing:

• Make sure you have ETH on Arbitrum Sepolia
• Check if you're whitelisted (you should be as project lead)

---

⚡ Development Workflow:

1. Start indexer first (needs to be running for frontend)
2. Start frontend second (connects to indexer)
3. Make changes and hot-reload works for both
4. Check GraphQL playground at localhost:8080 for data

---

Want me to create a startup script to automate this? I can make a simple shell script that starts everything in the right order with proper wait times.

Development

npm run dev

Build

npm run build

Linting

npm run lint

Local Development

Contract Deployment

1. Deploy contracts using the PiePay contracts repository
2. Update contract addresses in src/config.ts
3. Ensure ABI is current in src/abi/PiePay.json

Wallet Setup

1. Add localhost network to MetaMask:

   • Network name: Localhost 8545
   • RPC URL: http://localhost:8545
   • Chain ID: 31337
   • Currency symbol: ETH

2. Import test account private key for testing

Testing

The application includes comprehensive contract interaction testing through the UI. All contract functions can be tested through the respective component interfaces.

Contract Functions Supported

Read Functions

• projectLead() - Get project lead address
• payrollManager() - Get payroll manager address
• paymentToken() - Get payment token address
• payrollPool() - Get available payroll funds
• getContributorCount() - Get total number of contributors
• getContributorUnits(address) - Get units for a contributor
• getContributionDetails(id) - Get contribution details
• whitelistedContributors(address) - Check if address is whitelisted
• getTotalUnitsOutstanding(unitType) - Get total units by type
• getUnitHolders(unitType) - Get holders of a unit type

Write Functions

• whitelistContributor(address) - Add contributor to whitelist
• removeContributor(address) - Remove contributor from whitelist
• submitContribution(unitType, units, description) - Submit contribution
• reviewContribution(id, approved) - Approve/reject contribution
• convertUnits(fromType, toType, amount) - Convert between unit types
• fundPayroll(amount) - Add funds to payroll pool
• executeUnitPayout(unitType, amount) - Distribute funds to unit holders
• setProjectLead(address) - Change project lead
• setPayrollManager(address) - Change payroll manager
• setConversionMultipliers(pToD, pToC, dToC) - Update conversion rates
• setUnitCapacity(unitType, capacity) - Set unit capacity limits

Unit Types

• P-Units (Profit): Decrease on payout, earned through contributions
• D-Units (Debt): Decrease on payout, converted from P-Units with 1.5x multiplier
• C-Units (Capital): Persist on payout (dividend-like), highest in hierarchy

Role Permissions

• Project Lead: Manage contributors, review contributions, set new project lead
• Payroll Manager: Fund payroll, execute payouts, manage conversion rates and capacities
• Contributors: Submit contributions, convert units (if whitelisted)

Architecture Comparison

Aspect	PiePay	Grantships
Scope	Single contract focus	Multi-contract ecosystem
State Management	React Query only	GraphQL + local state
Navigation	Simple tabs	Complex routing
Data Flow	Direct contract calls	Indexer + subgraph
Complexity	Lightweight	Feature-rich

Future Enhancements

The architecture is designed for easy expansion:

1. Activate Additional Tabs: Uncomment components in PiePayDashboard.tsx
2. Add New Features: Extend usePiePayContract hook
3. Enhanced UI: Leverage Mantine's component library
4. Multi-chain Support: Extend chain configuration

Deployment

1. Update the contract address in src/config.ts
2. Build the application: npm run build
3. Deploy the dist folder to your hosting platform

Contract ABI

The contract ABI is automatically included from src/abi/PiePay.json. If you redeploy the contract, make sure to update this file with the new ABI.