From Earth to You - Connecting authentic, farm-fresh products from trusted producers directly to consumers.

1. Overview
2. Features
3. System Requirements
4. Quick Start Installation
5. Detailed Configuration
6. Project Structure
7. Database Schema
8. API Documentation
9. User Roles & Permissions
10. Payment Integration
11. Deployment Guide
12. Testing
13. Troubleshooting
14. Contributing
15. License

EthniCart is a modern, full-featured e-commerce platform built with Laravel that connects local producers with consumers. The platform emphasizes authenticity, quality, and direct-from-source products including organic foods, traditional crafts, beauty products, and more.

• 🏪 Multi-vendor marketplace for producers/sellers
• 💳 Secure payment processing with SSL Commerce
• 🔐 Google OAuth integration for seamless authentication
• 📱 Fully responsive design optimized for all devices
• 🔍 Real-time search with autocomplete suggestions
• 📊 Comprehensive analytics for sellers and admins
• 🛒 Advanced cart management with session persistence
• ⭐ Product reviews and rating system

• Backend: Laravel 10.x (PHP 8.1+)
• Frontend: Blade Templates, Tailwind CSS, Alpine.js
• Database: MySQL 8.0+ / MariaDB
• Authentication: Laravel Sanctum + Google OAuth (Socialite)
• Payment Gateway: SSL Commerce (Bangladesh)
• Storage: Local / S3 Compatible
• Build Tools: Vite
• Image Processing: Intervention Image

• ✅ User registration and login (Email/Google OAuth)
• ✅ Browse products by 12+ categories
• ✅ Advanced search with live autocomplete
• ✅ Shopping cart with real-time updates
• ✅ Secure checkout with multiple payment methods
• ✅ Order tracking and history
• ✅ User profile management
• ✅ Wishlist functionality
• ✅ Product reviews and ratings
• ✅ Email notifications

• ✅ Seller registration and verification
• ✅ Shop profile customization
• ✅ Product management (CRUD)
• ✅ Inventory tracking
• ✅ Order management dashboard
• ✅ Sales analytics and reports
• ✅ Order fulfillment workflow
• ✅ Revenue tracking
• ✅ Customer management

• ✅ Complete platform oversight
• ✅ User and seller approval/management
• ✅ Product moderation
• ✅ Category management
• ✅ Order monitoring
• ✅ Analytics dashboard
• ✅ System configuration
• ✅ Content management

1. 🍎 Farm Fresh Fruits & Vegetables
2. 🐟 Fish & Meat
3. 🌶️ Homemade Masala & Spices
4. 🥒 Pickles & Condiments
5. 🌿 Organic Roots
6. 💄 Beauty & Personal Care
7. 👗 Traditional Clothing & Apparels
8. 🎨 Handcrafted Goods
9. 🏠 Home & Kitchen Items
10. 💐 Flowers & Gifts
11. 🧼 Eco-Friendly Cleaning Products

✓ PHP >= 8.1
✓ MySQL >= 8.0 or MariaDB >= 10.3
✓ Composer >= 2.0
✓ Node.js >= 16.x
✓ NPM >= 8.x
✓ 2GB RAM
✓ 10GB Storage

✓ OpenSSL, PDO, Mbstring, Tokenizer, XML
✓ Ctype, JSON, BCMath, Fileinfo
✓ GD (for image processing)

# 1. Clone the repository
git clone https://github.com/mehedi-hridoy/EthniCart.git
cd EthniCart

# 2. Install PHP dependencies
composer install

# 3. Install Node.js dependencies
npm install

# 4. Create environment file
cp .env.example .env

# 5. Generate application key
php artisan key:generate

# 6. Configure database (Edit .env file)
DB_DATABASE=ethnicart_db
DB_USERNAME=root
DB_PASSWORD=your_password

# 7. Run migrations
php artisan migrate

# 8. Seed database (optional)
php artisan db:seed

# 9. Create storage symlink
php artisan storage:link

# 10. Build frontend assets
npm run dev

# 11. Start development server
php artisan serve

Visit: http://127.0.0.1:8000

# 1. Clone and navigate
git clone https://github.com/mehedi-hridoy/EthniCart.git
cd EthniCart

# 2. Start XAMPP (Apache + MySQL)

# 3. Install dependencies
composer update
npm install

# 4. Setup environment
cp .env.example .env
php artisan key:generate

# 5. Configure database in .env
# DB_DATABASE=ethnicart_db
# DB_USERNAME=root
# DB_PASSWORD=

# 6. Run migrations
php artisan migrate
php artisan storage:link

# 7. Build assets
npm run dev

# 8. Start server
php artisan serve

Create your database first:

CREATE DATABASE ethnicart_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

Update .env:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=ethnicart_db
DB_USERNAME=root
DB_PASSWORD=

