Welcome to the Retrade client applications repository! This monorepo contains all frontend applications for the Retrade e-commerce platform, built with modern web technologies and designed for scalability and performance.

• 🛒 Retrade Client Applications
  • 📋 Table of Contents
  • 🏗️ Architecture Overview
  • 🚀 Applications
  • 🛠️ Tech Stack
  • 📦 Project Structure
  • ⚡ Quick Start
    • Prerequisites
    • Installation
    • Development
    • Production Build
  • 🐳 Docker Deployment
    • Local Development
    • Production Deployment
  • 🔧 Configuration
  • 📚 Development Guidelines
  • 🧪 Testing & Quality
  • 📈 Performance
  • 🔒 Security
  • 🚀 CI/CD Pipeline
  • 🤝 Contributing
  • 📄 License

Retrade is a comprehensive e-commerce platform built with a microservices architecture. This repository contains three specialized frontend applications that interact with backend services through RESTful APIs, real-time WebSocket connections, and STOMP messaging.

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Customer App  │    │   Seller App    │    │   Admin App     │
│   (Next.js 15)  │    │   (Next.js 15)  │    │   (Next.js 15)  │
│   Port: 3001    │    │   Port: 3002    │    │   Port: 3000    │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 │
                    ┌─────────────────┐
                    │  Backend APIs   │
                    │  (Microservices)│
                    │  + WebSocket    │
                    │  + STOMP        │
                    └─────────────────┘

• Port: 3001 (development)
• Purpose: Main e-commerce storefront for customers
• Key Features:
  • 🛒 Product browsing and search
  • 🛍️ Shopping cart with real-time updates
  • 💳 Secure checkout and payment processing
  • 👤 User account management and profiles
  • 📦 Order tracking and history
  • 💬 Real-time chat with sellers
  • 📱 Responsive mobile-first design
  • 🔔 Real-time notifications
  • 💰 Digital wallet integration
  • ⭐ Product reviews and ratings
  • 📍 Address management
  • 🎯 Personalized recommendations

• Port: 3002 (development)
• Purpose: Comprehensive seller management portal
• Key Features:
  • 📊 Advanced analytics and reporting
  • 📦 Product catalog management
  • 📋 Order processing and fulfillment
  • 💰 Revenue tracking and financial reports
  • 📈 Sales performance metrics
  • 💬 Customer communication tools
  • 🚚 Shipping and logistics management
  • 🎫 Voucher and promotion management
  • 📱 Mobile-responsive interface
  • 🔔 Real-time order notifications
  • 👥 Customer relationship management
  • 📊 Interactive charts and dashboards

• Port: 3000 (development)
• Purpose: Platform administration and management
• Key Features:
  • 👥 User and seller management
  • 🏢 Brand and category administration
  • 📊 Platform-wide analytics
  • 💰 Financial oversight and platform fees
  • 🚨 Alert and monitoring systems
  • 📋 Report management
  • ⚙️ System configuration
  • 🔒 Security and access control
  • 📈 Revenue and growth tracking
  • 🎫 Voucher system management
  • 💸 Withdrawal request processing

• Framework: Next.js 15 with App Router & Turbopack
• Language: TypeScript 5.5+ (Strict mode)
• Styling: Tailwind CSS 4.1+ with DaisyUI
• Build Tool: Turbo 2.5+ (Monorepo management)
• Package Manager: Yarn 1.22+ with Workspaces
• Runtime: Node.js 18+

• Component Library: Radix UI (Accessible primitives)
• Icons: Lucide React, Heroicons, Tabler Icons
• Charts: Recharts 3.1+ (Admin), Recharts 2.15+ (Seller)
• Animations: Framer Motion 12+
• Notifications: Sonner
• Styling Utils: clsx, tailwind-merge

• HTTP Client: Axios 1.7+ with custom interceptors
• State Management:
  • React Context API (Customer, Seller)
  • Redux Toolkit 2.5+ (Admin)
• Real-time Communication:
  • STOMP.js 7.1+ over WebSocket
  • Socket.io Client 4.8+ (Utility package)
