Community Calendar

Public events are trapped in information silos. The library posts to their website, the YMCA uses Google Calendar, the theater uses Eventbrite, Meetup groups have their own pages. Anyone wanting to know "what's happening this weekend?" must check a dozen different sites.

Existing local aggregators typically expect event producers to "submit" events via a web form. This means producers must submit to several aggregators to reach their audience — tedious and error-prone. Worse, if event details change, producers must update each aggregator separately.

This project takes a different approach: event producers are the authoritative sources for their own events. They publish once to their own calendar, and individuals and aggregators pull from those sources. When details change, the change propagates automatically. This is how RSS feeds work for blogs,iCalendar can do the same for events.

The gold standard is iCalendar (ICS) feeds — a format that machines can read, merge, and republish. If you're an event producer and your platform can publish an ICS feed, that's great. But ICS isn't the only way. The real requirement is to embrace the open web. A clean HTML page with well-structured event data works. What doesn't work: events locked in Facebook or behind login walls.

XMLUI App: https://judell.github.io/community-calendar/

Feed Health Report: https://judell.github.io/community-calendar/report.html

Interactive architecture explainer — click through the 7 pipeline phases to see how data flows from sources to the frontend.

ICS feeds, web scrapers, and curator picks are collected daily by GitHub Actions, combined and deduplicated per city, converted to JSON, classified by Claude AI, and loaded into Supabase. The XMLUI frontend queries the deduplicated materialized view and renders events. See docs/pipeline.md for the full pipeline details.

A curator builds and maintains the calendar for their community. You don't create events — you discover and connect existing event sources: find organizations publishing calendars, test that feeds work, add them to the aggregator, and filter out noise. The goal is a comprehensive, low-maintenance calendar that updates automatically. See docs/curator-guide.md for the full playbook.

• Event pipeline — ICS feeds, scrapers, deduplication, source attribution. docs/pipeline.md
• Event classification — AI-powered categorization with curator overrides. docs/pipeline.md
• Search and snippets — Client-side filtering with scored description snippets. docs/search-and-performance.md
• Personal picks — Save events, subscribe via personal ICS feed. docs/picks.md
• Event capture — Photograph a poster or speak event details. docs/audio-capture.md
• Recurrence enrichment — Curators attach recurrence rules visible to all users. docs/recurrence.md

Know of a local calendar that should be included? Open an issue with the feed URL and a link to the events page. If you're comfortable with pull requests, you can also add the feed directly to cities/{city}/feeds.txt — see the issue template for the format.

• App architecture: docs/app-architecture.md — XMLUI components, local dev setup, resources
• Testing: Python and database tests via make test and make test-sql. tests/TEST_SUITE.md — Python tests and Supabase-native pgTAP database tests run in CI on PRs
• Frontend tests: Browser-based unit tests in test.html; regression tests via trace-tools. docs/regression-testing.md
• Adding a city: docs/curator-guide.md (discovery) and AGENTS.md (technical steps)
• Contributing: CONTRIBUTING.md — how to add feeds and submit PRs
• Adding sources: docs/procedures.md — feed discovery, testing, geo-filtering
• Supabase: supabase/README.md — schema, edge functions, auth, RLS
• Scrapers: scrapers/README.md — scraper library and per-site docs
• Timezones: docs/timezone.md — ICS timezone handling conventions
• Deduplication: docs/deduplication.md — dedup implementation details
• AI agents: AGENTS.md — operating guide for AI agents working on this codebase

.github/workflows/      # GitHub Actions automation
cities/                 # Per-city data (feeds.txt, SOURCES_CHECKLIST.md)
cli/                    # CLI tools
docs/                   # Detailed documentation
scrapers/               # Event scrapers for sites without ICS feeds
scripts/                # Build and utility scripts (combine_ics, ics_to_json, classify, etc.)
supabase/               # DDL docs, edge functions (load-events, my-picks, capture-event)
xmlui/                  # XMLUI app (Main.xmlui, Globals.xs, components/, helpers.js)
tests/                  # Python test suite and repo-level testing docs