Agents/KNOWLEDGE.md

Tradhox Ecosystem - Comprehensive Technical Knowledge Base

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

---

🏛️ Ecosystem Overview

graph TD
    UI([Supplier Browser]) --> S3[AWS S3 / CloudFront\n(supplier_central_frontend)]
    S3 --> ReactApp[React 19 + TypeScript + Vite]
    ReactApp -- REST / JWT --> EC2[AWS EC2 Server\n(seller_central_backend)]
    EC2 --> Backend[Django 6.1 DRF Core]
    Backend -- Logistics API --> ShippingService[shippingservice\nDjango Microservice]
    ShippingService --> EKart[EKart Carrier Client]
    ShippingService --> SFX[SFX Carrier Client]

---

1. 🖥️ Frontend: supplier_central_frontend

• 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.

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.
  • 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).
  • ShippingLabelsPage.tsx & LabelPreviewPage.tsx - Thermal AWB label preview & batch printing.
  • StorefrontPage.tsx & SettingsPage.tsx - Seller brand settings.

API Client Layer (src/services/api.ts)

• Configured with BASE_URL pointing to EC2 backend.
• Manages JWT Bearer token authentication via getAuthHeaders().

---

2. ⚙️ Backend Core: 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.

Core Endpoints & Functionality

• Auth & KYC:
  • POST /api/auth/register/ & POST /api/auth/login/
  • POST /api/auth/send-whatsapp/ & POST /api/auth/send-email-otp/
  • POST /api/profile/kyc/verify-pan/ & POST /api/profile/kyc/upload-eaadhaar/
  • POST /api/profile/submit-gstin/
• Catalog Management:
  • GET/POST /api/products/ (DRF ProductViewSet)
  • POST /api/products/bulk-upload/ (CSV parsing & product seeding)
  • POST /api/profile/presigned-url/ (AWS S3 image upload signatures)
• Order Lifecycle:
  • GET /api/orders/
  • POST /api/orders/:id/accept/ & POST /api/orders/:id/reject/
  • POST /api/orders/:id/create_pickup/
  • GET /api/orders/:id/track/
  • GET /api/orders/:id/print_label/
• Wallet:
  • GET /api/wallet/ & POST /api/wallet/withdraw/

---

3. 🚚 Shipping & Logistics Microservice: shippingservice

• Directory: d:/Tradhox_workspace/shippingservice
• Tech Stack: Django 5.x, Gunicorn, Requests, WhiteNoise.
• Daemon: shippingservice-beta.service on EC2.

Carrier Integrations

• EKart Integration (ekart/):
  • ekart/client.py: API wrapper for EKart parcel booking, tracking, and cancellation.
  • ekart/views.py: Dashboard & status views.
• SFX Integration (shipping/):
  • shipping/sfx_client.py: API client for SFX forward & reverse logistics.
  • shipping/views.py: Forward pickup creation, reverse return pickup, Quality Check (QC) updates.
  • Webhooks handling (templates/shipping/webhooks.html).
  • Print Label template rendering (templates/shipping/print_label.html).

---

🛠️ Verification & Build Commands

Frontend Verification

cd d:/Tradhox_workspace/supplier_central_frontend
npm run build
npm run lint

Backend & Shipping Service Verification

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

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