Skip to content
BranchesTags

Repository files navigation

T3(1)

PriceLens

Live Price Comparison Platform

Real-time price aggregation from live API sources
Stack: Next.js 16.2 + TypeScript + DynamoDB + MCP
Data: Fetched live from Alpha Vantage, Best Buy, and Ticketmaster APIs

🏆 What It Does

PriceLens aggregates live prices from real API sources across electronics, events, and finance. No fake data, no mock prices — every price shown is fetched in real-time from the source's official API.

The Problem: Product research means checking 5+ websites to find the best price. Most comparison tools either use stale data or scrape without permission.

The Solution: PriceLens uses official developer APIs to fetch real-time pricing data, organized into a clean comparison dashboard with automated price alerts.

  • Live price comparisons — real prices from Best Buy, Ticketmaster, Alpha Vantage
  • Smart deal finding — find the cheapest source instantly
  • Automated price alerts — get notified when prices drop to your target
  • MCP-native integration — query pricing from Claude, Cursor, or Cline

Product Categories

Category What We Track Data Source API
📱 Electronics Laptops, phones, headphones Best Buy (live) developer.bestbuy.com ✅
🎫 Events Concerts, sports, theme parks Ticketmaster (live) developer.ticketmaster.com ✅
📈 Finance Stocks, forex, crypto, commodities Alpha Vantage (live) alphavantage.co ✅
✈️ Flights Round-trip airfare Integration coming ⏳
🏨 Hotels Per-night room rates Integration coming ⏳

🗺️ Live Data Architecture

Prices flow through a pluggable DataSource adapter system (src/lib/sources/):

Next.js API Routes
      │
      ▼
   db-adapter.ts
      │
      ├── DynamoDB (if AWS keys configured)
      └── MemoryStore (local)
              │
              ▼
   PriceFetcher orchestrator
      │
      ├── Alpha Vantage API ──→ finance (free, 25 req/day)
      ├── Best Buy API ──────→ electronics (free, instant signup)
      └── Ticketmaster API ──→ events (free, 5,000 req/day)

Each source:

  1. Checks if its API key is configured in .env.local
  2. Fetches live prices when called
  3. Caches results with TTL to respect rate limits
  4. Gracefully degrades when no API key is set (shows setup guidance)

To add a new source: implement the DataSource interface, register it in price-fetcher.ts, add the env var to .env.example, and add the SourceInfo to types.ts.

🛢️ AWS Database: Amazon DynamoDB (Optional)

PriceLens works with an in-memory store by default (no AWS required). When AWS credentials are configured in .env.local, it transparently switches to DynamoDB.

Data Model (3 Tables)

Products (sku: HASH)
├── name, category, tags, baseSpecs
└── 27 products across 5 categories

Prices (sku: HASH, source: RANGE)
├── pricePerUnit, unit, currency, timestamp, sourceType
└── Fetched live from API sources

Alerts (userId: HASH, alertId: RANGE)
├── sku, targetSource, targetPrice, createdAt
└── User-specific price drop notifications

Provisioning

# Via AWS CLI
chmod +x scripts/provision-dynamodb.sh
./scripts/provision-dynamodb.sh

# Or CloudFormation
aws cloudformation deploy \
  --template-file infra/dynamodb-template.yaml \
  --stack-name pricelens-dynamodb \
  --capabilities CAPABILITY_IAM

🧠 MCP Server (9 Tools)

Connect any MCP-compatible client (Claude Desktop, Cursor, Cline):

Tool What It Does
search_prices Search products by keyword/category across all sources
compare_sources Full price comparison across merchants/airlines/sites
find_best_price Find the cheapest source with savings percentage
list_categories Browse product categories with counts
list_products_by_category Products with specs in a category
set_price_alert Create automated price drop alerts
list_alerts View active alerts for any user
delete_alert Remove a price alert
get_source_overview Complete pricing summary per merchant/airline

Claude Desktop Configuration

{
  "mcpServers": {
    "pricelens": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/pricelens/src/mcp-run.ts"],
      "env": {
        "ALPHA_VANTAGE_API_KEY": "your-key",
        "BESTBUY_API_KEY": "your-key",
        "TICKETMASTER_API_KEY": "your-key"
      }
    }
  }
}

🚀 Quick Start

Prerequisites

  • Node.js 18+
  • npm 9+
  • AWS account (optional — in-memory mode works without)

1. Clone & Install

git clone https://github.com/LSUDOKO/PriceLens
cd PriceLens
npm install

2. Configure API Keys (Required for live prices)

cp .env.example .env.local

Get your free API keys:

Without API keys, the app shows the product catalog with a setup guide. No fake data is displayed.

3. Start

# Start the web dashboard
npm run dev
# → http://localhost:3456

# Seed the product catalog (not prices — those come from live APIs)
curl -X POST http://localhost:3000/api/seed

4. Verify live data is flowing

# Health check shows source configuration
curl http://localhost:3000/api/health | jq

