vignesh/Agents
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
Agents/KNOWLEDGE.md

16 KiB
Raw Permalink Blame History

Tradhox Ecosystem - Comprehensive Technical Knowledge Base

This document contains full technical specifications, data models, API endpoints, microservices, and deployment configurations for the Tradhox Platform.

⚡ Critical Environment & Coding Standards

Important

1. Direct Manual Coding Rule: Do NOT use scratch scripts to edit or patch project files. Perform direct manual coding on each and every file. 2. Zero Mock / Sample Data Standard: Never hardcode dummy/sample products or mock users in frontend production states. Catalog, cart, orders, wishlist, addresses, and wallets must start in a clean initial state. 3. API Base URL Rule: Use https://betapartner-api.tradhox.com/api as the API endpoint for both Beta and Local Testing environments. 4. Chrome DevTools MCP Standard: Always use Chrome DevTools (chrome-devtools-mcp) tools (new_page, navigate_page, take_screenshot, evaluate_script) for all browser verifications.

🔑 Important Ecosystem Keys & Configurations

Parameter Configuration / Value Scope / Usage
Supplier API Base URL https://betapartner-api.tradhox.com/api Primary DRF Backend API for Supplier Central (Beta & Local)
Customer API Base URL https://beta-api.tradhox.com/api Primary DRF Backend API for Customer Website (Beta & Local)
CSA API Base URL https://betaapicsa.tradhox.com/api CSA Backend API (crmbackend) for Beta & Local testing
CSA Production Domain https://csa.tradhox.com Customer Service & Support Portal (S3 Bucket: csawebsite)
CSA Beta Domain https://betacsa.tradhox.com Staging / Beta CSA Portal (S3 Bucket: betacsa)
EC2 Server Host 16.113.57.127 Main Application EC2 Instance (ap-south-2)
SSH Key Path ~/.ssh/vignesh_tipro_apsouth2.pem SSH Private Key for Ubuntu user
DB Host 16.113.106.152 PostgreSQL cluster host (cisystem)
DB Port 5432 Standard PostgreSQL port
DB User vignesh Core database superuser
DB Password vignesh_secret_pass_2026 PostgreSQL password (Do NOT alter on server)
Beta Databases sellerprofile_beta, productprofile_beta, customerprofile_beta Active staging / beta databases
Prod Databases sellerprofile_prod, productprofile_prod, customerprofile_prod Production databases
AWS S3 Bucket betasupplierdocumentstorage Private S3 media storage for KYC, product photos & videos
AWS S3 Region ap-south-2 AWS Hyderabad region
S3 Base Storage URL https://betasupplierdocumentstorage.s3.ap-south-2.amazonaws.com/ Base prefix for uploaded files
WhatsApp Gateway http://betawhatsapp.tradhox.com/api/send/ External WhatsApp OTP dispatch service
Email Gateway https://beta-mailservices.tradhox.com/api/send/ Transactional email dispatch service
Forgejo Pipeline https://pipeline.tradhox.com CI/CD Git server (auto-deploys beta branch to EC2)
Supplier Central UI http://localhost:3000 Vite development server for supplier portal
Customer Website UI http://localhost:5173 Vite development server for customer marketplace

🏛️ Ecosystem Overview

graph TD
    SupplierUI([Supplier Central UI\nReact 19 + TS + Vite]) --> S3_Supplier[AWS S3 / CloudFront]
    CustomerUI([Customer Marketplace UI\nReact 19 + Vite]) --> S3_Customer[AWS S3 / CloudFront]
    SupplierUI -- REST / JWT --> Nginx[Nginx Reverse Proxy\n16.113.57.127:443]
    CustomerUI -- REST / State --> Nginx
    Nginx -- Proxy 8080 --> Backend[Django 6.1 DRF Core\nseller_central_backend]
    Nginx -- Proxy 8086 --> ShippingService[shippingservice\nDjango Microservice]
    Nginx -- Proxy 8091 --> EmailService[emailservice\nDjango Service]
    Nginx -- Proxy 8081 --> WhatsAppService[whatsapp-service\nSMS & WhatsApp Gateway]
    Nginx -- Proxy 8092/8093 --> DocVerify[documentverification\nKYC OCR Microservice]
    Backend --> DB[(PostgreSQL Cluster\n16.113.106.152:5432)]

