HaathSe — Voice-First Fair Commerce for Indian Artisans

A hackathon MVP that empowers Indian artisans with voice-to-listing AI, multilingual translation, fair transparent payments, NFT provenance on Polygon, cinematic Mapbox origin stories, and WebAR product preview.

---

Features

Feature	Description
Voice to Listing	Artisans speak their product story in any Indian language — AI generates a bilingual product listing
AI Translation	HuggingFace hosted API for language detection and translation across Indian languages and English
Fair Payment Split	Transparent 90/8/2 split: Artisan / Platform / Carbon Fund
NFT Provenance	ERC721 certificates on Polygon Amoy with QR codes for authenticity verification
Origin Flyover	Cinematic Mapbox journey from artisan village to buyer city with geodesic arc
WebAR Preview	View products in augmented reality using Google model-viewer
Custom Orders	Buyers describe customizations — AI translates + rule-based pricing engine with 14 modifier rules
Curated Marketplace	12 handpicked products across 8 categories with deep craft history and GI tag info
Auth	Firebase authentication with Google OAuth and email/password, role-based (artisan/buyer)
Artisan Dashboard	Order management with accept/edit/reject flows, crafting status tracking, and stats

---

Architecture

HaathSe/
├── backend/              # Node.js + Express API server (port 3001)
│   ├── services/         # AI wrappers (audio, translation, LLM, pricing, orderStore)
│   ├── routes/           # API endpoints (listing, customOrder, payment, provenance)
│   └── utils/            # JSON schema validators
├── frontend/             # Next.js 14 (App Router) + Tailwind + Framer Motion
│   ├── app/              # Pages (landing, artisan, marketplace, product, custom-order,
│   │                     #   provenance, ar-preview, orders, login, signup)
│   ├── components/       # Reusable UI (VoiceRecorder, ListingCard, OriginMap, ARViewer,
│   │                     #   PaymentSplitDisplay, ProvenanceCard, CustomOrderForm, etc.)
│   ├── lib/              # Firebase config, AuthContext, typed API client
│   └── public/models/    # 3D GLB files for AR preview
├── contracts/            # Solidity smart contract + Hardhat config
├── scripts/              # Hardhat deployment script
└── docs/plans/           # MVP implementation plan

Monorepo with three independent npm packages sharing a root .env. No root package.json.

---

Tech Stack

• Frontend: Next.js 14 (App Router), TailwindCSS, Framer Motion, Mapbox GL JS, Google model-viewer, Lucide React icons
• Backend: Node.js, Express, Axios, multer, qrcode
• AI: AssemblyAI SDK (STT), HuggingFace hosted API (translation + language detection), LM Studio + DeepSeek R1 8B (structured listing generation)
• Auth: Firebase Authentication (Google OAuth + email/password)
• Blockchain: Hardhat, Ethers.js, ERC721URIStorage + Ownable (Polygon Amoy)
• Payments: Mocked Razorpay simulation with transparent split calculation

---

Quick Start

Prerequisites

• Node.js 18+
• All external services are optional — the app gracefully falls back to demo/mock data

1. Clone and Setup Environment

cp .env.example .env
# Edit .env with your API keys (all optional for demo mode)

2. Start Backend

cd backend
npm install
npm run dev

Backend runs at http://localhost:3001. Health check: GET /api/health

3. Start Frontend

cd frontend
npm install
npm run dev

Frontend runs at http://localhost:3000. All /api/* requests are proxied to the backend.

4. (Optional) External Services

Service	Purpose	Without it
LM Studio with DeepSeek R1 8B on port 1234	Structured listing generation	Template-based fallback listing
AssemblyAI API key	Speech-to-text	Demo transcription in Telugu/Hindi/English
Mapbox access token (NEXT_PUBLIC_MAPBOX_TOKEN)	Origin flyover map	Elegant fallback card with village info
Firebase config (NEXT_PUBLIC_FIREBASE_*)	User authentication	App works without auth
HuggingFace Space API	Translation + language detection	Falls back to Telugu default

5. (Optional) Deploy Smart Contract

cd contracts
npm install
npx hardhat compile
npx hardhat run scripts/deploy.js --network polygonAmoy

---

API Endpoints

All routes are mounted under /api in the backend.

Listing

