Pricing intelligence for informal economies.

MarketLens is a full-stack platform that tracks, analyzes, and surfaces real-time price data from informal markets across the globe. It combines crowdsourced price observations with World Bank macroeconomic data, FAO producer price records, and live humanitarian alerts to compute an Informal Inflation Index (III) for each tracked market. An AI layer powered by Claude generates contextual price analysis, negotiation guidance, and market summaries.

The platform ships as a cross-platform mobile and web app (Expo / React Native Web) backed by a Python Flask API.

• Features
• Architecture
• Tech Stack
• Getting Started
• Project Structure
• API Reference
• External Data Sources
• Environment Variables

• Informal Inflation Index (III) - composite deviation score per market, updated in real time as observations come in
• Volatility Score - weighted coefficient of variation across all tracked items in a market
• Price Trend Acceleration (PTA) - percentage change in average price week-over-week
• Real Inflation Differential (RID) - gap between the informal III and official CPI from the World Bank
• Confidence Score - composite metric of observation volume, reporter diversity, and data recency

• Interactive heatmap of all tracked markets (mobile)
• Zoom-to-market with item-level price zone circles
• Card-based deviation view on web (native map not available in browser)

• Submit a price for any tracked item in any market
• Instant AI-powered analysis: deviation score, fairness rating, and negotiation guidance
• Dry-run mode to analyze without saving to the dataset
• Observations persist to PostgreSQL and improve the baseline for all users

• Point camera at any market item to identify it (mobile)
• File upload fallback on web
• Sends image to Claude for identification, then routes to price lookup

• Search all items across any market
• View price range (min, mean, max) with observation counts

• Live disaster feed from ReliefWeb API
• Disruption events automatically raise item baselines in affected categories (drought raises staples 35%, cyclone raises staples and merchandise 40%, etc.)

• Per-market narrative summary generated by Claude on each analysis cycle
• Per-submission insights: price context, severity label, negotiation script with cultural adaptation per city

┌─────────────────────────────────────────┐
│           Expo App (client/)            │
│   React Native + React Native Web       │
│                                         │
│  Mobile routes    Web-only routes       │
│  map.tsx          map.web.tsx           │
│  scan.tsx         scan.web.tsx          │
└───────────────┬─────────────────────────┘
                │  HTTP (REST)
                │  localtunnel for physical device
                v
┌─────────────────────────────────────────┐
│           Flask API (backend/)          │
│                                         │
│  /markets        /market/:id            │
│  /price/submit   /identify              │
│  /intel/global   /intel/:id             │
│  /intel/export   /heatmap               │
└──────┬───────────────────┬──────────────┘
       │                   │
       v                   v
┌─────────────┐    ┌───────────────────────┐
│  PostgreSQL │    │   External APIs       │
│             │    │                       │
│ market_     │    │  Anthropic Claude     │
│ reports     │    │  World Bank API       │
│             │    │  ReliefWeb API        │
│             │    │  FAO CSV Data         │
└─────────────┘    └───────────────────────┘

Baseline computation pipeline:

1. FAO producer price CSV gives a historical floor for each item in each region
2. World Bank CPI and food inflation multipliers adjust that floor for current macroeconomic conditions
3. ReliefWeb disaster events add a category-specific shock multiplier if active
4. Community observations from PostgreSQL further refine the baseline if enough data exists
5. Submitted prices are scored against this adjusted baseline using a z-score method

• Node.js 18+ and npm
• Python 3.11+
• PostgreSQL (local or remote, e.g. Neon, Supabase, Railway)
• An Anthropic API key
• Expo Go installed on your phone (for mobile testing)

cd backend
python -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate
pip install -r requirements.txt

Create a .env file in backend/:

DATABASE_URL=postgresql://user:password@host:5432/marketlens
ANTHROPIC_API_KEY=sk-ant-...

Run migrations and start the server:

python app.py
# API available at http://localhost:5000

cd client
npm install

Update app/constants.ts to point to your backend:

// Local development
export const API_BASE = 'http://localhost:5000';

// Physical device (replace with your machine's local IP)
export const API_BASE = 'http://192.168.x.x:5000';

// Tunnel (for sharing across networks)
export const API_BASE = 'https://your-tunnel.loca.lt';

cd client
npx expo start --clear
# Scan the QR code with Expo Go on your phone

cd client
npm run web
# Opens at http://localhost:8081

Note: the map screen automatically uses a card-based web layout instead of the native map component. The field scanner uses a file upload instead of the camera.

Marketlens/
├── backend/
│   ├── app.py                   # Flask app, all route definitions
│   ├── models/
│   │   ├── anomaly.py           # Z-score baseline and price anomaly detection
│   │   ├── claude_insights.py   # Claude API calls for analysis and summaries
│   │   └── intelligence.py      # III, volatility, PTA, RID, confidence computation
│   ├── services/
│   │   ├── fao.py               # FAO CSV ingestion and price floor lookup
│   │   ├── worldbank.py         # World Bank CPI/food inflation API
│   │   └── reliefweb.py         # ReliefWeb disaster feed and shock multipliers
│   └── data/
│       └── raw/                 # FAO producer price CSV files
│
├── client/
│   └── app/
│       ├── constants.ts         # API base, color palette, market and item definitions
│       ├── index.tsx            # Home screen with active indices
│       ├── map.tsx              # Interactive price map (mobile)
│       ├── map.web.tsx          # Card-based deviation view (web)
│       ├── scan.tsx             # Camera-based field scanner (mobile)
│       ├── scan.web.tsx         # File upload scanner (web)
│       ├── search.tsx           # Item lookup and price search
│       ├── report.tsx           # Price observation submission
│       ├── intelligence.tsx     # III dashboard with signals
│       ├── market/[id].tsx      # Market detail with price index
│       ├── item/[name].tsx      # Item detail with price history
│       └── lib/
│           └── cache.ts         # Client-side fetch cache
│
└── design/
    └── web-dashboard-spec.md    # B2B web dashboard design specification

All endpoints are served from the Flask backend. Default port: 5000.

Request body:

{
  "market_id": "lagos",
  "item_name": "Imported Rice (50kg bag)",
  "submitted_price": 45000,
  "quality": 7,
  "amount": "50kg",
  "reporter_type": "local",
  "neighborhood": "Balogun",
  "dry_run": false
}

Request body:

{
  "image_base64": "<base64-encoded image>",
  "market_id": "lagos"
}

CSV files sourced from the FAO STAT database covering producer prices for West Africa, India, and France. These files live in backend/data/raw/ and provide the historical price floor used to anchor baselines.

Fetches annual CPI (FP.CPI.TOTL.ZG) and food price inflation (FP.FPI.TOTL.ZG) for Nigeria, India, and France. This inflation multiplier adjusts FAO baselines to account for macroeconomic conditions. Results are cached locally to avoid hitting rate limits.

Live humanitarian alert feed from ReliefWeb. The backend queries for active disaster events in each market's country and maps disaster types (drought, flood, cyclone, epidemic) to price category multipliers. Example: a drought raises staple food baselines by 35%.

Used for three distinct tasks:

1. Item identification - given a base64 image and market context, returns the identified item name and its expected price range
2. Price analysis - given a submitted price and baseline data, returns a fairness score, severity label, deviation percentage, and a culturally-adapted negotiation script
3. Market summaries - given a market's current deviation rate and flagged items, returns a paragraph of contextual analysis displayed on the market detail screen

Each market tracks 8 items covering staple foods, street food, and local merchandise.

Built for Hackalytics 2026.