🖥️ TrustFlow Frontend

The decentralized UI for the TrustFlow gig-economy protocol.

TrustFlow Frontend is the Next.js web application that gives users a seamless interface for creating escrows, tracking milestones, resolving disputes, and managing their on-chain reputation — all powered by Soroban smart contracts on the Stellar network.

🚀 Live Demo (Coming Soon) | 📖 Documentation | 🤝 Contributing

---

✨ Core Features

• 🔗 Wallet Integration: One-click Stellar wallet connection via Freighter.
• 💼 Escrow Dashboard: Create, fund, and track milestone-based escrow vaults.
• 🎯 Gig Explorer: Browse and filter available gigs with search functionality.
• 🏆 Freelancer Leaderboard: Compare top earners and highest-reputation workers.
• 📝 Gig Creation Wizard: Multi-step form to create milestone-based gigs.
• ⚖️ Dispute Interface: Submit evidence, monitor juror votes, and receive settlement outcomes.
• 🌗 Dark / Light Mode: System-aware theme toggling via the useTheme hook.
• 🔔 Toast Notifications: Non-blocking feedback for all transaction states.
• 📱 Responsive Design: Mobile-first layout across all breakpoints.

---

🛠️ Tech Stack

• Framework: Next.js 13 (Pages Router)
• Language: TypeScript 5
• Styling: Tailwind CSS 3 + CSS Modules
• Blockchain: Stellar + Soroban
• Wallet: Freighter
• State Management: React Hooks + Context API

---

📄 Available Pages

• / - Landing page with feature showcase
• /dashboard - User dashboard (My Gigs)
• /dashboard/disputes - Active disputes
• /dashboard/profile - User profile and reputation
• /dashboard/settings - Account settings
• /explore - Browse available gigs
• /leaderboard - Global freelancer rankings by earnings and reputation
• /create-gig - Multi-step gig creation wizard

---

🗂️ Project Structure

├── pages/
│   ├── _app.tsx            # App shell — providers, global styles
│   └── index.tsx           # Landing / dashboard entry point
├── components/
│   ├── atoms/              # Primitive UI: Button, Card, Input, Checkbox, ProgressBar, Toast
│   ├── molecules/          # Composed UI: Deposits, FormPledge, TransactionModal, WalletData
│   └── organisms/          # Page-level sections: Navbar, Campaign, Pledge
├── hooks/
│   ├── useAccount.ts       # Stellar wallet account state
│   ├── useSubscription.ts  # Real-time contract event subscriptions
│   ├── useTheme.ts         # Dark/light theme management
│   ├── useToast.ts         # Toast notification queue
│   └── useIsMounted.ts     # SSR hydration safety guard
├── shared/
│   ├── contracts.ts        # Shared contract address constants
│   └── utils.ts            # Shared utility functions
├── styles/
│   ├── globals.css         # Global styles and CSS variables
│   └── Home.module.css     # Homepage styles
└── public/                 # Static assets and favicon

---

🚀 Getting Started

Prerequisites

• Node.js >= 18
• Freighter Wallet browser extension
• A funded Stellar testnet account

Installation

npm install

Environment Setup

cp .env.example .env

Key variables:

NEXT_PUBLIC_STELLAR_NETWORK=TESTNET
NEXT_PUBLIC_SOROBAN_RPC_URL=https://soroban-testnet.stellar.org
NEXT_PUBLIC_ESCROW_CONTRACT_ID=your-contract-id

Running

# Development
npm run dev

# Lint code
npm run lint

# Type-check
npm run typecheck

# Production build
npm run build

# Start production server
npm start

Open http://localhost:3000 in your browser.

---

📖 Component Guide

Atoms

Base-level, stateless UI primitives. Use these directly or compose them into molecules.

• Button — primary, secondary, and loading states.
• AmountInput — numeric input with token denomination label.
• ProgressBar — milestone completion indicator.
• Toast — auto-dismissing notification bubble (integrated globally).
• ThemeToggle — dark/light mode switcher (integrated in Navbar).

