A modern community platform connecting volunteers with those who need help.
Tech Stack: React, Node.js, MongoDB
Deployment: Cloudflare Pages (frontend) + Railway/Render (backend) + MongoDB Atlas (database)
- User Authentication: Secure JWT-based authentication with bcrypt password hashing
- User Profiles: Auto-generated gradient avatars, stats tracking, rewards system
- Posts System: Create requests or offers for help with categorization
- Response Management: Accept/decline responses to posts
- Points & Rewards: Gamified system to encourage community participation
- Real-time Filtering: Filter posts by type, category, status, and location
- Mobile Responsive: Beautiful UI built with Tailwind CSS and Radix UI
- React 19 - UI library
- TypeScript - Type safety
- Vite - Build tool
- React Router - Client-side routing
- Tailwind CSS - Styling
- Radix UI - Accessible components
- Lucide React - Icons
- Node.js - Runtime
- Express - Web framework
- Prisma - Database ORM
- MongoDB - Database
- JWT - Authentication
- bcrypt - Password hashing
- Node.js 18+ installed
- MongoDB Atlas account (free tier works)
- Git
git clone <your-repo-url>
cd code_for_humanitycd cfh_backend
# Install dependencies
npm install
# Create .env file with these variables:
# DATABASE_URL="mongodb+srv://username:password@cluster.mongodb.net/community"
# JWT_SECRET="generate-with: node -e 'console.log(require(\"crypto\").randomBytes(32).toString(\"hex\"))'"
# PORT=3001
# NODE_ENV=development
# Get MongoDB connection string from MongoDB Atlas: https://cloud.mongodb.com/
# Generate Prisma client
npm run db:generate
# Push schema to database
npm run db:push
# Seed database with sample data
npm run db:seed
# (Optional) Update avatars to gradients
node scripts/updateAvatars.js
# Start development server
npm run devBackend will run on http://localhost:3001
Environment Variables Required:
DATABASE_URL- MongoDB Atlas connection stringJWT_SECRET- Random secret key for JWT tokens (generate with crypto)PORT- Server port (default: 3001)NODE_ENV- Environment mode (development/production)
cd cfh_fe
# Install dependencies
npm install
# Create .env file with:
# VITE_API_URL=http://localhost:3001/api
# Start development server
npm run devFrontend will run on http://localhost:5173
Environment Variables Required:
VITE_API_URL- Backend API URL (local:http://localhost:3001/api, production:https://your-backend.railway.app/api)
Note: All frontend environment variables must start with VITE_ to be accessible in your React app.
Use these credentials to test the app:
- Volunteer: sarah@email.com / password123
- Help Seeker: robert@email.com / password123
code_for_humanity/
├── cfh_backend/ # Backend API
│ ├── prisma/
│ │ ├── schema.prisma # Database schema
│ │ └── seed.js # Database seeder
│ ├── src/
│ │ ├── routes/ # API routes
│ │ │ ├── auth.js # Authentication endpoints
│ │ │ ├── users.js # User endpoints
│ │ │ └── posts.js # Post endpoints
│ │ ├── middleware/ # Express middleware
│ │ │ └── auth.js # JWT authentication
│ │ └── index.js # App entry point
│ ├── API_DOCUMENTATION.md # Complete API docs
│ └── package.json
│
├── cfh_fe/ # Frontend React app
│ ├── public/
│ │ ├── _redirects # Cloudflare Pages SPA config
│ │ ├── users.json # Mock user data
│ │ └── posts.json # Mock post data
│ ├── src/
│ │ ├── components/ # React components
│ │ ├── contexts/ # React contexts
│ │ │ └── AuthContext.tsx # Auth state management
│ │ ├── pages/ # Page components
│ │ ├── lib/ # Utilities
│ │ │ ├── api.js # API client
│ │ │ └── avatarGenerator.ts # Gradient avatars
│ │ └── types/ # TypeScript types
│ └── package.json
│
├── DEPLOYMENT_GUIDE.md # Complete deployment guide
└── README.md # This file
POST /api/auth/signup- Register new userPOST /api/auth/login- Login userGET /api/auth/me- Get current user (requires auth)
GET /api/users- Get all usersGET /api/users/:id- Get user by IDPUT /api/users/:id- Update userDELETE /api/users/:id- Delete user
GET /api/posts- Get all posts (with filtering)GET /api/posts/:id- Get post by IDPOST /api/posts- Create new postPUT /api/posts/:id- Update postPOST /api/posts/:id/responses- Add response to postPUT /api/posts/:postId/responses/:responseId/accept- Accept responsePUT /api/posts/:postId/responses/:responseId/decline- Decline responsePOST /api/posts/:id/complete- Complete post & award pointsDELETE /api/posts/:id- Delete post
Full API Documentation: See cfh_backend/API_DOCUMENTATION.md
Users earn points by completing tasks. Rewards are automatically awarded:
| Points | Reward |
|---|---|
| 10+ | First Task ⭐ |
| 50+ | Active Participant 🌟 |
| 100+ | Community Helper 💚 |
| 200+ | Super Volunteer 🦸 |
| 300+ | Community Hero 🏆 |
| 500+ | Legend 👑 |
MongoDB Atlas:
- Create free cluster
- Set up database user
- Whitelist IP addresses
- Get connection string
Backend (Railway/Render):
- Push code to GitHub
- Connect repository
- Set environment variables
- Deploy and get URL
Frontend (Cloudflare Pages):
- Push code to GitHub
- Connect repository
- Set build settings
- Add backend URL to env vars
- Deploy
Detailed Guide: See DEPLOYMENT_GUIDE.md for step-by-step instructions
npm run dev # Start development server with nodemon
npm start # Start production server
npm run db:generate # Generate Prisma client
npm run db:push # Push schema to database
npm run db:seed # Seed databasenpm run dev # Start development server
npm run build # Build for production
npm run preview # Preview production build
npm run lint # Run ESLintCan't connect to MongoDB?
- Check your connection string
- Verify IP whitelist in MongoDB Atlas
- Make sure password is correct (no special characters causing issues)
CORS errors?
- Update CORS settings in
cfh_backend/src/index.js - Add your frontend URL to the allowed origins
Build fails?
- Clear node_modules and reinstall:
rm -rf node_modules && npm install - Check Node.js version (18+ required)
JWT errors?
- Make sure JWT_SECRET is set in backend .env
- Check token expiration (7 days by default)
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the ISC License.
For issues, questions, or suggestions, please open an issue on GitHub.
Built with ❤️ for communities everywhere