ProofOfHeart

A decentralized launchpad where the community — not a corporation — validates a cause.

ProofOfHeart empowers everyday people to rally behind the causes they believe in. By leveraging blockchain transparency and community-driven governance, it removes gatekeepers from the fundraising process and puts trust back where it belongs: in the hands of the people.

🌟 Vision & Mission

• Vision: A world where any meaningful cause can receive support without needing permission from a centralized authority.
• Mission: To build an open, transparent launchpad that lets communities discover, validate, and fund causes through decentralized consensus — ensuring that every voice counts and every contribution is accounted for on-chain.

🚀 Core Principles

• Community First: Causes are validated by the people, not by a corporate board.
• Radical Transparency: Every decision and transaction lives on-chain for anyone to verify.
• Permissionless Participation: Anyone can propose, support, or challenge a cause.
• Trust Through Code: Smart contracts enforce the rules, removing the need for intermediaries.

🛠 Tech Stack

Layer	Technology
Framework	Next.js 16 (App Router)
Language	TypeScript
Styling	Tailwind CSS v4
Animations	Framer Motion
Linting	ESLint 9
Runtime	Node.js (v22+)

🏗 Architecture

The project follows the standard Next.js App Router architecture:

• src/app/: Contains the routes, layouts, and page-specific logic.
• src/components/: (Planned) Reusable UI components.
• src/hooks/: (Planned) Custom React hooks for state and API interaction.
• src/utils/: (Planned) Utility functions and constants.
• public/: Static assets like images and fonts.

✨ Current Frontend Features

• Campaign exploration and detail pages backed by the Soroban contract service layer.
• Wallet-aware creator and contributor actions including withdrawal, refunds, and admin verification.
• Platform fee transparency across contribution, withdrawal, and cause detail views, with a 3% fallback until the get_platform_fee getter is available on-chain.
• Wallet dashboard contribution history with per-campaign status, claimable refund/revenue actions, and Stellar explorer transaction links.
• Revenue sharing support for eligible Educational Startup campaigns: creator dashboard deposit flow, contributor claim flow, revenue pool display, and transparent pro-rata breakdowns.
• Admin dashboard at /admin with wallet-gated access, pending campaign verification, platform fee updates, admin transfer, and contract-level stats.

🏁 Getting Started

Prerequisites

• Node.js (Version 22 or higher)
• npm

Installation

1. Clone the repository:

   git clone https://github.com/Iris-IV/ProofOfHeart-frontend.git
   cd ProofOfHeart-frontend

2. Install dependencies:

   npm install

Local Development

Run the development server:

npm run dev

Open http://localhost:3000 with your browser to see the result.

⚙️ Configuration

The project uses environment variables for configuration. Create a .env.local file in the root directory:

# Example Environment Variables
NEXT_PUBLIC_API_URL=https://api.proofofheart.org
# NEXT_PUBLIC_CHAIN_ID=1
NEXT_PUBLIC_RPC_URL=https://soroban-testnet.stellar.org
NEXT_PUBLIC_NETWORK_PASSPHRASE=Test SDF Network ; September 2015
# Optional off-chain webhook for creator email opt-ins
NEXT_PUBLIC_CREATOR_EMAIL_WEBHOOK_URL=

NEXT_PUBLIC_API_URL is the base URL for the off-chain service layer used by campaign comments, updates, reports, and wallet transaction history.

Expected endpoints under that base URL:

• GET /campaigns/:campaignId/updates
• POST /campaigns/:campaignId/updates
• GET /campaigns/:campaignId/comments
• POST /campaigns/:campaignId/comments
• POST /campaigns/:campaignId/comments/:commentId/pin
• POST /campaigns/:campaignId/comments/:commentId/report
• POST /campaign-reports
• PATCH /campaign-reports
• POST /wallet-transactions

Authenticated off-chain mutations send wallet signatures with:

• X-Wallet-Address
• X-Request-Signature
• X-Request-Timestamp
• X-Request-Purpose

The client retries transient failures and falls back to the existing mock/local stores when NEXT_PUBLIC_API_URL is not set.

🚀 Mainnet Launch Checklist

Before going live on the Stellar public network, ensure the following production-readiness items are complete:

Smart Contract

• get_platform_fee getter deployed on mainnet (remove the 3% hardcoded fallback)
• Contract address and network passphrase updated to mainnet values in .env.production
• Full audit of Soroban contract completed and findings addressed
• Emergency pause / admin-transfer mechanisms tested on mainnet

Frontend

• NEXT_PUBLIC_NETWORK_PASSPHRASE set to Public Global Stellar Network ; September 2015
• NEXT_PUBLIC_RPC_URL pointed at a production Horizon / Soroban RPC endpoint
• NEXT_PUBLIC_API_URL pointed at the production off-chain service
• Error boundary wired to a production error tracker (e.g. Sentry)
• All console warnings and TypeScript errors resolved (npm run build passes cleanly)
• Lighthouse / Core Web Vitals baseline captured

Security & Operations

• Content Security Policy (CSP) headers configured for production
• Rate limiting enabled on off-chain API endpoints
• Secrets rotated; no .env.local values committed to the repository
• Docker production image built and smoke-tested (docker build + docker run)
• CI pipeline passes on main (lint → build → tests)

Communications

• Community announcement drafted
• Docs/README updated with mainnet contract address and explorer links

🤝 Contributing!

Please review our Security Policy for information on how to responsibly disclose vulnerabilities.

Please read our Code of Conduct before contributing.

We welcome contributions! To maintain a clean and consistent codebase, please follow these guidelines:

1. Fork the repository and create your branch from main.
2. Naming Convention: Use descriptive branch names (e.g., feat/add-onboarding, fix/login-error).
3. Code Style:
   • Use Functional Components with Hooks.
   • Follow the existing TypeScript patterns.
   • Run npm run lint before committing.
4. Pull Requests:
   • Provide a clear description of the changes.
   • Reference any related issues.
   • Ensure your code builds locally (npm run build).

Internationalization (i18n)

To keep our translation files clean, you can run the unused keys script to find keys that exist in the English messages file but are no longer referenced in the source code:

node scripts/find-unused-i18n-keys.js

This script will output a report of keys present in messages/en.json but never referenced in src/.

🐳 Docker Support

To ensure a consistent development environment, we support containerization with Docker.

Local Development

Run the following command to start the application in development mode with hot-reloading:

docker-compose up

Production Build

To build the production image manually:

docker build -t proofofheart-frontend .

To run the production container:

docker run -p 3000:3000 proofofheart-frontend

🛡 Error Reporting

src/components/ErrorBoundary.tsx exposes an optional onError prop that receives a PII-safe error report (name, message, stack) whenever a React render error is caught.

Wiring Sentry (or another provider)

1. Install the SDK: npm install @sentry/nextjs
2. Follow the Sentry Next.js setup guide to create sentry.client.config.ts.
3. Pass onError wherever you render <ErrorBoundary>:

import * as Sentry from "@sentry/nextjs";
import ErrorBoundary from "@/components/ErrorBoundary";

<ErrorBoundary
  onError={({ name, message, stack }) =>
    Sentry.captureException(Object.assign(new Error(message), { name, stack }))
  }
>
  {children}
</ErrorBoundary>;

Only error.name, error.message, and error.stack are forwarded — no user data or wallet addresses are included by default.

📄 License

This project is licensed under the MIT License.

---

Built with ❤️ by the ProofOfHeart Community.