Jax Events

Personal event-discovery web app for Jacksonville Beach, FL. Local-first (runs in your browser at localhost:3000), self-learning (ratings shift the recommendation weights), and portable to a real host later.

What it does

• Pulls real events from Cummer Museum (iCal), Florida Theatre (HTML), Meetup (iCal per group), and Ticketmaster (API). Per-source isolation: one broken source doesn't kill the others.
• List view sorted by Best Match score or Chronological order (toggle on the page)
• Calendar view with Week mode (wide rows, readable wrapped names) and Month mode (compact)
• Category icons for quick visual scanning (🎷 jazz, 🛶 kayak, 🧘 yoga, 🧠 philosophy, 🛠️ maker, …)
• 👍 / 👎 + 1–5 ★ after attending — the system learns what you actually enjoy
• Ongoing exhibitions (months-long) surface as evergreen suggestions, not calendar spam
• Filters: date range, free-only, max price slider, 28 categories, search, "hide 👎"

Add-a-tip flow (the social-media gap-filler)

When you see something good on Instagram, Facebook, an email forward, or a flyer, hit ＋ Add tip in the header. Paste the caption / description / pasted text into the modal, optionally add the source URL, and click Parse with AI.

Under the hood: a short call to Claude Haiku 4.5 extracts title, date+time (resolving relative dates like "this Saturday" against today), venue, address, city, URL, description, price, and categories. You then review and edit the extracted fields before saving — Claude isn't trusted unilaterally; you're the final say.

• Cost: ~$0.001 per tip (Haiku is cheap, prompt is short).
• API key: set ANTHROPIC_API_KEY in .env.local. Without it, the modal still works — you just fill the form manually.
• Privacy: the pasted text is sent to Anthropic's API; nothing else leaves your machine.

This is the deliberate workaround for the social-media scraping problem (IG/FB block scraping aggressively; APIs are owner-only or expensive). You see the post on your phone, hit Add tip, paste — 10 seconds of friction, no scraping infrastructure, no missed events.

Setup

cd ~/jax-events
npm install
cp .env.example .env.local        # contains a curated starter list of Meetup groups
npm run seed                       # load verified-real Jacksonville-area events
npm run dev                        # open http://localhost:3000

Click ↻ Refresh in the UI to pull live data from all configured sources.

API keys & config

.env.local controls everything. Suggested keys to add:

Source	Required?	How to get	Free tier
Cummer Museum	nothing	iCal feed, public	unlimited
Florida Theatre	nothing	HTML scrape, public	unlimited
Meetup	nothing	iCal per group, public	unlimited
Ticketmaster	optional API key	https://developer-acct.ticketmaster.com/user/register	5,000 calls/day

MEETUP_GROUPS in .env.local controls which Meetup groups get scanned. Add or remove slugs (the part after meetup.com/) freely.

Match score, explained

The number on each event card is a Match score (0–100+, higher = closer fit to your tastes). Not stars. Stars (★ 1–5) only appear when you mark an event attended and rate it.

match = avg(category_weights for the event)
      + venue_affinity_bonus           (learned per-venue bump)
      + source_affinity_bonus          (learned per-Meetup-group bump)
      + 8 if free
      + 15 if tagged 'experiential'
      − 25 if tagged ONLY 'market-shopping'
      − 10 if it's an evergreen ongoing place
      + distance_penalty               (0 / −3 / −15 / −30, source-modified)

Color cues on the card: green ≥ 80, blue ≥ 50, slate ≥ 20, faded otherwise.

Distance & driving radius

Every event lands in one of four buckets based on its city:

Bucket	Penalty	Includes
Local	0	Jacksonville, Jax Beach, Atlantic/Neptune Beach, Ponte Vedra, Mayport
Nearby (~1 hr)	−3 (or ~−5 for meetups)	St Augustine, Fernandina, Amelia, Orange Park, Fleming Island
Drive (1–3 hr)	−15 (or ~−22 for meetups)	Daytona, Gainesville, Ocala, Brunswick GA, St Simons
Far (3+ hr)	−30 (or ~−45 for meetups)	Orlando, Tampa, Miami, Pensacola, Tallahassee, …

The Driving radius filter in the sidebar hard-filters to events in or below the selected bucket. Default is "Nearby" (Jax metro + 1-hour cities).

Distance penalties are stronger for Meetups (small events) and lighter for destination venues like Florida Theatre or Daily's Place — those "earn" the drive.

Each card also shows an approximate drive distance from the corner of Beach Blvd & 3rd St S, Jacksonville Beach (change via HOME_LAT / HOME_LON in .env.local). This readout is local-only — the public build hides it, since a distance measured from one fixed point is misleading to a visitor who could be anywhere. Values prefixed with ~ mean the venue had no exact coordinates and we used city-center as a fallback — click Directions on the card for Google's actual ETA. Tap the 📍 venue line to open Google Maps, or Directions to start navigation.

Five feedback states

Action	What it does	Card treatment
👍 Interested	+2 to every category on the event, +1 to venue	Green border + "✓ You marked this Interested"
📅 Register	Marks "I signed up / bought a ticket". Doesn't shift weights. Surfaces in iCal export.	Violet border + "📅 You're registered for this"
👎 Not for me	−2 to every category, −1 to venue	Faded
🚗 Too far for this	Penalizes the source/group by −8 and venue by −8. Does NOT touch category weights.	Faded
✓ I went to this + ★ 1–5	(stars − 3) × 4 to every category; half that to the venue	Blue border, persistent star count

All clicks are optimistic — the card updates instantly, then the list refetches in the background, so positions don't jump while you're rating.

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