1. 🛍️ Frontend (FOR SELLERS & SUPPLIERS): supplier_central_frontend

  • Target Audience: Sellers & Artisans (Product ingestion, stock management, order acceptance, payouts & shipping label printing).
  • Directory: d:/Tradhox_workspace/supplier_central_frontend
  • Tech Stack: React 19, TypeScript, Vite, TailwindCSS v4, Bulma CSS, Lucide React, FontAwesome.
  • Hosting: AWS S3 Static Hosting / CloudFront CDN.
  • API Base Endpoint: https://betapartner-api.tradhox.com/api (for both local development & beta).

Key Pages & Routing

  • Public Routes:
    • LandingPage.tsx - Homepage & feature highlights.
    • HowItWorksPage.tsx - Supplier workflow guide.
    • PricingPage.tsx - Pricing tiers & fee structure.
    • OnboardingPage.tsx - Supplier registration & KYC verification wizard.
    • LoginPage.tsx & ResetPasswordPage.tsx - Auth flows.
  • Dashboard Routes:
    • OverviewPage.tsx - Real-time metrics & business analytics.
    • AddProductPage.tsx - Single product catalog ingestion (Starts at Step 1 Category selection with media file dropzone).
    • BulkUploadPage.tsx - Batch CSV product import with validation.
    • InventoryPage.tsx - Stock levels & price adjustments.
    • OrdersPage.tsx & Order Views - Order acceptance, rescheduling, damage reporting.
    • PayoutsPage.tsx - Wallet balance & withdrawal requests.
    • ReturnsTrackerPage.tsx - Reverse shipment tracking & Quality Check (QC).
    • StorefrontPage.tsx & SettingsPage.tsx - Seller brand settings.

2. 🏛️ Frontend & Backend (FOR CONSUMERS & END CUSTOMERS): customerwebsite & customerwebsitebackend

A. Frontend: customerwebsite (FOR CONSUMERS)

  • Target Audience: End Consumers & Patrons (Catalog browsing, shopping bag, checkout, order tracking & sovereign wallet).
  • Directory: d:/Tradhox_workspace/customerwebsite
  • Tech Stack: React 19, Vite, TailwindCSS v4, Lucide React, Google Material Symbols, React Router DOM.
  • Hosting: AWS S3 Static Hosting / CloudFront CDN.
  • Dev Server: http://localhost:5173/
  • Zero Mock / Guest First Architecture:
    • Initial state defaults strictly to Guest Mode (Sign In / Register CTAs in Header, 0 badge counts).
    • Authentication is 100% Mobile Number + WhatsApp OTP based (Email & Password removed).
    • Clean initial states for Cart [], Wishlist [], Orders [], Addresses [], and Sovereign Wallet balance ₹0.
    • Zero hardcoded mock products or fake user credentials.
    • Full dynamic state management in src/context/AuthContext.jsx.
  • Key Modules & Context (AuthContext.jsx):
    • Auth: isLoggedIn, user, sendOtp, loginWithOtp, registerWithOtp, logout, updateProfile.
    • Cart / Bag: cart, addToCart, removeFromCart, updateCartQuantity, clearCart, cartSubtotal, cartTax, cartShipping, cartTotal, cartCount.
    • Wishlist: wishlist, toggleWishlist, removeFromWishlist, isInWishlist, wishlistCount.
    • Delivery Addresses: addresses, addAddress, updateAddress, deleteAddress, setDefaultAddress, getSelectedAddress.
    • Orders: orders, activeOrderId, placeOrder, cancelOrder, requestReturn, getOrderById.
    • Sovereign Wallet: walletBalance, walletTransactions, addMoneyToWallet, payWithWallet.
  • Page Route Specs (App.jsx):
    • / & /home - HomePage.jsx (Hero banner, heritage categories, curated collections, trending products).
    • /products - ProductListingPage.jsx (Catalog grid, price filtering, category taxonomy, sorting).
    • /product/:id - ProductDetailPage.jsx (Gallery, variant selector, stock status, add to cart/buy now).
    • /cart - CartPage.jsx (Bag items, quantity adjustments, tax/shipping breakdown).
    • /checkout - CheckoutPage.jsx (Delivery address selection & order summary).
    • /select-payment & /payment - SelectPaymentPage.jsx (UPI, Cards, NetBanking, Sovereign Wallet, COD).
    • /payment-retry - PaymentRetryPage.jsx (Transaction failure recovery).
    • /orders - OrderConfirmationPage.jsx (Success message & invoice summary).
    • /tracking - OrderTrackingPage.jsx (Real-time tracking, Shadowfax AWB timeline).
    • /wishlist - WishlistPage.jsx (Saved patron wishlist grid).
    • /account - AccountPage.jsx (Patron dashboard hub).
    • /wallet - WalletPage.jsx & /add-money - AddMoneyWalletPage.jsx (Sovereign wallet ledger & top-up).
    • /profile - ProfilePage.jsx & /change-password - ChangePasswordPage.jsx (Profile & security settings).
    • /addresses - AddressesPage.jsx & /add-address - AddAddressPage.jsx (Saved address management).
    • /login - LoginPage.jsx & /register - RegisterPage.jsx (WhatsApp OTP login/registration).
    • /order-cancellation & /return-request - Cancellation & return request flows.

