Skip to content

README.md

Latest commit

 

History

History
594 lines (463 loc) · 26.7 KB

README.md

File metadata and controls

594 lines (463 loc) · 26.7 KB

thumbnail

🛒 ShopHub – Fullstack E-commerce Platform

ShopHub is a comprehensive fullstack e-commerce platform built to deliver a seamless online shopping experience. Designed for customers and administrators, ShopHub enables users to browse products, manage shopping carts, place orders, process payments, and track shipments — all from an intuitive web interface.

The platform supports role-based access control, automated inventory management, real-time notifications, and secure payment processing with Midtrans integration. With a powerful admin dashboard, administrators can manage products, categories, orders, users, and monitor sales analytics efficiently. ShopHub aims to provide a complete, scalable e-commerce solution through modern web technologies.

1. Project Overview

ShopHub was developed to create a modern, full-featured e-commerce platform that addresses the complexities of online retail. Traditional e-commerce solutions often lack flexibility in product management, have limited customization options, and offer poor integration capabilities. ShopHub was designed as a comprehensive, scalable solution that unifies product management, order processing, payment handling, and customer relationship management into one cohesive platform.

The platform serves as a complete e-commerce ecosystem for managing products, processing orders, handling payments, and providing excellent customer service — reducing operational complexity while improving user experience and business efficiency.

2. Project Requirements

  • Enable customers to browse and search products with advanced filtering capabilities
  • Support comprehensive shopping cart and wishlist functionality
  • Implement secure checkout process with multiple payment options
  • Handle order management with real-time status tracking
  • Integrate shipping cost calculation and delivery tracking
  • Provide role-based dashboards (customer, admin)
  • Send automated notifications for order updates and promotions

3. The Challenge

The main challenge in developing ShopHub was creating a scalable e-commerce architecture that could handle complex product catalogs, real-time inventory management, secure payment processing, and efficient order fulfillment. The application needed to support multiple user roles, provide responsive product search, handle concurrent transactions, and integrate with external payment and shipping services — all while maintaining optimal performance and user experience.

4. The Approach & Solution

To address these challenges, I built a fullstack web application using Go (Gin) for the backend and React for the frontend. The system features a robust product management system with categorization, advanced search capabilities, and real-time inventory tracking. Users can browse products, add items to cart, apply vouchers, and complete purchases through secure payment processing. The platform includes automated order processing, shipping integration, and comprehensive admin tools for managing the entire e-commerce operation.

5. Key Features

  • JWT Authentication – Secure user authentication with role-based access control

  • Google OAuth Integration – Seamless social login for enhanced user experience

  • Advanced Product Search & Filtering – Comprehensive product discovery with category, price, and rating filters

  • Shopping Cart & Wishlist – Persistent cart management with real-time price calculations

  • Voucher & Discount System – Flexible promotion management with percentage and fixed discounts

  • Secure Payment Processing – Integrated Midtrans payment gateway for multiple payment methods

  • Order Management System – Complete order lifecycle from placement to delivery

  • Shipping Cost Calculator – Real-time shipping cost calculation with multiple courier options

  • Inventory Management – Automated stock tracking and low-stock alerts

  • Review & Rating System – Customer feedback system for products and sellers

  • Admin Dashboard – Comprehensive analytics, sales reports, and system management

  • Real-time Notifications – Automated email and in-app notifications for order updates

  • Automated Cron Jobs – Background tasks for payment processing and system maintenance

6. Tech Stack

6.1 Frontend

  • React 18 with React Router v7
  • TailwindCSS + Radix UI + ShadCN UI
  • React Hook Form + Zod (form validation)
  • Zustand (state management)
  • TanStack React Query (data fetching and caching)
  • Stripe.js (payment processing)
  • Axios (HTTP client)
  • Vite (build tool)

6.2 Backend

  • Golang (Gin Framework)
  • GORM (ORM for MySQL)
  • MySQL (Main database)
  • Redis (Caching & session store)
  • Midtrans (Payment gateway)
  • JWT Auth (Access & Refresh Token)
  • Google OAuth2 (Social authentication)
  • Cloudinary (Image storage)
  • Cron Jobs (Scheduled tasks)