# Prices will populate once API keys are configured
# and the first API call triggers a live fetch

🖥️ Frontend Pages

Price Explorer (/)

Search, filter, and sort 27 products across 5 categories. See live prices from configured API sources. Each product card shows its price range, best deal, and expandable source breakdown. When no API keys are configured, a setup banner guides you to add them.

Source Comparison (/heatmap)

Visual overview of live API sources color-coded by average price. See which sources are cheapest (green) vs most expensive (red). Summary cards show the cheapest source, most expensive, and price spread.

Price Alerts (/alerts)

Full CRUD interface for price alerts. Search products with autocomplete, set target prices, choose specific sources or track all. Alerts trigger webhooks when live prices cross your threshold.

🔌 API Routes

Route Method Description
/api/seed GET/POST Seed product catalog (prices come live from APIs)
/api/health GET Health check + source status + cache age
/api/prices GET Query products/prices by SKU, source, category
/api/alerts GET/POST/PUT/DELETE Full CRUD for price alerts
/api/check-alerts GET/POST Manual alert check trigger (auth-protected)

🏗️ Architecture

View the interactive architecture diagram for a visual representation of the full stack.

┌─────────────────────────────────────────────────────┐
│                   Claude Desktop                     │
│              (or any MCP Client)                     │
└──────────────────────┬──────────────────────────────┘
                       │ stdio (JSON-RPC)
                       ▼
┌─────────────────────────────────────────────────────┐
│                   PriceLens                          │
│    ┌─────────────┐  ┌────────────┐  ┌───────────┐  │
│    │ Next.js API │  │MCP Server  │  │Price      │  │
│    │ Routes      │  │(9 Tools)   │  │Fetcher    │  │
│    └──────┬──────┘  └─────┬──────┘  └─────┬─────┘  │
│           │               │               │          │
│           ▼               ▼               ▼          │
│    ┌──────────────────────────────────────────┐     │
│    │           db-adapter.ts                   │     │
│    │  ┌──────────┐  ┌─────────────────┐      │      │
│    │  │DynamoDB  │  │MemoryStore      │      │      │
│    │  │(Optional)│  │+ TTL Cache      │      │      │
│    │  └──────────┘  └────────┬────────┘      │      │
│    └─────────────────────────┼────────────────┘      │
│                              │                        │
│    ┌─────────────────────────▼────────────────┐      │
│    │     PriceFetcher                          │     │
│    │  ┌──────────┐ ┌────────┐ ┌────────────┐  │     │
│    │  │Best Buy  │ │Ticket  │ │Alpha       │  │     │
│    │  │API       │ │master  │ │Vantage API │  │     │
│    │  │(live)    │ │API     │ │(live)      │  │     │
│    │  │          │ │(live)  │ │            │  │     │
│    └─────────────┘ └────────┘ └────────────┘       │
└─────────────────────────────────────────────────────┘

Key Design Decisions

  1. Pluggable Data Sources: Every live API source implements the DataSource interface. Add new sources by creating an adapter and registering it.

  2. No Fake Data: Zero hardcoded prices. Every price is fetched live from official APIs. When no API key is configured, the app shows setup guidance — never fake data.

  3. TTL Caching: Results are cached in memory with configurable TTLs (15 min for finance, 30 min for electronics, 1 hour for events) to respect API rate limits.

  4. Graceful Degradation: Each source adapter checks for its API key. Missing keys = empty data = clear UI guidance. No crashes, no errors.

  5. MCP First: The MCP server runs on the same db-adapter layer as the web UI. Every API endpoint is also accessible as an MCP tool.

🔧 Deploy to Production

Vercel

Deploy with Vercel

Set these environment variables in Vercel:

  • ALPHA_VANTAGE_API_KEY
  • BESTBUY_API_KEY
  • TICKETMASTER_API_KEY
  • NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY
  • CLERK_SECRET_KEY
  • AWS_ACCESS_KEY_ID (optional)
  • AWS_SECRET_ACCESS_KEY (optional)
  • AWS_REGION (optional)

AWS DynamoDB (Optional)

./scripts/provision-dynamodb.sh
aws dynamodb list-tables --region us-east-1
# → pricelens-products, pricelens-prices, pricelens-alerts

🧪 Development

# Type check
npm run typecheck

# Lint
npm run lint

# Run tests (24 unit tests)
npm run test

# Watch mode
npm run test:watch

# MCP server (for AI client integration)
npm run mcp

📝 License

MIT

🙏 Acknowledgments

  • Uses Alpha Vantage API for live financial data
  • Uses Best Buy Developer API for live electronics pricing
  • Uses Ticketmaster Discovery API for live event pricing
  • Uses Amazon DynamoDB for persistent storage (optional)
  • Uses Next.js 16.2 + Vercel for frontend deployment

About

live prices from real API sources across electronics, events, and finance. No fake data, no mock prices — every price shown is fetched in real-time from the source's official API.

Topics

awsbuy-at-lowest-pricecompare-productlive-market-feed

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages