City Pulse MN
A hub for everything happening across the Twin Cities metro — both downtowns plus all first- and second-ring suburbs (Plymouth, Maple Grove, Bloomington, Edina, Woodbury, and the rest). A calendar, a Mapbox map, category filters (music, sports, family, arts, food, unique, festival), live text search, full event detail, and shareable event/day pages, in the City Pulse MN brand. Privacy-friendly analytics (Vercel). Password-protected admin dashboard. Row-level-security hardened. Weekly Instagram content generator. Email capture with owned subscriber list. Add-to-calendar (.ics + Google). Price & area filters. Curated collection landing pages. Weekly email digest. Community event submissions with admin moderation. Saved events (per-visitor list, no login). Content-based event classification. Venue-anchored discovery. Coverage monitor. Multi-day event handling. Freshness re-verification. Time integrity (all-day events, normalized timezones). Title hygiene (display-clean titles, canonical city names). First-party analytics (event_stats, admin engagement dashboard). Trending (decayed, intent-weighted ranking on the homepage and collections). Personalized digest (leads with each subscriber's saved events). Saved-list durability (signed magic links, cross-device merge). Neighborhoods (coordinate-derived districts with browse pages). Venue pages (registry-derived schedule pages with maps and Place JSON-LD). City landing pages (metro-wide, thin-content-guarded). Evergreen /this-weekend page (weekend clock, day-grouped). Instagram card generator (locked-rules admin tool). Responsive — tuned for laptop and phone. SEO-ready: schema.org event data, sitemap, and branded share cards.
Live at citypulsemn.com — hosted on Vercel, with the GoDaddy-registered domain pointed at it.
Events are kept fresh by an automated weekly pipeline: AI research agents find events, normalize and geocode them, and upsert them into Postgres; the website reads published rows. The database is the boundary between the two — see docs/ARCHITECTURE.md.
Stack
- Next.js 15 (App Router) + React 19 + TypeScript — website
- Postgres (Supabase or Neon) — events database
- Mapbox GL — map (client) + geocoding (server)
- Anthropic Claude (
@anthropic-ai/sdk) — research agents with web search
- GitHub Actions — weekly cron (Trigger.dev optional alternative)
- Deploy: Vercel (domain citypulsemn.com via GoDaddy DNS)
Quickstart
npm install
npm run dev # http://localhost:3000 (runs on bundled sample data)
Add DATABASE_URL and Mapbox/Anthropic keys to go live. Full path: docs/SETUP.md.
Scripts
npm run dev # website (dev)
npm run build # type-check + build the site
npm test # unit tests (25): window logic, dedup key, price tiering
npm run pipeline # run the weekly research pipeline once (needs env)
Documentation
| Doc | What's in it |
|---|
| DEPLOY-WALKTHROUGH.md | The friendly, detailed, no-experience-assumed version — every concept and click explained |
| ARCHITECTURE.md | System overview, the master flow diagram, where everything lives |
| DATABASE.md | Schema, the dedup key, lifecycle, time zones, provisioning Supabase/Neon |
| PIPELINE.md | The weekly automation: agents, normalize, upsert, auto-publish & hiding, scheduling |
| CONNECTORS-AND-TOOLS.md | Every external service, env var, and where to get each key |
| SETUP.md | Zero-to-live runbook with a verify checklist and troubleshooting |
Project structure
app/ Website (Next.js App Router)
components/ Calendar, map, filters, detail panels
lib/
events.ts READ boundary (Postgres → EventRecord, sample fallback)
db.ts Postgres connection (Supabase/Neon)
event-key.ts Dedup key + price tiering (tested)
geocode.ts Mapbox geocoding
upsert.ts WRITE boundary (idempotent upsert + archive)
agents/ Research subagents (Claude + web_search) + prompts
dates.ts Calendar/window logic (tested)
scripts/run-pipeline.ts The weekly orchestrator
db/schema.sql Database schema
.github/workflows/ Weekly cron
examples/trigger-alternative/ Optional Trigger.dev version of the pipeline
Environment
See .env.example. Website needs DATABASE_URL + NEXT_PUBLIC_MAPBOX_TOKEN; the pipeline also needs ANTHROPIC_API_KEY + a Mapbox geocoding token. Full matrix in CONNECTORS-AND-TOOLS.md.
