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
- 🔗 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
useThemehook. - 🔔 Toast Notifications: Non-blocking feedback for all transaction states.
- 📱 Responsive Design: Mobile-first layout across all breakpoints.
- 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
/- 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
├── 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
- Node.js >= 18
- Freighter Wallet browser extension
- A funded Stellar testnet account
npm installcp .env.example .envKey variables:
NEXT_PUBLIC_STELLAR_NETWORK=TESTNET
NEXT_PUBLIC_SOROBAN_RPC_URL=https://soroban-testnet.stellar.org
NEXT_PUBLIC_ESCROW_CONTRACT_ID=your-contract-id# Development
npm run dev
# Lint code
npm run lint
# Type-check
npm run typecheck
# Production build
npm run build
# Start production server
npm startOpen http://localhost:3000 in your browser.
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>
}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.
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.
- The project currently uses the Next.js Pages Router. The Freelancer Leaderboard is implemented at
pages/leaderboard.tsxto 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.
- The profile page fetches reputation, bio, and past gigs from
GET /api/profile, which proxies toPROFILE_API_BASE_URLwhen configured and falls back to typed mock data for local/dev environments. - No new runtime dependencies were added for this feature.
- 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.
- 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
- 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
- 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
We welcome contributions from the community! Whether you're fixing bugs, adding features, or improving documentation, your help is appreciated.
- Find an issue: Check good first issues or help wanted
- Read the guide: See CONTRIBUTING.md for detailed instructions
- Set up locally: Follow the installation steps above
- Make your changes: Create a feature branch and commit your work
- Submit a PR: Open a pull request with a clear description
# 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- 🔗 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 →
- Documentation: Full Docs
- Issues: Report bugs or request features
- Discussions: Stellar Community Forum
Securing the future of work, one transaction at a time.
MIT License. Copyright (c) 2026 TrustFlow Protocol.
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