A production-grade decentralized humanitarian aid platform frontend built on the Stellar blockchain
Features • Tech Stack • Installation • Documentation • Contributing
- Transparent Donations: Every transaction is tracked on the Stellar blockchain for full transparency
- Campaign Management: Create, fund, and track humanitarian aid campaigns with advanced filtering
- Beneficiary Portal: Claim aid with QR verification and track claim history
- Admin Dashboard: Verify beneficiaries, moderate campaigns, and monitor platform activity
- Real-time Analytics: Track donations, distributions, and impact metrics with live updates
- Multi-wallet Support: Compatible with Freighter, Rabet, XBull, and more wallet providers
- Responsive Design: Optimized for desktop, tablet, and mobile devices with bottom navigation
- Dark/Light Mode: Built-in theme switching with smooth transitions
- Accessibility: WCAG 2.1 AA compliant for inclusive design
- Gamification: Impact badges and achievements to encourage donor engagement
- Social Sharing: Share campaigns on X, Facebook, LinkedIn with one click
- Campaign Comparison: Compare up to 3 campaigns side-by-side for informed decisions
- Export Functionality: Export donation history in CSV or JSON formats
- Notification Center: Real-time notifications for donations and updates
- Framework: Next.js 15 (App Router)
- Language: TypeScript
- Styling: TailwindCSS + shadcn/ui
- State Management: Zustand
- Data Fetching: React Query
- Animations: Framer Motion
- Blockchain: Stellar SDK + Soroban
- Wallet Integration: Stellar Wallet Kit
- Testing: Jest + Playwright
- CI/CD: GitHub Actions
- Deployment: Vercel
- Node.js 20 or higher
- npm or yarn
- Git
- Clone the repository:
git clone https://github.com/your-org/aidlink-frontend.git
cd aidlink-frontend- Install dependencies:
npm install- Set up environment variables:
cp .env.example .env.local- Run the development server:
npm run dev- Open http://localhost:3000 in your browser
All client-side environment variables must be prefixed with NEXT_PUBLIC_. After changing any of them, restart the dev server.
Copy the example file and fill in your values:
cp .env.example .env.local| Variable | Description | Default |
|---|---|---|
NEXT_PUBLIC_HORIZON_MAINNET |
Mainnet Horizon REST API URL | https://horizon.stellar.org |
NEXT_PUBLIC_HORIZON_TESTNET |
Testnet Horizon REST API URL | https://horizon-testnet.stellar.org |
NEXT_PUBLIC_HORIZON_FUTURENET |
Futurenet Horizon REST API URL | https://horizon-futurenet.stellar.org |
NEXT_PUBLIC_HORIZON_STANDALONE |
Standalone Horizon REST API URL | http://localhost:8000 |
NEXT_PUBLIC_SOROBAN_RPC_MAINNET |
Mainnet Soroban RPC endpoint | https://rpc.mainnet.stellar.org |
NEXT_PUBLIC_SOROBAN_RPC_TESTNET |
Testnet Soroban RPC endpoint | https://soroban-testnet.stellar.org |
NEXT_PUBLIC_SOROBAN_RPC_FUTURENET |
Futurenet Soroban RPC endpoint | https://rpc-futurenet.stellar.org |
NEXT_PUBLIC_SOROBAN_RPC_STANDALONE |
Standalone Soroban RPC endpoint | http://localhost:8000/soroban/rpc |
NEXT_PUBLIC_DEFAULT_NETWORK |
Default network | testnet |
NEXT_PUBLIC_SUPPORTED_NETWORKS |
Comma-separated list of networks | testnet,futurenet |
NEXT_PUBLIC_AID_TOKEN_CONTRACT |
AID token contract ID | (empty) |
NEXT_PUBLIC_CAMPAIGN_MANAGER_CONTRACT |
Campaign manager contract ID | (empty) |
NEXT_PUBLIC_BENEFICIARY_REGISTRY_CONTRACT |
Beneficiary registry contract ID | (empty) |
NEXT_PUBLIC_API_URL |
Backend API base URL | http://localhost:3000/api |
NEXT_PUBLIC_ENABLE_ANALYTICS |
Enable analytics tracking | true |
NEXT_PUBLIC_ENABLE_ERROR_TRACKING |
Enable error tracking | true |
The application supports multiple Stellar networks configured at runtime via environment variables:
- Testnet (
testnet): Default for development and testing - Futurenet (
futurenet): For testing upcoming protocol features - Mainnet (
mainnet): Production network - Standalone (
standalone): Local development with Quickstart Docker image
aidlink-frontend/
├── src/
│ ├── app/ # Next.js app router pages
│ │ ├── (auth)/ # Authentication pages
│ │ ├── (dashboard)/ # Dashboard pages
│ │ ├── (public)/ # Public pages
│ │ ├── api/ # API routes
│ │ ├── campaigns/ # Campaign pages
│ │ ├── beneficiary/ # Beneficiary portal
│ │ └── admin/ # Admin portal
│ ├── components/ # React components
│ │ ├── features/ # Feature-specific components
│ │ ├── layout/ # Layout components
│ │ └── ui/ # shadcn/ui components
│ ├── hooks/ # Custom React hooks
│ ├── lib/ # Utility libraries
│ │ └── soroban/ # Soroban SDK integration
│ ├── store/ # Zustand stores
│ ├── types/ # TypeScript types
│ ├── config/ # Configuration files
│ └── utils/ # Utility functions
├── e2e/ # Playwright E2E tests
├── public/ # Static assets
├── .github/ # GitHub Actions workflows
└── docs/ # Documentation
npm run testnpm run test:e2enpm run lintnpm run type-checkBuild the Docker image:
docker build -t aidlink-frontend .Run the container:
docker run -p 3000:3000 aidlink-frontendThe easiest way to deploy is using Vercel:
- Push your code to GitHub
- Import the project in Vercel
- Add environment variables
- Deploy
Deploy using Docker to any container registry:
docker build -t aidlink-frontend .
docker tag aidlink-frontend your-registry/aidlink-frontend
docker push your-registry/aidlink-frontend- Architecture Documentation - System architecture and design patterns
- Component Documentation - Reusable component library
- API Documentation - API endpoints and integration guide
- Deployment Guide - Deployment instructions for various platforms
- Testing Guide - Testing strategies and best practices
- Contributing Guide - How to contribute to the project
We welcome contributions! Please read our Contributing Guide before submitting a pull request.
This project is licensed under the MIT License.
- Stellar Development Foundation
- shadcn/ui
- Vercel
- The open-source community
For support, email support@aidlink.org or open an issue on GitHub.
Check out the live demo at demo.aidlink.org (coming soon)
- Multi-language support (i18n)
- Advanced analytics dashboard
- Mobile app (React Native)
- AI-powered campaign recommendations
- Integration with more blockchain networks
- Advanced reporting features
- Video verification for beneficiaries
- Smart contract audit and verification