• Form Handling: Custom hooks with Joi validation

• Linting: ESLint 9+ with Next.js config
• Formatting: Prettier 3.5+ with plugins
• Git Hooks: Husky 9.1+
• Type Checking: TypeScript strict mode with custom configs
• Device Fingerprinting: FingerprintJS 4.6+

• File Processing: XLSX (Admin)
• Markdown: React Markdown with GFM
• Date Handling: date-fns 4.1+ (Customer)
• Color Processing: ColorThief 2.6+ (Customer)
• WebRTC: Custom WebRTC configuration for video calls

retrade-client/
├── apps/
│   ├── customer/              # Customer-facing e-commerce app
│   │   ├── app/              # Next.js App Router pages
│   │   ├── components/       # React components
│   │   ├── context/          # React Context providers
│   │   ├── hooks/            # Custom React hooks
│   │   ├── services/         # API service layer
│   │   └── utils/            # Utility functions
│   ├── seller/               # Seller dashboard application
│   │   ├── app/              # Next.js App Router pages
│   │   ├── components/       # React components
│   │   ├── context/          # React Context providers
│   │   ├── hooks/            # Custom React hooks
│   │   ├── service/          # API service layer
│   │   └── utils/            # Utility functions
│   └── admin/                # Admin dashboard application
│       ├── app/              # Next.js App Router pages
│       ├── components/       # React components
│       ├── hooks/            # Custom React hooks
│       ├── services/         # API service layer
│       └── lib/              # Utility functions
├── packages/
│   ├── components/           # Shared UI components
│   ├── util/                 # Shared utilities and APIs
│   │   ├── src/api/          # HTTP client configuration
│   │   ├── src/socket/       # WebSocket/STOMP configuration
│   │   ├── src/webrtc/       # WebRTC configuration
│   │   └── src/file/         # File handling utilities
│   └── typescript-config/    # Shared TypeScript configurations
├── .docker/                  # Docker configurations
│   ├── compose.yaml          # Production deployment
│   ├── compose.local.yaml    # Local development
│   └── compose.build.yaml    # Build configuration
├── .github/                  # GitHub Actions workflows
│   └── workflows/
│       ├── main.yaml         # Main deployment pipeline
│       ├── deploy-dev.yaml   # Development deployment
│       └── build-image.yaml  # Docker image building
└── .husky/                   # Git hooks configuration

• Node.js: >= 18.0.0
• Yarn: >= 1.22.22
• Docker: >= 20.0.0 (for containerized deployment)
• Git: Latest version

# Clone the repository
git clone <repository-url>
cd retrade-client

# Install dependencies for all workspaces
yarn install

# Build shared packages
yarn build

# Start all applications in development mode with Turbopack
yarn dev

# Start specific application
yarn workspace @retrade/rt-client-customer dev
yarn workspace @retrade/rt-client-seller dev
yarn workspace @retrade/rt-client-admin dev

# Run with specific port (if needed)
yarn workspace @retrade/rt-client-customer dev -- --port 3001

Application URLs:

• Customer App: http://localhost:3001
• Seller Dashboard: http://localhost:3002
• Admin Dashboard: http://localhost:3000

# Build all applications
yarn build

# Build specific application
yarn workspace @retrade/rt-client-customer build

# Start production server
yarn workspace @retrade/rt-client-customer start

# Start all services locally with development profile
docker compose -f .docker/compose.local.yaml --profile dev up -d

# Start specific service
docker compose -f .docker/compose.local.yaml --profile customer up -d
docker compose -f .docker/compose.local.yaml --profile seller up -d
docker compose -f .docker/compose.local.yaml --profile admin up -d

# View logs
docker compose -f .docker/compose.local.yaml logs -f

# Deploy to staging environment
docker compose -f .docker/compose.yaml --profile stag up -d

# Deploy to production environment
docker compose -f .docker/compose.yaml --profile prod up -d

# Deploy specific service to production
docker compose -f .docker/compose.yaml --profile customer up -d

