- Overview
- Key Features
- Architecture
- Tech Stack
- Project Structure
- Quick Start
- Configuration
- Authentication Flow
- API Documentation
- Security
- Performance
- Contributing
- Support
EarnEasy is a modern e-commerce marketplace platform designed for scalability, security, and exceptional user experience. Built with modern web technologies, it provides a foundation for online marketplace management with Google OAuth authentication, JWT session management, and clean architecture.
To provide a robust, scalable, and secure marketplace platform that empowers businesses to create exceptional e-commerce experiences while maintaining the highest standards of security and performance.
- 🛡️ Google OAuth 2.0 Integration - Secure social login with Google
- 🍪 HTTP-Only Cookie Authentication - JWT tokens stored in secure HTTP-only cookies for XSS protection
- � Token Blacklisting - Secure logout with server-side token invalidation
- 🔒 Dual Authentication Support - Both cookie and header-based authentication for flexibility
- 🛡️ Security Headers - CORS protection with production-ready cookie settings
- 🔐 Data Encryption - Secure data transmission and storage
- 📊 Session Management - Centralized authentication handling with AuthContext
- 🏪 Multi-vendor Marketplace - Foundation for multiple sellers (structure ready)
- 📦 Product Management - Complete CRUD operations for products
- 🔍 Advanced Search & Filtering - Basic search with category filtering
- 📱 Mobile-First Design - Responsive UI for all device types
- 🛒 Shopping Cart - Persistent cart functionality
- 📊 User Profiles - Comprehensive user management
- 🎨 Modern UI/UX - Material-UI components with custom theming
- ⚡ Hot Module Replacement - Vite for instant development feedback
- 🧩 Modular Architecture - Clean separation of concerns
- 📦 RESTful API Design - OpenAPI-ready endpoints
- 🔄 CI/CD Ready - GitHub Actions configuration ready
- 🧪 Testing Framework - Test structure ready for implementation
- 📝 Code Quality - ESLint and Prettier configuration
┌────────────────────┐ ┌────────────────────┐ ┌────────────────────┐
│ Frontend │ │ Backend │ │ Database │
│ (React SPA) │◄──►│ (Node.js API) │◄──►│ (MongoDB) │
└────────────────────┘ └────────────────────┘ └────────────────────┘
│ │ │
│ │ │
┌──────────────┐ ┌─────────────┐ ┌──────────────┐
│ Material UI │ │ Express │ │ Mongoose │
│ (UI) │ │ Middleware │ │ ODM │
└──────────────┘ └─────────────┘ └──────────────┘
- Frontend: React 18 + Vite + Material-UI
- Backend: Node.js + Express.js + Mongoose
- Database: MongoDB
- Authentication: HTTP-Only Cookies + JWT + Google OAuth 2.0
- Development: Hot reloading, ESM modules, modern JS/ES6+
| Category | Technology | Purpose |
|---|---|---|
| Frontend | React 18 | UI library with hooks and modern features |
| Build Tool | Vite | Fast development server and build tool |
| UI Framework | Material-UI (MUI) | Professional component library |
| Routing | React Router | Client-side routing |
| HTTP Client | Axios | API communication |
| State Management | React Context | Global state management |
| Backend | Node.js + Express | Server runtime and web framework |
| Database | MongoDB + Mongoose | NoSQL database with ODM |
| Authentication | HTTP-Only Cookies + JWT + Google OAuth | Secure authentication with XSS protection |
| Security | CORS + JWT | Security headers and token validation |
| Development | ESLint + Prettier | Code quality and formatting |
EarnEasy/
├── 📁 backend/
│ ├── 📁 controllers/ # Route handlers and business logic
│ │ ├── authController.js # Authentication logic
│ │ └── productController.js # Product management
│ ├── 📁 middleware/ # Custom middleware
│ │ └── authMiddleware.js # JWT and session management
│ ├── 📁 models/ # Database models
│ │ ├── authModel.js # User authentication model
│ │ ├── Products.js # Product data model
│ │ └── dbConnections.js # Database connection
│ ├── 📁 routes/ # API route definitions
│ │ ├── authRouter.js # Authentication routes (consolidated)
│ │ ├── productRoutes.js # Product API routes
│ │ └── profileRoutes.js # User profile routes
│ ├── 📁 utils/ # Utility functions
│ │ └── googleClient.js # Google OAuth configuration
│ ├── index.js # Server entry point
│ ├── package.json # Backend dependencies
│ ├── seeder.js # Database seeding script
│ └── .env # Environment variables
│
├── 📁 frontend/
│ ├── 📁 src/
│ │ ├── 📁 components/ # Reusable UI components
│ │ │ ├── BottomNavBar.jsx
│ │ │ ├── CategoriesBar.jsx
│ │ │ ├── GoogleLogin.jsx
│ │ │ ├── ProductCard.jsx
│ │ │ └── SessionInfo.jsx
│ │ ├── 📁 pages/ # Page components
│ │ │ ├── LandingPage.jsx
│ │ │ ├── HomePage.jsx
│ │ │ ├── ExplorePage.jsx
│ │ │ ├── CartPage.jsx
│ │ │ ├── AddPage.jsx
│ │ │ └── ProfilePage.jsx
│ │ ├── 📁 context/ # React context providers
│ │ │ └── AuthContext.jsx # Authentication context (was SessionContext)
│ │ ├── 📁 utils/ # Frontend utilities
│ │ │ ├── PrivateRoute.jsx
│ │ │ └── RefreshHandler.jsx
│ │ ├── 📁 api/ # API service layer
│ │ │ └── apiFetch.js
│ │ ├── App.jsx # Main application component
│ │ ├── main.jsx # Application entry point
│ │ └── index.css # Global styles
│ ├── 📁 public/ # Static assets
│ │ ├── 📁 images/ # Product and UI images
│ │ └── vite.svg
│ ├── package.json # Frontend dependencies
│ ├── vite.config.js # Vite configuration
│ └── eslint.config.js # ESLint configuration
│
├── README.md # Project documentation
└── .gitignore # Git ignore rules
- Node.js (v16.0.0 or higher)
- MongoDB (v4.4 or higher)
- Google OAuth Credentials (Client ID & Secret)
- Git for version control
-
Clone the Repository
git clone https://github.com/so-sc/EarnEasy.git cd EarnEasy -
Backend Setup
cd backend npm install -
Frontend Setup
cd ../frontend npm install -
Environment Configuration Create
.envfiles as described in the Configuration section. -
Database Setup
# Start MongoDB service mongod # Seed database (optional) cd backend node seeder.js
-
Start Development Servers
# Backend (Terminal 1) cd backend npm start # Server runs on http://localhost:3000 # Frontend (Terminal 2) cd frontend npm run dev # App runs on http://localhost:5173
# Server Configuration
PORT=3000
NODE_ENV=development
# Database
MONGODB_URI=mongodb://localhost:27017/earneasy
# JWT Configuration
JWT_SECRET=your_super_secret_jwt_key_minimum_32_characters
JWT_ACCESS_EXPIRE=7d
# Google OAuth
GOOGLE_CLIENT_ID=your_google_client_id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your_google_client_secret
# Frontend URL
FRONTEND_URL=http://localhost:5173
# Security (Optional)
CORS_ORIGIN=http://localhost:5173# API Configuration
VITE_API_BASE_URL=http://localhost:3000
# Google OAuth
VITE_GOOGLE_CLIENT_ID=your_google_client_id.apps.googleusercontent.com
# Environment
VITE_NODE_ENV=development- Go to Google Cloud Console
- Create a new project or select existing
- Enable Google+ API
- Create OAuth 2.0 credentials
- Add authorized origins and redirect URIs
sequenceDiagram
participant User
participant Frontend
participant Backend
participant Google
participant Database
User->>Frontend: Click "Sign in with Google"
Frontend->>Google: Redirect to Google OAuth
Google->>User: Show consent screen
User->>Google: Grant permissions
Google->>Backend: Send authorization code
Backend->>Google: Exchange code for tokens
Google->>Backend: Return user info & tokens
Backend->>Database: Find or create user
Database->>Backend: Return user data
Backend->>Frontend: Set HTTP-only cookie + return user info
Frontend->>User: Redirect to dashboard
- Token Storage: JWT tokens stored in secure HTTP-only cookies
- XSS Protection: Cookies cannot be accessed by client-side JavaScript
- Automatic Handling: Browser automatically sends cookies with requests
- Token Blacklisting: Server-side token invalidation on logout
- Dual Support: Both cookie and header authentication for API flexibility
POST /auth # Google OAuth callback
GET /session/validate # Validate current session
POST /session/logout # Logout userGET /products # Get all products
POST /products # Create new product (auth required)
GET /products/:id # Get product by ID
PUT /products/:id # Update product (auth required)
DELETE /products/:id # Delete product (admin only)GET /users/profile # Get current user profile
PUT /users/profile # Update user profile
GET /users/sessions # Get active sessions{
"success": true,
"message": "Operation successful",
"data": {
// Response data
}
}- JWT Tokens: Stateless authentication with 7-day expiry
- Google OAuth: Secure third-party authentication
- Session Management: JWT-based session tracking
- CORS Protection: Configured for specific origins
- Input Validation: Basic server-side validation
- Security Headers: CORS (ready for additional headers)
- Error Handling: Secure error messages without sensitive data
- Environment Variables: Sensitive data in
.envfiles - Database Security: MongoDB connection string encryption
- API Rate Limiting: (Ready for implementation)
- Audit Logging: (Ready for implementation)
- Frontend: Code splitting, lazy loading, image optimization
- Backend: Database indexing, query optimization, caching
- Database: Proper indexing, aggregation pipelines
- Security: Efficient JWT validation, session management
- Performance Metrics: Response times, error rates
- User Analytics: Session tracking, user behavior
- Server Monitoring: CPU, memory, database performance
- Error Tracking: Centralized error logging and alerts
- Fork the repository
- Create a feature branch (
git checkout -b feature/AmazingFeature) - Commit your changes (
git commit -m 'Add some AmazingFeature') - Push to the branch (
git push origin feature/AmazingFeature) - Open a Pull Request
- ESLint: JavaScript linting and code quality
- Prettier: Code formatting consistency
- Commit Messages: Conventional commit format
- Documentation: Update README and code comments
- Code Review: All PRs require review
- Testing: Automated tests must pass
- Security: Security review for sensitive changes
- Performance: Performance impact assessment
- Documentation: This README and inline code comments
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Contributors: Thank you to all contributors who have helped make this project better
- Feedback: We welcome feedback and suggestions for improvement
- Bug Reports: Please report bugs with detailed reproduction steps
Made with ❤️ by the EarnEasy Team