SearchThursday email
Menu

Engineering

How Around Lex is built

Around Lex is a guide to events, places and plans in Lexington, Kentucky. This page explains how the website works, for readers who like to know and for people who build websites themselves.

Pages are built on the server

When you open a page, a small program on the server assembles the HTML from a reviewed catalog and sends the finished page. Your browser does not download an application to run the site. Links are links, filters are ordinary form fields, and the address bar always holds a page you can share. The few features that use JavaScript, such as the optional map and the save-on-this-device list, work without it and add the extra only when your browser allows it.

The catalog is a set of files

Every event, place and guide is a record in the project's source files, with the official source it came from and the date it was last checked. Changes go through review before they are published, and the project history shows what changed and when. There is no content database behind the public pages to slow down, break or fall out of sync.

Unknowns get written down

When an official page is offline or two official sources disagree, the record gets a question with a next step instead of a best guess. An event with an open schedule question stays visible with a warning, but it leaves the date lists, the calendar downloads and the structured data that search engines read until the question is resolved. A listing with a date but no published time says "Time to be confirmed" rather than inventing one.

Lexington time is the only time

Dates and times are calculated in the Eastern time zone, including the daylight saving change, using the Temporal date library. Calendar downloads are converted from Lexington time so they land in the right hour wherever you import them.

Speed is tested on release builds

Release checks run on the development computer before the finished files are uploaded to hosting. The checks stop if unit tests, the content audit or the type check fail. Browser tests walk the site at desktop, phone and 320-pixel widths. Lighthouse, the open-source auditing tool, checks 28 representative pages on a simulated phone and a desktop, three times each; the newsletter adds another page when enabled. Every measurement must score 100 in performance, accessibility, best practices and search readiness. A saved record ties passing checks to the reviewed source. The upload command refuses changed source or changed build files, and the live site reports the commit it was built from.

Photographs carry their paperwork

The real photographs on the site come with a recorded license, author and source, and a fingerprint of the original file. Every build re-checks those fingerprints and stops if a file has changed without a rights review. Event pages use original artwork instead of posters, because posters belong to the people who made them.

The map waits for you

Street maps load only after you choose to load them, from the project's own copy of the Leaflet library, with tiles from OpenStreetMap. The site never asks for your location; directions open as ordinary Google Maps links, and you choose the starting point there.

Forms are private and small

Event suggestions, corrections and partnership requests go to a review queue, never straight to a page. When the queue is not connected, the form offers an email address instead of pretending to work. Newsletter signup stays closed until the mailing provider is connected.

Hosting is separate from testing

Tests and builds run locally to avoid paid build minutes. The public site still uses hosted servers and storage. Fonts and images are served from the site itself, and optional integrations stay switched off until configured, with the pages saying so.

The catalog right now

These numbers are counted from the catalog when this page is served.

Events
484
Dates listed across those events
870
Places
217
Guides
54
Events with a known price
45%219 of 484 events carry a lowest ticket price, free ones included.
Median time since a listing was last checked
2 daysAcross events, places and guides.
Official pages cited
795Distinct addresses cited by events, places, plans, recurring groups and festivals.
Upcoming dates marked cancelled or postponed
00 cancelled and 0 postponed. Their event pages still show them, with the status.
Dates moved, with the earlier date recorded
1
Recurring groups with a current schedule
350 groups past the date their schedule was checked through.
Open source questions
197 date questions on events, 12 visitor detail questions on places.

The version you are reading

This copy of the site was built from commit b4dd145 in the project's history. The health check at /api/health reports the same value, with the hosting deployment it belongs to.

Feeds you can subscribe to

Each of the 217 places also has its own calendar: add .ics to the end of its page address. The feeds page explains how to subscribe in Apple Calendar, Google Calendar and Outlook.

The same catalog is also a read-only JSON API with an OpenAPI description. The developer page lists every endpoint with a live example and the terms for reusing the data.

Architecture notes

The architecture notes and decision records are kept with the code. The repository is private for now and will be opened later. Our listing standards cover what gets listed and how it is checked.