Skip to main content

CityLight (Geocentric) CMS Integration Guide

Automated events engine and boundary syndication for Business Improvement Districts (BIDs).

Executive Overview & Value Proposition​

CityLight is Geocentric's specialized website CMS for downtown improvement districts, urban partnerships, and BIDs. Keeping a downtown website calendar populated with hundreds of monthly events is typically a full-time, labor-intensive chore.

Vibemap powers CityLight with automated, boundary-safe event intelligence:

  • Boundary Precision: Events are strictly filtered by polygon boundary slugs (e.g. downtown-nashville, jack-london), ensuring out-of-district events never slip onto the BID's website.
  • Zero-Touch Publishing: CityLight pulls directly from Vibemap's public v0.3 events API, formatting listings natively in CityLight templates.
  • Recurring Event Precision: Native support for complex RFC 5545 recurrence rules (RRULE), preserving weekly trivia, farmers markets, and theater runs without database bloat.
  • Editorial Control: Moving an event to "Pending" in the Vibemap Hub automatically suppresses it on the CityLight website on the next sync cycle.

Integration Architecture & Data Flow​

flowchart LR
A["Vibemap Hub\n(Editorial Verification)"] -->|"v0.3 Events API\n?boundary=<slug>"| B["Geocentric Importer\n(vibemap_process_events.php)"]
B -->|"GeoJSON Parsing &\nRecurrence Expansion"| C["CityLight Storage\n(Database)"]
C --> D["Public District Website\n(e.g. nashvilledowntown.com)"]
E["District Staff / Vibemap"] -.->|"On-Demand Trigger\nUpdate Now Button"| B

1. Ingestion Endpoint​

Vibemap exposes a boundary-scoped REST GeoJSON endpoint for each district:

GET https://api.vibemap.com/v0.3/events?boundary=<slug>&is_approved=true

(Examples: boundary=downtown-nashville, boundary=jack-london).

2. Importer Execution (vibemap_process_events.php)​

Geocentric maintains a unified PHP importer script across all Vibemap clients:

  • The importer requests the boundary endpoint and walks paginated responses using the next link in the JSON payload.
  • It parses the GeoJSON FeatureCollection (results.features) and translates coordinates, metadata, taxonomy, and recurrence rules into CityLight's internal database tables.
  • Published pages render natively under the district's domain (e.g. nashvilledowntown.com/event/<slug>).

3. Sync Triggers & Frequency​

  • Nightly Automated Run: The importer executes once every 24 hours in the early morning.
  • Manual "Update Now" Trigger: District staff or Vibemap can trigger an immediate manual resync at:
    https://citylight.studio/citylight10c/vibemap_index.php
    Geocentric server administrators can also execute a forced CLI sync when required.

Recurring Events Specification (RFC 5545)​

A major strength of the Vibemap-CityLight bridge is its native handling of repeating schedules. Vibemap supplies standard iCalendar RFC 5545 recurrence metadata on every event series:

Feed FieldTypeDescription & Example
recursBooleanFlags whether the event repeats (true / false).
recurrenceString (RFC 5545)Complete recurrence definition with RRULE and optional EXDATE.
Example: RRULE:FREQ=WEEKLY;UNTIL=20261105T055959Z;BYDAY=TU,TH
recurrence_start_timeString (HH:MM:SS)Local wall-clock starting time (e.g. 19:00:00).
recurrence_end_timeString (HH:MM:SS)Local wall-clock ending time (e.g. 22:00:00).
durationInteger (Seconds)Duration in seconds (e.g. 10800 for 3 hours).

CityLight's parser reads the RRULE string to calculate and display future occurrences on calendar views without requiring hundreds of redundant database rows.


Performance Tuning & Troubleshooting SOPs​

1. Past-Event Windowing​

  • Issue: CityLight does not automatically delete past events; it only displays what the feed provides. Retaining 365 days of historical events caused sync payloads to balloon, resulting in HTTP 504 timeouts.
  • Fix: Vibemap introduced a configurable past-event window. For Downtown Nashville, reducing the historical window to 3 months (Sep 21, 2026) drastically slashed payload size and cut sync times from 7 minutes to under 45 seconds.

2. Description Formatting Standards​

  • Standard: Geocentric requires a consistent format for the description field across all items—either 100% plain text or 100% sanitized HTML. Mixed payloads trigger PHP warnings on $results or corrupt CityLight layout containers.

3. De-publishing & Editorial Gates​

  • Only events with is_approved = true in the Vibemap Hub are included in the feed.
  • To unpublish an event immediately: change its status from "Approved" to "Pending" in the Vibemap Hub and click Update Now in the CityLight studio console.

Client Implementations​

Client / BIDBoundary SlugStatus & Implementation Notes
Downtown Nashville Partnershipdowntown-nashvilleLive since Aug 2026. Configured with 3-month past event window.
Yerba Buena Partnership (SF)yerba-buenaLive. High-density arts and museum cultural calendar.
Downtown Tulsadowntown-tulsaLive. Cited by Geocentric as the benchmark implementation model.
Jack London Oaklandjack-londonBoundary endpoint delivered Sep 24, 2026; preview staging active.
Union Square Alliance (SF)union-squareHybrid architecture: Events powered by Vibemap, business directory via District360.
Bayside Village BIDbayside-villageScoped and queued for onboarding.

Future Roadmap​

  • Parent Events & Occurrences: Geocentric is evolving CityLight storage to model parent events with linked occurrence instances, allowing festival multi-day schedules to share a single canonical landing page.
  • Multi-Source Hybrid Ingestion: Exploring CityLight-authored local events merging with Vibemap's scraped district events.
  • Key Contacts: Jim Blakeslee, Melanie Charlton (Geocentric).