Method	Endpoint	Description
POST	/api/voice-to-listing	Upload audio file — full pipeline: transcribe, detect language, translate, generate structured listing
POST	/api/demo-listing	Generate listing from text input (no audio needed)

Custom Orders

Method	Endpoint	Description
POST	/api/custom-order	Submit custom order with auto language detection, translation, and pricing
GET	/api/custom-order/:orderId	Fetch a single order with full timeline
GET	/api/custom-orders	List all orders (filter by ?artisan=&status=&productId=)
POST	/api/custom-order/respond	Artisan accept/edit-price/reject an order
POST	/api/custom-order/:orderId/start	Artisan marks crafting begun
POST	/api/custom-order/:orderId/complete	Artisan marks order complete
GET	/api/artisan/:artisanName/stats	Artisan dashboard stats (pending/active/completed/rejected)
GET	/api/artisan/:artisanName/orders	All orders for a specific artisan

Payment

Method	Endpoint	Description
POST	/api/payment/split	Calculate transparent 90/8/2 payment split
POST	/api/payment/simulate	Mock Razorpay payment with generated IDs

Provenance

Method	Endpoint	Description
POST	/api/provenance/mint	Mint in-memory NFT provenance with QR code
GET	/api/provenance/:tokenId	Get provenance metadata (falls back to demo data)

Health

Method	Endpoint	Description
GET	/api/health	Service status and configured API key flags

---

Frontend Pages

Route	Description
/	Landing page with hero, feature cards, live voice demo, origin map
/marketplace	12 curated products with search, category/state filters, sort
/product/[id]	Full product page — AR viewer, origin map, craft history, payment split, provenance
/artisan	Artisan studio — 5-step workflow: record voice, upload images, view listing, payment split, mint NFT
/artisan/orders	Artisan order dashboard — manage incoming requests, active crafting, past orders
/artisan/profile-setup	Post-signup profile completion for artisans (craft, location, experience)
/custom-order	Buyer custom order form with suggestion chips and pricing breakdown
/orders/[orderId]	Buyer order tracking with auto-refresh and timeline
/provenance/[tokenId]	NFT provenance certificate with blockchain info and origin map
/ar-preview	WebAR gallery with 3 GLB models (clay pot, blue pottery vase, wooden toy)
/login	Role-based login (artisan/buyer) via Google OAuth or email/password
/signup	Role-based signup with additional artisan profile fields

---

Smart Contract

contracts/HaathSeProvenance.sol — ERC721URIStorage + Ownable (Solidity 0.8.20)

• Token: HaathSe Provenance (HSP)
• Stores on-chain: artisan name, village, production date, mint timestamp, artisan address
• mintProvenance() — mints NFT to artisan's address, sets IPFS URI, emits ProvenanceMinted event
• getProvenance() — returns all on-chain metadata
• Deployed to Polygon Amoy testnet (chain ID 80002)

Note: The backend currently mocks provenance with in-memory storage. The Solidity contract is ready but not wired to the backend.

---

Design System

• Colors: Background #F5F1E8, Primary #1F3D2B, Accent #C26A3D, Olive #6B7B3A, Cream #FAF7F0
• Theme: Organic, nature-inspired, warm — no neon, no tech-blue
• Glass Cards: backdrop-blur-lg bg-white/30 border-white/40 rounded-2xl shadow-xl
• Typography: Playfair Display (serif headings), Inter (sans body)
• Animations: Soft fade-in, gentle hover (max 1.02 scale), smooth Mapbox flyover

---

Demo Walkthrough

1. Landing — Open http://localhost:3000, explore the feature cards and live voice demo
2. Marketplace — Browse 12 curated products, filter by category or state, search by keyword
3. Product Page — Visit /product/1 for the full experience: AR viewer, origin map, craft history, payment split
4. Voice Listing — Go to Artisan Studio, click "Generate Demo Listing" to see AI pipeline output
5. Custom Order — Navigate to Custom Orders, type "I want larger size with blue color", see pricing breakdown
6. Order Tracking — After placing a custom order, follow the order ID link to track status
7. Artisan Dashboard — Visit Artisan Orders to accept/reject orders and manage crafting
8. AR Preview — Interact with 3D models and try "View in AR" on a supported device
9. Provenance — Check /provenance/1 for NFT certificate with QR code and blockchain info

---

License

MIT