CommodityChain

Real-time commodity intelligence platform — live prices, AI analysis, India macro layer, news feed, alerts, and interactive tools.

Frontend: commoditychain.vercel.app  ·  Backend API: commoditychain-api-ayaveegddsfagxc8.centralindia-01.azurewebsites.net/docs

---

Features

Module	Description
Dashboard	Live price cards, bar charts, top movers, market sentiment
Explorer	Full price history chart (1W/1M/3M/1Y), OHLC table, watchlist
Map	D3 world map — producer/consumer profiles for 20 countries
Correlation	8×8 Pearson correlation heatmap (30-day rolling)
Converter	Currency + commodity unit + value converter with live FX rates
Watchlist	Hypothetical portfolio with live unrealised PnL
Alerts	Browser push notification price alerts (localStorage)
Export Data	CSV / JSON price history download
News	Commodity-filtered news feed with AI sentiment labels
Learn	Explainer articles — oil, gold, futures, copper, India context
Analyst	Groq Llama 3.3 70B chat with live price context + 3 persona modes
Simulator	India macro impact model — drag crude price, see petrol/inflation/INR
India	City-wise petrol/diesel prices + tax breakdown + macro indicators

---

Tech Stack

Layer	Technology
Frontend	Next.js 14 + TypeScript
Styling	Custom CSS variable design system (dark + light)
Backend	FastAPI + WebSockets
AI	Groq Llama 3.3 70B (free tier)
Price data	Twelve Data API (real-time)
Metals fallback	metals.live
FX rates	open.er-api.com
News	NewsAPI + curated fallback
Frontend host	Vercel
Backend host	Azure App Service (B1 · Central India)
CI/CD	GitHub Actions

---

Local Setup

# Terminal 1 — Backend
cd backend
py -3.11 -m venv venv
.\venv\Scripts\Activate.ps1
pip install -r requirements.txt
uvicorn main:app --reload --port 8000

# Terminal 2 — Frontend
cd frontend
npm install
npm run dev

Open http://localhost:3000 · API docs at http://localhost:8000/docs

---

Environment Variables

backend/.env

ALLOWED_ORIGINS=http://localhost:3000
GROQ_API_KEY=           # console.groq.com — free
TWELVE_DATA_KEY=        # twelvedata.com — free tier
NEWS_API_KEY=           # newsapi.org — optional
WEBSITES_PORT=8000

frontend/.env.local

NEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_WS_URL=ws://localhost:8000

---

Deployment

Layer	Platform	Notes
Frontend	Vercel	Auto-deploy on push to main
Backend	Azure App Service B1	GitHub Actions CI/CD via .github/workflows/main_commoditychain-api.yml

Azure App Service settings:

• Runtime: Python 3.11 · Linux
• Startup command: uvicorn main:app --host 0.0.0.0 --port 8000
• Always On: enabled
• WebSockets: enabled

---

API Reference

Method	Route	Description
GET	/api/prices	All commodity prices
GET	/api/prices/:id	Single commodity
GET	/api/news	News feed
GET	/api/rates	Live FX rates
POST	/api/analyst	AI analysis (Groq)
POST	/api/simulate	India macro shock model
GET	/api/export/:id	CSV/JSON download
GET	/api/india/prices	City-wise petrol/diesel
GET	/api/correlation	Pearson matrix
WS	/ws/prices	Live price stream

---

Project Structure

commoditychain/
  backend/
    main.py                    # FastAPI app, 9 routers
    requirements.txt
    services/
      commodity_service.py     # Twelve Data + GBM fallback
    routers/
      prices.py / websocket.py / news.py / fx.py
      analyst.py / simulator.py / export.py
      india.py / correlation.py
  frontend/src/
    app/                       # 13 pages (Next.js App Router)
    components/
      Navbar.tsx               # Grouped nav with icons
      PriceCard.tsx / Ticker.tsx / StatsBar.tsx
    hooks/
      usePrices.ts / useTheme.ts / useWatchlist.ts
    lib/
      api.ts / constants.ts / utils.ts
  .github/
    workflows/
      main_commoditychain-api.yml   # Azure backend deploy

---

Build Phases

Phase	Features
1	Dashboard, live prices, WebSocket, dark mode
2	Explorer, News, Converter, Watchlist
3	AI Analyst, Shock Simulator, Alerts, Learn
4	Global Map, Correlation Matrix, Export, India Layer

---

Built by Ayush Raj — BSc CSDA @ IIT Patna 2024–2028
Stack: Next.js 14 · FastAPI · Groq · Twelve Data · Vercel · Azure