A production-ready Web3 decentralized application (dApp) that enables users to form rotating savings and credit associations (ROSCAs) using cUSD stablecoins on the Celo blockchain.

• Group Savings Circles: Create and join rotating savings groups with customizable parameters
• Real Celo Integration: Actual cUSD transactions on Celo Alfajores (testnet) and mainnet
• Wallet Support: MetaMask, Valora, and other Celo-compatible wallets
• Transparent Payouts: All transactions recorded on-chain for full transparency

• SEO Optimized: Complete meta tags, Open Graph, Twitter Cards, and structured data
• Mobile-First Design: Responsive UI optimized for mobile and desktop
• AI Chatbot: OpenAI-powered assistant for user support and guidance
• Referral System: Earn 5 cUSD for successful referrals with unique referral codes
• Leaderboard: Community rankings by referrals and contributions
• Landing Page: Professional marketing page with FAQ and video integration

• Real Blockchain Transactions: Integrated with Celo network for actual cUSD transfers
• Mock Transaction Mode: Development-friendly transaction simulation for testing
• Network Auto-Detection: Automatically switches to correct Celo network
• Balance Tracking: Real-time cUSD and CELO balance display
• Transaction History: Explorer links for all blockchain transactions
• Error Handling: Comprehensive error management and user feedback
• TypeScript: Full type safety throughout the application
• Testing: Comprehensive test coverage for core functionality

• Node.js 18+ and npm
• MetaMask or Celo-compatible wallet
• Some CELO for gas fees (free from Alfajores faucet for testnet)

# Install dependencies
npm install

# Configure environment variables
cp .env.example .env
# Edit .env with your API keys and configuration

# Start the development server
npm run dev

The app will be available at http://localhost:5000

Create a .env file from .env.example and configure:

• VITE_USE_MOCK_TX=true for development with mock transactions
• VITE_CELO_NETWORK=alfajores for testnet
• OPENAI_API_KEY=your_key for chatbot functionality

1. Install MetaMask or Valora wallet

2. Add Celo Alfajores testnet:

   • Network Name: Celo Alfajores Testnet
   • RPC URL: https://alfajores-forno.celo-testnet.org
   • Chain ID: 44787
   • Currency: CELO
   • Explorer: https://explorer.celo.org/alfajores

3. Get test tokens from Celo Faucet

• React 18 with TypeScript for type safety
• Tailwind CSS for responsive styling
• Radix UI components for accessibility
• Wouter for client-side routing
• React Query for server state management

• Ethers.js v6 for Ethereum/Celo interactions
• Celo ContractKit for Celo-specific functionality
• cUSD Token Contract for stablecoin transactions
• Real Wallet Integration with MetaMask and Valora

• Express.js REST API
• OpenAI Integration for chatbot functionality
• TypeScript throughout the stack
• Vite for fast development and building

• LocalStorage for client-side persistence
• Zod for runtime type validation
• Database Ready with Drizzle ORM setup
• Session Management for wallet connections

1. Connect your wallet on the landing page
2. Navigate to "Create Group"
3. Set group parameters:
   • Group name and description
   • Contribution amount (minimum 10 cUSD)
   • Payment frequency (weekly/monthly)
   • Group duration (7-365 days)
4. Share the generated invite code with friends

1. Get an invite code from a group creator
2. Click "Join Group" and enter the code
3. Review group details and confirm participation
4. Make your first contribution to activate membership

1. Go to your group's detail page
2. Click "Make Contribution"
3. Confirm the transaction in your wallet
4. Track your progress on the dashboard

• Earn 5 cUSD for each successful referral
• Friends must join a group and make first contribution
• Rewards credited automatically

• Earn 2 cUSD for maintaining 3+ consecutive contributions
• Bonus awarded automatically
• Encourages consistent saving habits

# Optional: OpenAI API key for enhanced chatbot
OPENAI_API_KEY=your_openai_api_key_here

# Optional: Database URL for persistent storage
DATABASE_URL=your_postgresql_url_here

Edit client/src/config/constants.ts to switch between:

• Alfajores (testnet) - Default for development
• Mainnet - For production deployment

├── client/
│   ├── src/
│   │   ├── components/     # UI components
│   │   ├── pages/         # Route components
│   │   ├── contexts/      # React contexts
│   │   ├── lib/           # Utilities and services
│   │   └── config/        # Configuration files
├── server/                # Express backend
├── shared/               # Shared types and schemas
└── docs/                # Documentation

• WalletProvider: Manages Celo wallet connections
• CeloWalletService: Handles blockchain interactions
• ChatBot: AI-powered user assistance
• LandingPage: SEO-optimized marketing page

# Run type checking
npm run typecheck

# Check for linting issues
npm run lint

# Build for production
npm run build

1. Connect your GitHub repository to Vercel
2. Set environment variables in Vercel dashboard
3. Deploy with automatic CI/CD

# Build the application
npm run build

# Deploy the dist folder
# Configure your server to serve the static files

The integrated chatbot provides:

• Wallet connection guidance
• Group creation help
• cUSD and Celo blockchain education
• Troubleshooting support
• Platform feature explanations

• Uses established cUSD token contract on Celo
• No custom smart contracts reduce attack surface
• All transactions verified on-chain

• Never stores private keys or seed phrases
• Uses secure wallet connection protocols
• Encourages hardware wallet usage

• Minimal data collection
• Wallet addresses are public blockchain data
• No personal information required

• Celo Documentation
• cUSD Stablecoin
• MetaMask Setup
• Valora Wallet

• Discord
• Twitter
• GitHub

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

MIT License - see LICENSE file for details

Built with ❤️ by Edcode and Bruno Maa

StableCircle - Empowering communities through decentralized group savings on Celo 🌍