Riftfound

A calendar view for Riftbound TCG events.

Quick Start

# Install dependencies
npm install

# Start dev servers (SQLite mode, no geocoding)
./dev.sh

# Or with PostgreSQL + Photon geocoder
./dev.sh --docker --photon

Frontend: http://localhost:5173

Project Structure

riftfound/
├── backend/          # Express.js API (port 3001)
├── frontend/         # React + Vite calendar UI (port 5173)
├── scraper/          # Event scraper (distributed across 60min cycles)
├── infrastructure/   # Docker, Photon, Terraform AWS deployment
├── dev.sh            # Development script
└── deploy.sh         # Production deployment script

Development

dev.sh Options

Flag	Description
(none)	SQLite mode, no Docker, no geocoding
--docker	Start PostgreSQL via docker-compose
--postgres	Use PostgreSQL for app (implies --docker)
--photon	Start Photon geocoder (first run downloads ~8GB)
--keep-docker	Keep Docker services running on exit
--reset	Delete all data (DB + Docker volumes)
--reset-db	Delete DB only (preserve Photon data)

Manual Commands

npm run dev:backend   # Start backend only
npm run dev:frontend  # Start frontend only
npm run dev:scraper   # Run scraper once
npm test              # Run all tests (Vitest)

API

Endpoint	Description
GET /api/events	List events with filtering
GET /api/events/:id	Single event
GET /api/events/info	Scrape stats
GET /api/events/geocode?q=	Geocode location

Query Parameters

• page, limit - Pagination
• search - Text search
• city, state, country - Location filters
• eventType - Event type filter (Summoner Skirmish, Nexus Night)
• lat, lng, radiusKm - Distance filtering
• calendarMode=true - Return all events in 3-month range

Architecture

• Database: SQLite for dev, DynamoDB for production. Controlled by DB_TYPE env var.
• Geocoding: Mapbox API (primary) with self-hosted Photon (OSM-based) as fallback for dev.
• Shops table: Geocoded store locations, events reference via shop_id
• Scraper: Runs every 60min cycle, fetches all ~30k events with requests distributed evenly across the cycle to avoid rate limiting

Deployment

Production runs on AWS serverless with Terraform:

• Frontend: S3 + CloudFront (HTTPS)
• Backend API: Lambda + API Gateway (via CloudFront)
• Scraper: Lambda + EventBridge (hourly)
• Database: DynamoDB

Deploy Commands

# First time setup
cp deploy.env.example deploy.env
# Edit deploy.env with your AWS values

# Deploy
./deploy.sh frontend        # React app to S3/CloudFront
./deploy.sh backend-lambda  # Backend API to Lambda
./deploy.sh scraper-lambda  # Scraper to Lambda
./deploy.sh lambdas         # Both backend and scraper to Lambda

See CLAUDE.md for detailed deployment and infrastructure docs.

License

Apache License 2.0 - see LICENSE