Using Toast Notifications:

import { useGlobalToast } from '../pages/_app'

function MyComponent() {
  const toast = useGlobalToast()

  const handleSuccess = () => toast.success('Transaction confirmed!')
  const handleError = () => toast.error('Connection failed')
  const handleWarning = () => toast.warning('Low balance detected')
  const handleInfo = () => toast.info('Fetching data...')

  return <button onClick={handleSuccess}>Show Toast</button>
}

Molecules

Stateful compositions built from atoms.

• FormPledge — full pledge form with validation and submission.
• TransactionModal — step-by-step transaction status overlay.
• WalletData — connected wallet summary card.
• Deposits — list of active deposits with release controls.

Organisms

Full page sections wired to on-chain data.

• Navbar — responsive top nav with wallet connect.
• Campaign — campaign detail with funding progress.
• Pledge — pledge workflow from input to confirmation.

🧭 Architecture Notes

• The project currently uses the Next.js Pages Router. The Freelancer Leaderboard is implemented at pages/leaderboard.tsx to match the existing routing convention.
• The leaderboard is backed by typed local sample data until the protocol exposes a public ranking endpoint or indexer query. The UI sorts the same dataset by total escrow earnings or reputation score.
• No new runtime dependencies were added for this feature.

---

🛡️ Security

• No private keys ever touch the browser — all signing delegated to Freighter.
• Contract IDs and RPC URLs loaded strictly from environment variables.
• XDR simulation run before every transaction submission.

---

🗺️ Roadmap

✅ Completed

• Landing page with feature showcase
• Dark/Light mode theming
• Toast notification system
• User dashboard with sidebar navigation
• Gig explorer with search and filtering
• Multi-step gig creation wizard
• Responsive mobile-first design

🚧 In Progress

• Wallet Integration (#21): Full Freighter API integration
• Escrow SDK (#16): Connect gig creation to smart contracts
• Profile Pages (#10): On-chain reputation and work history viewer

📋 Planned

• Dispute UI (#15): Full juror dashboard with evidence upload and voting
• Mobile Navbar (#34): Enhanced mobile navigation
• i18n Support (#8): Multi-language support via next-intl
• Real-time Updates (#12): WebSocket integration for live notifications

View all issues →

---

🤝 Contributing

We welcome contributions from the community! Whether you're fixing bugs, adding features, or improving documentation, your help is appreciated.

Quick Start for Contributors

1. Find an issue: Check good first issues or help wanted
2. Read the guide: See CONTRIBUTING.md for detailed instructions
3. Set up locally: Follow the installation steps above
4. Make your changes: Create a feature branch and commit your work
5. Submit a PR: Open a pull request with a clear description

Development Workflow

# 1. Fork and clone the repo
git clone https://github.com/YOUR_USERNAME/trustflow-frontend.git

# 2. Create a feature branch
git checkout -b feature/your-feature-name

# 3. Make changes and test
npm run dev
npm run lint
npm run typecheck
npm run build

# 4. Commit and push
git commit -m "feat: add your feature"
git push origin feature/your-feature-name

Areas We Need Help

• 🔗 Blockchain Integration: Freighter wallet and Soroban contract integration
• 🎨 UI Components: Additional components and improvements
• 📝 Documentation: Improving guides and code comments
• 🧪 Testing: Adding unit and E2E tests
• 🐛 Bug Fixes: Resolving reported issues

Read the full contributing guide →

---

🤝 Community & Support

• Documentation: Full Docs
• Issues: Report bugs or request features
• Discussions: Stellar Community Forum

---

Securing the future of work, one transaction at a time.

---

📜 License

MIT License. Copyright (c) 2026 TrustFlow Protocol.

📊 Project Status

This project is under active development. The UI foundation is complete and ready for blockchain integration. We're actively seeking contributors, especially those with:

• Stellar/Soroban smart contract experience
• React/Next.js expertise
• UI/UX design skills

Good First Issues: Start here