A community-driven web platform enabling neighbors to lend, borrow, and gift everyday items and services — without ever leaving their neighborhood.
CivicSwap addresses a common urban coordination failure: households collectively own enormous quantities of items (tools, kitchenware, books, camping gear, appliances) that sit unused 95% of the time, while neighbors spend money buying or renting those very same items nearby.
CivicSwap transforms idle household resources into shared community capital by connecting neighbors through a structured, trustworthy platform anchored to real geographic locations.
| Service | URL |
|---|---|
| Frontend | https://civicswap-frontend.vercel.app |
| Backend API | https://civicswap-backend.up.railway.app/api |
| Health Check | https://civicswap-backend.up.railway.app/api/health |
- 🗺️ Hyper-Local Discovery — Interactive Leaflet.js map with adjustable radius (0.5–10 km) to find available items near your location
- 🔄 Borrow Lifecycle Management — Structured 6-state workflow: Request → Approval → ON_LOAN → Return → Rating → Closed
- ⭐ Reputation & Rating System — Transparent trust scores calculated as weighted averages from completed transactions
- 📧 Automated Email Notifications — Brevo REST API triggers emails at every stage of the borrow lifecycle
- 🔍 Search & Category Filters — Find items by keyword, category (Tools, Books, Kitchenware, Electronics, etc.), distance, or date
- 📱 Responsive UI — Premium Airbnb-inspired design with parallax, hover effects, and smooth transitions — works on desktop, tablet, and mobile
- 🔒 JWT Authentication — Secure stateless session management with bcrypt password hashing
- 📍 Browser Geolocation — Auto-detect user location during registration and item posting
- 🛡️ Overlap Validation — Prevents double-booking of items on conflicting dates
| Layer | Technology |
|---|---|
| Frontend Framework | React 18 + Vite |
| Styling | Tailwind CSS (CDN) |
| Maps | Leaflet.js + React-Leaflet + MongoDB $nearSphere |
| Backend | Node.js + Express.js |
| Database | MongoDB + Mongoose (MongoDB Atlas) |
| Authentication | JWT (jsonwebtoken) + bcryptjs |
| Email Service | Brevo REST API (via Axios over HTTPS) |
| HTTP Client | Axios (frontend + backend) |
| Frontend Hosting | Vercel |
| Backend Hosting | Railway |
| Version Control | Git & GitHub |
| API Testing | Thunder Client (VS Code Extension) |
| IDE | Visual Studio Code |
- User Authentication — Registration, login, JWT session management, home location setup (lat/lng via browser Geolocation API)
- Geographic Discovery — Leaflet.js interactive map, radius-based item filtering using MongoDB
$nearSphere, adjustable radius slider (0.5–10 km) - Item Management — Post/edit listings with title, description, category, location, and status (AVAILABLE / ON_LOAN / UNAVAILABLE)
- Borrow Lifecycle — 6-state machine: PENDING → APPROVED → ON_LOAN → RETURNED → CLOSED (or REJECTED); conflict detection for overlapping bookings
- Reputation & Rating — Star ratings (1–5) after each completed transaction; weighted average reputation scores displayed on user profiles
- Notifications — Automated emails via Brevo REST API for request submission, approval/rejection, return confirmation, and rating prompts
- Database Management — MongoDB with Mongoose ODM, 2dsphere geo-indexes, FK-style references, and scheduling conflict validation
- Search & Filter — Keyword search, category filter, sort by distance, integrated with geographic radius
- Responsive UI — Premium dark-themed dashboard with item cards, status badges, transaction history, map view, and user profiles
CivicSwap/
├── civicswap-backend/
│ ├── config/
│ │ └── db.js # MongoDB Atlas connection
│ ├── models/
│ │ ├── User.js # User schema with geo-location + bcrypt
│ │ ├── Item.js # Item schema with 2dsphere index
│ │ ├── Transaction.js # 6-state lifecycle model
│ │ └── Rating.js # Rating with unique constraint
│ ├── controllers/
│ │ ├── authController.js # Register, login, profile
│ │ ├── itemController.js # CRUD + geo-filter
│ │ ├── transactionController.js # Full borrow lifecycle + email triggers
│ │ └── ratingController.js # Ratings + auto reputation update
│ ├── routes/
│ │ ├── authRoutes.js
│ │ ├── itemRoutes.js
│ │ ├── transactionRoutes.js
│ │ └── ratingRoutes.js
│ ├── middleware/
│ │ └── authMiddleware.js # JWT token verification
│ ├── utils/
│ │ ├── sendEmail.js # Brevo REST API email utility
│ │ └── keepAlive.js # Health ping utility
│ ├── .env
│ └── server.js
│
└── civicswap-frontend/
├── src/
│ ├── components/
│ │ ├── Navbar.jsx # Auth-aware navbar with scroll effect
│ │ ├── ItemCard.jsx
│ │ └── ProtectedRoute.jsx # JWT-protected route wrapper
│ ├── context/
│ │ └── AuthContext.jsx # Global JWT + user state
│ ├── pages/
│ │ ├── HomePage.jsx # Parallax hero, stats, features
│ │ ├── LoginPage.jsx # Split layout with animated form
│ │ ├── RegisterPage.jsx # Geolocation-enabled registration
│ │ ├── DashboardPage.jsx # Stats cards + recent activity
│ │ ├── ItemListPage.jsx # Search + filter + geo-sorted grid
│ │ ├── ItemDetailPage.jsx # Item info + borrow request form
│ │ ├── CreateItemPage.jsx # Category selector + location detect
│ │ ├── EditItemPage.jsx # Pre-filled form + status toggle
│ │ ├── MapPage.jsx # Leaflet.js map + radius slider
│ │ ├── ProfilePage.jsx # Reputation + items + reviews
│ │ ├── EditProfilePage.jsx # Name, bio, password, location
│ │ ├── TransactionPage.jsx # Activity + incoming requests tabs
│ │ └── RatingPage.jsx # Interactive star rating
│ └── utils/
│ └── axios.js # Axios instance with JWT injection
├── vercel.json # SPA routing fix for Vercel
└── index.html
- Computer/Laptop with minimum 4 GB RAM (8 GB recommended)
- Internet connection (for APIs, map tiles, MongoDB Atlas, deployment)
- Minimum 20 GB free disk space for development environment and database
- Smartphone (optional) — for testing the responsive mobile interface
- OS: Windows 10/11 / Ubuntu 20.04+ / macOS
- Runtime: Node.js 18+
- Package Manager: npm
- Database: MongoDB 6+ (local) or MongoDB Atlas (cloud)
- Git & GitHub
- Web Browser: Google Chrome / Mozilla Firefox
Make sure you have Node.js 18+ and npm installed:
node --version
npm --version# 1. Clone the repository
git clone https://github.com/<your-username>/civicswap.git
cd civicswap/civicswap-backend
# 2. Install dependencies
npm install
# 3. Configure environment variables
cp .env.example .env
# Edit .env with your credentials.env configuration:
PORT=5000
MONGO_URI=mongodb://localhost:27017/civicswap
JWT_SECRET=your_jwt_secret_key
JWT_EXPIRE=7d
EMAIL_FROM=your_email@gmail.com
BREVO_API_KEY=your_brevo_api_key
NODE_ENV=development# 4. Start the backend server
npm run devBackend runs at http://localhost:5000
# 1. Navigate to frontend directory
cd ../civicswap-frontend
# 2. Install dependencies
npm install
# 3. Update API base URL in src/utils/axios.js
# baseURL: 'http://localhost:5000/api'
# 4. Start the frontend dev server
npm run devFrontend runs at http://localhost:5173
| Method | Endpoint | Access | Description |
|---|---|---|---|
POST |
/api/auth/register |
Public | Register user with location |
POST |
/api/auth/login |
Public | Login, returns JWT token |
GET |
/api/auth/profile |
Private | Get logged-in user profile |
PUT |
/api/auth/profile |
Private | Update name, bio, password, location |
| Method | Endpoint | Access | Description |
|---|---|---|---|
GET |
/api/items |
Private | Get items with optional geo-filter |
POST |
/api/items |
Private | Create new item listing |
GET |
/api/items/:id |
Private | Get single item with owner details |
PUT |
/api/items/:id |
Private | Update item (owner only) |
DELETE |
/api/items/:id |
Private | Delete item (owner only) |
Geo-filter params:
?latitude=28.59&longitude=78.55&radius=5&category=Tools&search=drill
| Method | Endpoint | Access | Description |
|---|---|---|---|
POST |
/api/transactions |
Private | Create borrow request |
GET |
/api/transactions/my |
Private | Get all my transactions |
GET |
/api/transactions/requests |
Private | Get incoming PENDING requests |
PUT |
/api/transactions/:id/approve |
Private | Approve request (lender only) |
PUT |
/api/transactions/:id/reject |
Private | Reject request (lender only) |
PUT |
/api/transactions/:id/return |
Private | Mark item as returned |
| Method | Endpoint | Access | Description |
|---|---|---|---|
POST |
/api/ratings |
Private | Submit rating after return |
GET |
/api/ratings/user/:id |
Private | Get all ratings for a user |
- WhatsApp / Telegram Integration — Borrow notifications directly on preferred messaging apps
- AI-Based Recommendations — Suggest items based on borrowing history, location, and community preferences
- Mobile App — Dedicated Android & iOS app with push notifications and real-time map updates
- Tiered Trust Badges — "Verified Neighbor", "Top Lender" badges + penalty flags for late returns
- Payment Gateway — Optional damage deposits via Razorpay / PayPal for high-value items
- Community Forums & Events — Discussion boards and neighborhood events section
- Advanced Analytics Dashboard — Admin dashboard for usage stats, popular categories, and community health metrics
- SMS Notifications — Brevo SMS API integration for real-time transaction alerts
- Node.js Official Docs — https://nodejs.org/docs
- Express.js Official Docs — https://expressjs.com
- MongoDB Official Docs — https://www.mongodb.com/docs
- Mongoose Official Docs — https://mongoosejs.com/docs
- React Official Docs — https://react.dev
- Leaflet.js Docs — https://leafletjs.com
- Tailwind CSS Docs — https://tailwindcss.com/docs
- Brevo API Docs — https://developers.brevo.com
- JWT Docs — https://jwt.io
- Vite Docs — https://vite.dev
Harshit Trivedi Ritik Sharma
CivicSwap — Reducing unnecessary consumption, one neighborhood at a time. 🌱