Production URLs:

• Customer: https://retrade.local (prod) / https://dev.retrade.local (staging)
• Seller: https://seller.retrade.local (prod) / https://seller-dev.retrade.local (staging)
• Admin: https://admin.retrade.local (prod) / https://admin-dev.retrade.local (staging)

Each application uses environment variables for configuration. Create .env.local files in each app directory:

API_BASE_URL=https://api.retrade.local
SOCKET_URL=wss://socket.retrade.local
NEXT_PUBLIC_APP_ENV=development

API_BASE_URL=https://api.retrade.local
SOCKET_URL=wss://socket.retrade.local
NEXT_PUBLIC_APP_ENV=development

API_BASE_URL=https://api.retrade.local
SOCKET_URL=wss://socket.retrade.local
NEXT_PUBLIC_APP_ENV=development

• Follow TypeScript strict mode with proper type definitions
• Use functional components with React hooks
• Implement proper error boundaries for robust error handling
• Follow the established folder structure and naming conventions
• Use ESLint and Prettier for consistent code formatting

• Use Radix UI primitives for accessible, unstyled components
• Implement responsive design with Tailwind CSS mobile-first approach
• Create reusable components in the shared packages when applicable
• Follow the compound component pattern for complex UI elements
• Use proper TypeScript interfaces for component props

• Use the shared API utilities from @retrade/util package
• Implement comprehensive error handling with user-friendly messages
• Use TypeScript interfaces for all API request/response types
• Handle loading, success, and error states consistently across components
• Implement proper caching strategies for frequently accessed data

• Use React Context for application-wide state in Customer and Seller apps
• Use Redux Toolkit for complex state management in Admin app
• Implement proper state normalization for complex data structures
• Use custom hooks to encapsulate state logic and side effects

# Run linting across all workspaces
yarn lint

# Format code with Prettier
yarn format

# Type checking
yarn type-check

# Run specific linting
yarn workspace @retrade/rt-client-customer lint

• ESLint: Configured with Next.js and TypeScript rules
• Prettier: Automated code formatting with custom configuration
• Husky: Pre-commit hooks for code quality enforcement
• TypeScript: Strict mode enabled for type safety

• Bundle Optimization: Next.js automatic code splitting and tree shaking
• Image Optimization: Next.js Image component with remote pattern support
• Lazy Loading: Component-level code splitting with dynamic imports
• Caching: Proper HTTP caching headers and Next.js built-in caching
• Turbopack: Fast bundler for development with hot module replacement

• Built-in Next.js analytics and performance metrics
• Custom performance tracking for critical user journeys
• Bundle analyzer integration for bundle size monitoring

• Authentication: JWT-based authentication with refresh tokens
• Authorization: Role-based access control (RBAC)
• HTTPS: Enforced in production with proper SSL/TLS configuration
• Input Validation: Client and server-side validation with Joi schemas
• XSS Protection: Sanitized user inputs and CSP headers
• Device Fingerprinting: FingerprintJS for enhanced security
• Secure Headers: Comprehensive security headers configuration

• Sensitive data encryption in transit and at rest
• Proper session management and token handling
• GDPR-compliant data handling practices

• Triggers on push to main branch
• Builds Docker images for all applications
• Deploys to both staging and production environments

• Matrix strategy for parallel builds (customer, seller, admin)
• Separate builds for development and production environments
• Pushes images to GitHub Container Registry (GHCR)

• Automated deployment to development and production servers
• Docker Compose orchestration with proper profiles
• Automatic cleanup of old images and containers

• Development: Continuous deployment from main branch
• Staging: Pre-production testing environment
• Production: Stable production environment with manual approval

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes following the coding standards
4. Run tests and linting (yarn lint && yarn type-check)
5. Commit your changes (git commit -m 'Add some amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request with detailed description

• Provide clear description of changes
• Include screenshots for UI changes
• Ensure all checks pass (linting, type checking)
• Update documentation if necessary
• Request review from relevant team members

This project is proprietary and confidential. All rights reserved by Retrade Platform.