Add to .env:

ADMIN_EMAIL=admin@ethnicart.com
ADMIN_PASSWORD=SecurePassword123!

Create admin user:

# Method 1: Using Seeder
php artisan db:seed --class=AdminUserSeeder

# Method 2: Using Tinker
php artisan tinker
>>> use App\Models\User; use Illuminate\Support\Facades\Hash;
>>> User::create(['name' => 'Admin', 'email' => 'admin@ethnicart.com', 'password' => Hash::make('SecurePassword123!'), 'email_verified_at' => now(), 'role' => 'admin']);
>>> exit

1. Create project at Google Cloud Console
2. Enable Google+ API
3. Create OAuth 2.0 credentials
4. Add redirect URI: http://localhost:8000/auth/google/callback
5. Update .env:

GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret
GOOGLE_REDIRECT_URI=http://localhost:8000/auth/google/callback

📖 Detailed OAuth Guide: See GOOGLE_AUTH_SETUP.md

SSLCOMMERZ_STORE_ID=your_store_id
SSLCOMMERZ_STORE_PASSWORD=your_password
SSLCOMMERZ_SANDBOX=true

MAIL_MAILER=smtp
MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
MAIL_USERNAME=your-email@gmail.com
MAIL_PASSWORD=your-app-password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=noreply@ethnicart.com
MAIL_FROM_NAME="EthniCart"

EthniCart/
├── app/
│   ├── Console/Commands/      # Custom Artisan commands
│   ├── Exceptions/            # Exception handling
│   ├── Helpers/               # Helper functions
│   ├── Http/
│   │   ├── Controllers/       # Application controllers
│   │   │   ├── Admin/         # Admin panel controllers
│   │   │   ├── Auth/          # Authentication
│   │   │   ├── Seller/        # Seller dashboard
│   │   │   └── ...            # Customer controllers
│   │   └── Middleware/        # Custom middleware
│   ├── Library/SslCommerz/    # Payment integration
│   ├── Models/                # Eloquent models
│   └── Services/              # Business logic services
│
├── database/
│   ├── migrations/            # Database migrations
│   └── seeders/               # Data seeders
│
├── public/
│   ├── assets/                # Compiled assets
│   ├── images/                # Static images
│   └── storage/               # Uploaded files (symlink)
│
├── resources/
│   ├── views/                 # Blade templates
│   │   ├── admin/             # Admin views
│   │   ├── seller/            # Seller views
│   │   ├── auth/              # Auth pages
│   │   └── ...                # Customer views
│   └── lang/                  # Language files
│
├── routes/
│   ├── web.php                # Web routes
│   ├── api.php                # API routes
│   └── console.php            # Console commands
│
├── storage/
│   ├── app/public/            # User uploads
│   └── logs/                  # Application logs
│
├── tests/                     # Automated tests
├── .env.example               # Environment template
├── composer.json              # PHP dependencies
├── package.json               # Node dependencies
└── README.md                  # This file

User ──┬── (1:n) Orders
       ├── (1:1) Seller Profile
       └── (1:n) Cart Items

Seller ──┬── (1:n) Products
         └── (1:n) Orders

Product ──┬── (n:1) Category
          ├── (n:1) Seller
          ├── (1:n) Product Images
          └── (n:n) Order Items

Order ──┬── (n:1) User
        ├── (n:1) Seller
        └── (1:n) Order Items

Category ──── (1:n) Sub-Categories (self-referencing)

users: User accounts (customers, sellers, admins)
sellers: Seller profiles and shop information
products: Product catalog
categories: Product categories hierarchy
ethni_orders: Order records
order_items: Order line items
product_images: Product image gallery
seller_order_stats: Seller statistics

Login

POST /api/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "password"
}

Response: 200 OK
{
  "token": "1|abc123...",
  "user": { ... }
}

Register

POST /api/register
Content-Type: application/json

{
  "name": "John Doe",
  "email": "user@example.com",
  "password": "password",
  "password_confirmation": "password"
}

Get Products

GET /api/products?page=1&category=foods&sort=price_asc

Response: 200 OK
{
  "data": [ ... ],
  "meta": {
    "current_page": 1,
    "total": 150
  }
}

Search Products

GET /api/search-suggestions?query=tomato

Response: 200 OK
{
  "products": [ ... ]
}

Product Details

GET /api/products/{id}

Response: 200 OK
{
  "id": 1,
  "name": "Organic Tomatoes",
  "price": 50.00,
  "stock": 100,
  ...
}

Add to Cart

POST /api/cart/add/{product_id}
Authorization: Bearer {token}

Response: 200 OK
{
  "success": true,
  "cart_count": 3
}

Get Cart

GET /api/cart
Authorization: Bearer {token}

Response: 200 OK
{
  "items": [ ... ],
  "total": 550.00
}

• Browse and search products
• Manage cart and place orders
• Track order status
• Write product reviews
• Manage profile and wishlist

• All customer permissions
• Create and manage products
• Process orders
• View sales analytics
• Manage shop profile
• Handle inventory

• All seller permissions
• Manage users and sellers
• Approve/reject registrations
• Moderate products
• System configuration
• Platform analytics

// Customer routes
Route::middleware(['auth'])->group(function () {
    // Customer-only routes
});

// Seller routes
Route::middleware(['auth', 'seller'])->prefix('seller')->group(function () {
    // Seller dashboard and management
});

// Admin routes
Route::middleware(['auth', 'admin'])->prefix('admin')->group(function () {
    // Admin panel
});

1. Register at SSL Commerce
2. Get Store ID and Password
3. Configure in .env:

SSLCOMMERZ_STORE_ID=test123
SSLCOMMERZ_STORE_PASSWORD=test123
SSLCOMMERZ_SANDBOX=true  # false for production

1. Customer places order → Order created (status: pending)
2. Redirect to SSL Commerce payment page
3. Customer completes payment
4. Callback to /payment/success or /payment/fail
5. Order status updated
6. Confirmation email sent

• Credit/Debit Cards (Visa, MasterCard, Amex)
• Mobile Banking (bKash, Nagad, Rocket)
• Internet Banking
• Digital Wallets

# 1. Environment
APP_ENV=production
APP_DEBUG=false
APP_URL=https://yourdomain.com

# 2. Database backup strategy
# 3. SSL certificate (HTTPS)
# 4. File permissions
chmod -R 775 storage bootstrap/cache

# 5. Optimize
php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan optimize

# 6. Queue workers (optional)
php artisan queue:work --daemon

# 7. Monitoring & logging

Apache (.htaccess)

<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteRule ^(.*)$ public/$1 [L]
</IfModule>

Nginx

location / {
    try_files $uri $uri/ /index.php?$query_string;
}

• Connect your server
• Configure environment variables
• Set deployment script
• Auto-deploy on push

# Run all tests
php artisan test

# With coverage
php artisan test --coverage

# Specific suite
php artisan test --testsuite=Feature

# Specific test
php artisan test tests/Feature/ProductTest.php

// tests/Feature/ProductTest.php
public function test_user_can_view_products()
{
    $response = $this->get('/products');
    
    $response->assertStatus(200)
             ->assertViewIs('products.index')
             ->assertSee('Products');
}

1. Blank Page / 500 Error

# Check logs
tail -f storage/logs/laravel.log

# Clear all caches
php artisan optimize:clear

2. Permission Errors

chmod -R 775 storage bootstrap/cache
chown -R www-data:www-data storage bootstrap/cache

3. Database Connection Failed

# Test connection
php artisan tinker
>>> DB::connection()->getPdo();

# Verify .env database credentials

4. Assets Not Loading

# Rebuild assets
npm run build

# Check public directory permissions

5. Google OAuth Not Working

• Verify redirect URI matches exactly
• Check Google Console credentials
• Clear config: php artisan config:clear

6. Images Not Uploading

# Recreate storage link
php artisan storage:link

# Check storage permissions
chmod -R 775 storage/app/public

# Development only!
APP_DEBUG=true
LOG_LEVEL=debug

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create feature branch (git checkout -b feature/AmazingFeature)
3. Commit changes (git commit -m 'Add AmazingFeature')
4. Push to branch (git push origin feature/AmazingFeature)
5. Open Pull Request

• Follow PSR-12
• Write meaningful commits
• Add tests for new features
• Update documentation

Reporting Vulnerabilities: Email mehedi.hridoy101@gmail.com

Best Practices:

• Keep dependencies updated
• Use HTTPS in production
• Implement rate limiting
• Sanitize all inputs
• Regular security audits

• Enable caching (Redis recommended for production)
• Optimize images (WebP format)
• Use CDN for static assets
• Implement lazy loading
• Add database indexes
• Use eager loading to prevent N+1 queries

• Laravel Docs
• Tailwind CSS
• SSL Commerce API

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: mehedi.hridoy101@gmail.com

• Mehedi Hasan Hridoy - GitHub
• Umme Salma Lamyea - GitHub

This project is licensed under the MIT License - see LICENSE file for details.

• Laravel Framework Team
• Tailwind CSS Team
• Open Source Community
• All Contributors

• ✨ Initial release
• 🏪 Multi-vendor marketplace
• 🔐 Google OAuth integration
• 💳 SSL Commerce payment
• 📱 Responsive design
• 📊 Analytics dashboard
• 🛒 Cart system
• ⭐ Review system

Made with ❤️ for local producers and authentic products

Last Updated: November 2, 2025