6.3 Deployment

  • VPS Hosting
  • Docker + Docker Compose
  • Nginx (Reverse proxy)
  • GitHub Actions (CI/CD)

7. Project Structure

7.1 Frontend

src/
├── assets/                         # Static files such as images, icons, and fonts
├── components/                     # Reusable global UI components
│   ├── admin/                      # Admin-specific components
│   ├── customer/                   # Customer-specific components
│   ├── form/                       # Form components
│   ├── header/                     # Header and navigation components
│   ├── input/                      # Input field components
│   ├── loading/                    # Loading indicators
│   ├── product-detail/             # Product detail components
│   ├── product-results/            # Product listing components
│   ├── public/                     # Public page components
│   └── ui/                         # Base UI components (shadcn/ui)
├── pages/                          # Page-level modules organized by main features
│   ├── admin/                      # Admin dashboard pages
│   ├── customer/                   # Customer account pages
│   ├── CartPage.jsx                # Shopping cart page
│   ├── Checkout.jsx                # Checkout process page
│   ├── Home.jsx                    # Homepage
│   ├── InvoicePage.jsx             # Order invoice page
│   ├── ProductDetail.jsx           # Product detail page
│   ├── ProductResults.jsx          # Product search results
│   ├── SignIn.jsx                  # User login page
│   └── SignUp.jsx                  # User registration page
├── hooks/                          # Global custom React hooks
│   ├── useAddress.js               # Address management hooks
│   ├── useAuthQuery.js             # Authentication query hooks
│   ├── useCart.js                  # Shopping cart hooks
│   ├── useCategory.js              # Category management hooks
│   ├── useOrder.js                 # Order management hooks
│   ├── usePayment.js               # Payment processing hooks
│   ├── useProduct.js               # Product data hooks
│   └── useVouchers.js              # Voucher management hooks
├── lib/                            # Utility functions and configuration files
│   ├── constant.js                 # Constants used across the app
│   ├── react-query.js              # React Query configuration
│   ├── schema.js                   # Zod schemas for validation
│   └── utils.js                    # General utility functions
├── middleware/                     # Client-side route guards
│   └── index.jsx                   # Protected route middleware
├── services/                       # API service modules to interact with the backend
│   ├── addresses.js                # Address API services
│   ├── auth.js                     # Authentication services
│   ├── banners.js                  # Banner management services
│   ├── cart.js                     # Cart API services
│   ├── categories.js               # Category services
│   ├── dashboard.js                # Dashboard analytics services
│   ├── location.js                 # Location services
│   ├── notification.js             # Notification services
│   ├── orders.js                   # Order management services
│   ├── payment.js                  # Payment processing services
│   ├── product.js                  # Product API services
│   ├── profile.js                  # User profile services
│   ├── reviews.js                  # Review and rating services
│   └── voucher.js                  # Voucher services
├── store/                          # Global state management (Zustand stores)
│   ├── useAuthStore.jsx            # Authentication state
│   ├── useCategoryStore.jsx        # Category state
│   ├── useCheckoutStore.jsx        # Checkout process state
│   ├── useOrderStore.jsx           # Order state
│   ├── useProductStore.jsx         # Product state
│   ├── useQueryStore.jsx           # Query state management
│   ├── useTransactionStore.jsx     # Transaction state
│   └── useUserStore.jsx            # User data state
├── App.jsx                         # Root component defining app layout and routes
├── main.jsx                        # Entry point for rendering the React app
└── index.html                      # HTML template used by Vite

7.2 Backend