B. Backend Microservice: customerwebsitebackend (FOR CONSUMERS)

  • Directory: d:/Tradhox_workspace/customerwebsitebackend
  • Tech Stack: Python 3.14, Django 6.1, DRF, SimpleJWT, django-cors-headers, Gunicorn, PostgreSQL.
  • Daemon Service: customer-website-backend.service on AWS EC2 (16.113.57.127:8082).
  • CORS Setup: CorsMiddleware #1 position, CORS_ALLOW_ALL_ORIGINS = True, CORS_ALLOW_CREDENTIALS = True, full HTTP methods & headers.
  • Database Routing: Multi-database setup (DatabaseRouter in customerwebsitebackend/db_router.py):
    • default / customerprofile: Database customerprofile_beta or customerprofile_prod (Users, CustomerProfiles, Carts, CartItems, Orders).
    • productprofile: Database productprofile_beta or productprofile_prod (Categories, Product unmanaged model pointing to api_product table).
    • sellerprofile: Database sellerprofile_beta or sellerprofile_prod (SellerOrder unmanaged model pointing to api_order table).
  • Core API Endpoints:
    Endpoint Method Class View Description
    /api/v1/customer/auth/send-whatsapp/ POST SendWhatsAppOTPView Dispatch WhatsApp OTP to mobile number
    /api/v1/customer/auth/register/ POST UserRegisterView Register customer account
    /api/v1/customer/auth/login/ POST TokenObtainPairView JWT Token generation
    /api/v1/customer/auth/refresh/ POST TokenRefreshView JWT Token refresh
    /api/v1/customer/profile/ GET, PUT UserProfileView Fetch & update customer profile
    /api/v1/customer/categories/ GET CategoryListView Public category taxonomy list
    /api/v1/customer/products/ GET ProductListView Catalog product listing & search
    /api/v1/customer/products/<id>/ GET ProductDetailView Single product details
    /api/v1/customer/cart/ GET, POST CartView View shopping cart / Add item
    /api/v1/customer/cart/items/<id>/ PUT, DELETE CartItemDetailView Update item quantity / Delete
    /api/v1/customer/cart/checkout/ POST CheckoutView Create Order & sync SellerOrder (api_order)
    /api/v1/customer/cart/payment-success/ POST PaymentSuccessView Payment confirmation & update seller status
    /api/v1/customer/orders/ GET OrderHistoryView Customer order history with tracking details
    /api/v1/customer/orders/<id>/ GET OrderDetailView Customer order detail view

3. ⚙️ Backend Core (FOR SELLERS & SUPPLIERS): seller_central_backend

  • Directory: d:/Tradhox_workspace/seller_central_backend
  • Tech Stack: Python 3.14, Django 6.1, DRF, SimpleJWT, Gunicorn, PostgreSQL/SQLite, Boto3.
  • Daemon: seller-central-backend.service on AWS EC2 (16.113.57.127:8080).
  • API Host Domain: https://betapartner-api.tradhox.com/api

4. 🎧 CSA Site Frontend & Backend: crmfrontend & crmbackend

  • Frontend Directory: d:/Tradhox_workspace/crmfrontend
    • Tech Stack: React 19, TypeScript, Vite, TailwindCSS v4.
    • Hosting: AWS S3 Static Hosting (csawebsite for Prod, betacsa for Beta) / CloudFront CDN.
    • Public Domains: https://csa.tradhox.com (Prod) & https://betacsa.tradhox.com (Beta).
  • Backend Directory: d:/Tradhox_workspace/crmbackend
    • Tech Stack: Python 3.14, Django 6.1, DRF, Gunicorn.
    • API Host Domains: https://apicsa.tradhox.com/api (Prod) & https://betaapicsa.tradhox.com/api (Beta).

5. 🚚 Shipping & Logistics Microservice: shippingservice

  • Directory: d:/Tradhox_workspace/shippingservice
  • Tech Stack: Django 5.x, Gunicorn, Requests, WhiteNoise.
  • Daemon: shippingservice-beta.service on EC2 (16.113.57.127:8086).
  • Carrier Clients: EKart Client (ekart/client.py) and Shadowfax Client (shipping/sfx_client.py).

6. 🌐 EC2 Server Infrastructure & Nginx Proxy Architecture

  • Server IP: 16.113.57.127 (Region: ap-south-2, User: ubuntu, Key: ~/.ssh/vignesh_tipro_apsouth2.pem)
  • Database Cluster: 16.113.106.152:5432 (cisystem)

Active Ports & Reverse Proxy Mapping Table

Port Bound Systemd Service Nginx Upstream / Proxy Target Public Domain / URL
80 / 443 0.0.0.0 nginx.service Reverse Proxy Master https://*.tradhox.com
8080 0.0.0.0 seller-central-backend.service http://127.0.0.1:8080 https://betapartner-api.tradhox.com
8082 0.0.0.0 customer-website-backend.service http://127.0.0.1:8082 Customer Website Backend API
8085 0.0.0.0 seller-central-backend-beta.service Standby Beta DRF API Internal testing / staging
8086 0.0.0.0 shippingservice-beta.service http://127.0.0.1:8086 Logistics & AWB Label API
8087 0.0.0.0 searchengine.service http://127.0.0.1:8087 https://betasearch-api.tradhox.com
8108 127.0.0.1 typesense-server.service http://127.0.0.1:8108 Typesense Search Engine Service
8091 0.0.0.0 emailservice.service http://127.0.0.1:8091 https://beta-mailservices.tradhox.com
8081 127.0.0.1 whatsapp-service.service http://127.0.0.1:8081 https://betawhatsapp.tradhox.com
8092 127.0.0.1 beta-documentverification.service http://127.0.0.1:8092 KYC Document Verification (Beta)
8093 127.0.0.1 documentverification.service http://127.0.0.1:8093 KYC Document Verification (Prod)
6379 127.0.0.1 redis-server.service Redis Key-Value Store Local broker & cache
51820 / 51821 0.0.0.0 docker-proxy WireGuard VPN Container Internal secure gateway & Web UI
22 0.0.0.0 ssh.service OpenSSH Server Remote server terminal access

Nginx Configuration File Paths (/etc/nginx/sites-available/)

  • seller-central-backend \rightarrow /etc/nginx/sites-enabled/seller-central-backend (Proxies port 8080)
  • customer-website-backend \rightarrow /etc/nginx/sites-enabled/customer-website-backend (Proxies port 8082)
  • shippingservice-beta \rightarrow /etc/nginx/sites-enabled/shippingservice-beta (Proxies port 8086)
  • searchengine \rightarrow /etc/nginx/sites-enabled/searchengine (Proxies port 8087)
  • emailservice \rightarrow /etc/nginx/sites-enabled/emailservice (Proxies port 8091)
  • smswhatsappservice \rightarrow /etc/nginx/sites-enabled/smswhatsappservice (Proxies port 8081)
  • documentverification & beta-documentverification \rightarrow Proxies ports 8093 & 8092
  • socialmedia.tradhox.com \rightarrow /etc/nginx/sites-enabled/socialmedia.tradhox.com

🧪 Verification & Build Commands

Frontend Verification

# Supplier Central Frontend
cd d:/Tradhox_workspace/supplier_central_frontend
npm run build

# Customer Marketplace
cd d:/Tradhox_workspace/customerwebsite
npm run build

Backend, Customer Backend & Shipping Service Verification

cd d:/Tradhox_workspace/seller_central_backend
python manage.py test

cd d:/Tradhox_workspace/customerwebsitebackend
python manage.py test

cd d:/Tradhox_workspace/shippingservice
python manage.py test

🌐 Browser Automation & UI Testing

  • Always Use Chrome DevTools MCP: Always use Chrome DevTools (chrome-devtools-mcp) tools (new_page, navigate_page, take_screenshot, click, evaluate_script) to open, interact with, and verify web applications in the browser. Avoid standalone Playwright driver downloads.