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
nextlink 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:
Geocentric server administrators can also execute a forced CLI sync when required.https://citylight.studio/citylight10c/vibemap_index.php
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 Field | Type | Description & Example |
|---|---|---|
recurs | Boolean | Flags whether the event repeats (true / false). |
recurrence | String (RFC 5545) | Complete recurrence definition with RRULE and optional EXDATE.Example: RRULE:FREQ=WEEKLY;UNTIL=20261105T055959Z;BYDAY=TU,TH |
recurrence_start_time | String (HH:MM:SS) | Local wall-clock starting time (e.g. 19:00:00). |
recurrence_end_time | String (HH:MM:SS) | Local wall-clock ending time (e.g. 22:00:00). |
duration | Integer (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
descriptionfield across all items—either 100% plain text or 100% sanitized HTML. Mixed payloads trigger PHP warnings on$resultsor corrupt CityLight layout containers.
3. De-publishing & Editorial Gates
- Only events with
is_approved = truein 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 / BID | Boundary Slug | Status & Implementation Notes |
|---|---|---|
| Downtown Nashville Partnership | downtown-nashville | Live since Aug 2026. Configured with 3-month past event window. |
| Yerba Buena Partnership (SF) | yerba-buena | Live. High-density arts and museum cultural calendar. |
| Downtown Tulsa | downtown-tulsa | Live. Cited by Geocentric as the benchmark implementation model. |
| Jack London Oakland | jack-london | Boundary endpoint delivered Sep 24, 2026; preview staging active. |
| Union Square Alliance (SF) | union-square | Hybrid architecture: Events powered by Vibemap, business directory via District360. |
| Bayside Village BID | bayside-village | Scoped 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).