server/
├── cmd/                            # Main entry point of the application
│   └── main.go                     # The main file that runs the server
├── internal/
│   ├── config/                     # Configuration and initialization
│   │   ├── cloudinary.go           # Cloudinary image storage config
│   │   └── database.go             # Database connection setup
│   ├── cron/                       # Scheduled background jobs
│   │   └── payment_cron.go         # Payment processing cron jobs
│   ├── dto/                        # Data Transfer Objects
│   │   ├── auth_dto.go             # Authentication DTOs
│   │   ├── order_dto.go            # Order DTOs
│   │   ├── payment_dto.go          # Payment DTOs
│   │   └── product_dto.go          # Product DTOs
│   ├── handlers/                   # HTTP handlers for each feature (Controller layer)
│   │   ├── address_handler.go      # Address management handlers
│   │   ├── admin_handler.go        # Admin dashboard handlers
│   │   ├── auth_handler.go         # Authentication handlers
│   │   ├── banner_handler.go       # Banner management handlers
│   │   ├── cart_handler.go         # Shopping cart handlers
│   │   ├── category_handler.go     # Category management handlers
│   │   ├── location_handler.go     # Location services handlers
│   │   ├── notification_handler.go # Notification handlers
│   │   ├── order_handler.go        # Order management handlers
│   │   ├── payment_handler.go      # Payment processing handlers
│   │   ├── product_handler.go      # Product management handlers
│   │   ├── profile_handler.go      # User profile handlers
│   │   ├── review_handler.go       # Review and rating handlers
│   │   └── voucher_handler.go      # Voucher management handlers
│   ├── middleware/                 # HTTP middleware
│   │   ├── auth.go                 # Authentication middleware
│   │   ├── cors.go                 # CORS configuration
│   │   ├── rate_limiter.go         # Rate limiting
│   │   └── logger.go               # Request logging
│   ├── models/                     # GORM model definitions
│   │   └── models.go               # All database models
│   ├── repositories/               # Data access layer (Repository pattern)
│   │   ├── address_repository.go   # Address data access
│   │   ├── auth_repository.go      # Authentication data access
│   │   ├── banner_repository.go    # Banner data access
│   │   ├── cart_repository.go      # Cart data access
│   │   ├── category_repository.go  # Category data access
│   │   ├── location_repository.go  # Location data access
│   │   ├── notification_repository.go # Notification data access
│   │   ├── order_repository.go     # Order data access
│   │   ├── payment_repository.go   # Payment data access
│   │   ├── product_repository.go   # Product data access
│   │   ├── profile_repository.go   # Profile data access
│   │   ├── review_repository.go    # Review data access
│   │   └── voucher_repository.go   # Voucher data access
│   ├── routes/                     # Route grouping initialization per feature
│   │   ├── address_route.go        # Address routes
│   │   ├── admin_route.go          # Admin routes
│   │   ├── auth_route.go           # Authentication routes
│   │   ├── banner_route.go         # Banner routes
│   │   ├── cart_route.go           # Cart routes
│   │   ├── category_route.go       # Category routes
│   │   ├── location_route.go       # Location routes
│   │   ├── notification_route.go   # Notification routes
│   │   ├── order_route.go          # Order routes
│   │   ├── payment_route.go        # Payment routes
│   │   ├── product_route.go        # Product routes
│   │   ├── profile_route.go        # Profile routes
│   │   ├── review_route.go         # Review routes
│   │   └── voucher_route.go        # Voucher routes
│   ├── seeders/                    # Database seeders for initial data
│   │   └── seeder.go               # Database seeding functions
│   ├── services/                   # Core business logic of the application
│   │   ├── address_service.go      # Address business logic
│   │   ├── auth_service.go         # Authentication business logic
│   │   ├── banner_service.go       # Banner business logic
│   │   ├── cart_service.go         # Cart business logic
│   │   ├── category_service.go     # Category business logic
│   │   ├── location_service.go     # Location business logic
│   │   ├── notification_service.go # Notification business logic
│   │   ├── order_service.go        # Order business logic
│   │   ├── payment_service.go      # Payment business logic
│   │   ├── product_service.go      # Product business logic
│   │   ├── profile_service.go      # Profile business logic
│   │   ├── review_service.go       # Review business logic
│   │   └── voucher_service.go      # Voucher business logic
│   └── utils/                      # Common utility functions
│       ├── cloudinary.go           # Image upload utilities
│       ├── email.go                # Email sending utilities
│       ├── jwt.go                  # JWT token utilities
│       └── response.go             # Response formatting utilities
├── go.mod                          # Go module dependency configuration
├── go.sum                          # Go module checksum file
├── Dockerfile                      # Docker build instructions
├── docker-compose.yml              # Multi-container setup for local development
├── deploy.sh                       # Script for automated deployment
└── credentials.json                # Service account credentials (gitignored)

8. Authentication & Authorization

  • JWT Authentication – Secure token-based authentication with access and refresh tokens
  • Google OAuth Integration – Social login for enhanced user experience and onboarding
  • Role-Based Access Control – Protects routes based on user roles (customer, admin) with middleware
  • API Key Gateway – Secures specific endpoints with API key validation for webhook and external access
  • Session Management – Redis-based session storage for scalable user session handling

9. API Features & Endpoints

9.1 Authentication

Method Endpoint Description
POST /api/auth/login User login
POST /api/auth/logout User logout
POST /api/auth/register User registration
POST /api/auth/send-otp Send OTP for verification
POST /api/auth/verify-otp Verify OTP
POST /api/auth/refresh-token Refresh access token
GET /api/auth/google Google OAuth login
GET /api/auth/google/callback Google OAuth callback
GET /api/auth/me Get current user profile

9.2 Product Management

Method Endpoint Description
GET /api/product Search and filter products
GET /api/product/:slug Get product detail by slug
POST /api/product Create new product (admin)
PUT /api/product/:id Update product (admin)
DELETE /api/product/:id Delete product (admin)

9.3 Category Management

Method Endpoint Description
GET /api/categories Get all categories
GET /api/categories/:id Get category detail
POST /api/categories Create category (admin)
PUT /api/categories/:id Update category (admin)
DELETE /api/categories/:id Delete category (admin)

9.4 Shopping Cart

Method Endpoint Description
GET /api/cart Get user cart items
POST /api/cart Add item to cart
PUT /api/cart/:id Update cart item quantity
DELETE /api/cart/:id Remove item from cart
DELETE /api/cart Clear entire cart

9.5 Order Management

Method Endpoint Description
POST /api/orders Create new order (checkout)
GET /api/orders Get user orders
GET /api/orders/:orderID Get order detail
POST /api/orders/check-shipping Calculate shipping cost
POST /api/orders/:orderID/shipment Create shipment info (admin)
PUT /api/orders/:orderID/shipment Update shipment status (admin)
GET /api/orders/:orderID/shipment Get shipment info

9.6 Payment Processing

Method Endpoint Description
GET /api/payments Get user payment history
POST /api/payments/notifications Payment webhook (Midtrans)

9.7 User Profile & Address

Method Endpoint Description
GET /api/profile Get user profile
PUT /api/profile Update user profile
PUT /api/profile/avatar Update user avatar
GET /api/addresses Get user addresses
POST /api/addresses Add new address
PUT /api/addresses/:id Update address
DELETE /api/addresses/:id Delete address

9.8 Reviews & Ratings

Method Endpoint Description
GET /api/reviews/:productID Get product reviews
POST /api/reviews Submit product review
PUT /api/reviews/:id Update review
DELETE /api/reviews/:id Delete review

9.9 Vouchers & Discounts

Method Endpoint Description
GET /api/vouchers Get available vouchers
POST /api/vouchers/apply Apply voucher to order
POST /api/vouchers Create voucher (admin)
PUT /api/vouchers/:id Update voucher (admin)
DELETE /api/vouchers/:id Delete voucher (admin)

9.10 Banner Management

Method Endpoint Description
GET /api/banners Get all banners
POST /api/banners Create banner (admin)
PUT /api/banners/:id Update banner (admin)
DELETE /api/banners/:id Delete banner (admin)

9.11 Location Services

Method Endpoint Description
GET /api/locations/provinces Get all provinces
GET /api/locations/cities/:id Get cities by province
GET /api/locations/districts/:id Get districts by city
GET /api/locations/subdistricts/:id Get subdistricts by district
GET /api/locations/postal-codes/:id Get postal codes by subdistrict

9.12 Notifications

Method Endpoint Description
GET /api/notifications Get user notifications
PUT /api/notifications/read Mark notifications as read
POST /api/notifications/broadcast Send broadcast (admin)

9.13 Admin Dashboard

Method Endpoint Description
GET /api/admin/dashboard Get dashboard analytics
GET /api/admin/users Get all users
GET /api/admin/orders Get all orders
GET /api/admin/sales Get sales statistics

10. Configuration

10.1 Environment Variables for Frontend

VITE_API_SERVICES=https://your-api-domain.com/api
VITE_API_KEY=your-api-key
VITE_GOOGLE_CLIENT_ID=your-google-client-id

10.2 Environment Variables for Backend

# ==== MySQL Database ====
DB_HOST=your-database-host               # e.g. localhost or db
DB_PORT=3306
DB_USERNAME=your-database-username       # e.g. root
DB_NAME=your-database-name               # e.g. ecommerce_db
DB_PASSWORD=your-database-password

# ==== Cloudinary (Image Storage) ====
CLOUDINARY_CLOUD_NAME=your-cloudinary-cloud-name
CLOUDINARY_API_KEY=your-cloudinary-api-key
CLOUDINARY_API_SECRET=your-cloudinary-api-secret
CLOUDINARY_FOLDER_NAME=your-cloudinary-folder-name

# ==== Email Service ====
USER_EMAIL=your-email-address
USER_PASSWORD=your-email-app-password    # e.g. App Password from Gmail

# ==== Redis ====
REDIS_ADDR=your-redis-host:6379          # e.g. redis:6379 or localhost:6379
REDIS_PASSWORD=your-redis-password       # leave blank if not used

# ==== Application Config ====
PORT=5002
API_KEY=your-api-key
JWT_ACCESS_SECRET=your-jwt-access-secret
JWT_REFRESH_SECRET=your-jwt-refresh-secret
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret

# ==== Midtrans Payment ====
MIDTRANS_SERVER_KEY=your-midtrans-server-key
MIDTRANS_CLIENT_KEY=your-midtrans-client-key
MIDTRANS_ENVIRONMENT=sandbox             # or production

# ==== Shipping API ====
RAJAONGKIR_API_KEY=your-rajaongkir-api-key

# ==== Deployment (Optional) ====
# TRUSTED_PROXIES=your-vps-ip
# FRONTEND_REDIRECT_URL=https://yourdomain.com
# GOOGLE_REDIRECT_URL=https://your-api.yourdomain.com/api/auth/google/callback

11. Deployment

For this project, the backend is deployed on a VPS using Docker and Nginx, while the frontend can be deployed on various platforms like Vercel, Netlify, or traditional web hosting.

11.1 Backend Deployment (VPS)

  1. Provision a VPS (e.g., Ubuntu-based)

  2. Install Docker and Docker Compose

  3. Clone the repository into your VPS

  4. Configure .env file with your production credentials

  5. Run the app with Docker Compose:

docker-compose up -d --build

  1. Configure Nginx as reverse proxy and set up SSL with Certbot

  2. Access your API via custom domain (e.g., https://api.yourdomain.com)

11.2 Frontend Deployment

Option 1: Vercel/Netlify (Recommended)

  1. Connect your Git repository

  2. Add environment variables to the hosting dashboard

  3. Set build command:

npm run build
  1. Set output directory: dist

Option 2: Traditional Web Hosting

  1. Build the project locally:
npm run build

  1. Upload the dist folder to your web hosting provider

  2. Configure environment variables through hosting control panel

12. Local Development Setup

12.1 Prerequisites

  • Node.js (v18 or higher)
  • Go (v1.19 or higher)
  • MySQL (v8.0 or higher)
  • Redis (optional, for caching)

12.2 Frontend Setup

cd client
npm install
cp .env.example .env
# Configure environment variables
npm run dev

12.3 Backend Setup

cd server
go mod download
cp .env.example .env
# Configure environment variables
go run cmd/main.go

12.4 Database Setup

  1. Create MySQL database
  2. Update database credentials in .env
  3. Run the application - it will auto-migrate tables and seed initial data

13. Contributing

Contributions are welcome! If you'd like to improve or extend this project:

  1. Fork this repository

  2. Create a new branch:

git checkout -b feature/your-feature-name
  1. Commit your changes:
git commit -m "feat: add new feature"
  1. Push to your branch:
git push origin feature/your-feature-name
  1. Open a Pull Request

📄 License

This project is licensed under the MIT License. Feel free to use, modify, and distribute it for personal or commercial purposes.

MIT License

About Me