📚 BiblioStatus

BiblioStatus is a web app that shows the real-time opening status of Finnish public libraries on a map.

🔍 Features

The map

• 🌍 Interactive map with open / self-service / closed / closed-all-day statuses colour-coded, recomputed every minute from the day's opening hours, so a library that opens while the page is open changes colour without a reload
• 📍 Find Nearest Open Library - uses GPS to find the 3 (phone) or 5 (desktop) closest open libraries with distances; respects a selected service ("the nearest open library with a sauna")
• 🌗 Light and dark mode (light by default; the map follows)
• 📱 Mobile-optimized layout with responsive sidebar and touch controls

Finding a library

• 🔎 Search All Libraries - type part of a name and pick a library in any city; the map jumps to it
• 🏢 City / municipality filter, including All Cities to see every library at once
• 🏷️ Service filter - 240+ services; the service and library lists follow the city (and service) you picked, and a short notice says so when a choice no longer fits and is cleared
• 🔗 Shareable links - the filters are in the page address (?city=Espoo&service=Sauna&library=123), so a link restores a view and a reload keeps it
• 📊 Service Statistics tab - how common each service is, per city, as a chart and a table

A library's details

• 📅 Complete daily schedule (e.g. "10:00-14:00 Open, 14:00-20:00 Self-service"), with the current period marked
• 📞 Phone and e-mail links (only for values that look like a phone number or address), 🔗 the library's website, and 🗺️ one-click Google Maps directions
• 💎 Services listed for the library

Reliability

• 📦 Data from the Kirkanta API is updated nightly via GitHub Actions and stored in Turso (cloud SQLite) with a SQLite backup in the app
• 🔌 If the connection to the server is lost for good (the device slept, the network dropped) the page says so and offers Reload; a short drop reconnects by itself without a word
• 🛟 If the database is unreachable the page says so: it shows the last good data (marked with its time), the nightly backup, or a plain message, instead of failing silently
• 🩺 GET /health for uptime monitoring, with a Cloud Monitoring check and an e-mail alert
• ✅ Automated URL monitoring with an e-mail alert for broken links

📸 Screenshot

🚀 Live App

👉 Try it here!

🛠️ Project Structure

fetch_library_data.R        # The data pipeline (Kirkanta API v4 -> Turso + SQLite backup)
check_library_urls.R        # Validates all library URLs
R/                          # Pipeline code the app shares or tests
├── turso.R                 # Turso HTTP API: reads (with timeout and retry), all-or-nothing writes
├── schedules.R             # The 7-day window, parsing the API's schedules, how the window is written
├── library_write.R         # Replacing the libraries and services in one transaction
├── coordinates.R           # Which coordinates to believe (override > API > last good snapshot)
└── backfill_historical_data.R  # Backfill historical schedules
data/                       # Manual corrections and the coordinate snapshot (CSV)
├── library_url_overrides.csv, library_coordinate_overrides.csv, library_exclusions.csv
└── library_coordinates.csv # Last good coordinates of every library (kept up to date by the weekly run)
app/
├── run.R                   # Entry point: security headers, /health, host and port
├── global.R, server.R, ui.R
├── server/                 # data (loading, reloading), filters, url (the address), map, panels
├── modules/service_stats.R # The Service Statistics tab
├── libraries.sqlite        # SQLite backup (written by the pipeline)
├── lib/                    # The R code (not in www/, which Shiny serves to anyone)
│   ├── functions.R         # Database queries, status calculation, map drawing, popups
│   ├── data_layer.R        # get_app_data(): never throws, shared cache, stale/backup states
│   ├── filter_logic.R      # The dropdown rules (no Shiny in it), the search box, the address
│   ├── health.R, security.R # /health and the security headers (including the CSP)
│   ├── strings.R           # All user-facing text
│   └── variables.R         # Colours, map settings, cache and reload times
└── www/                    # What the browser may fetch
    └── app.js, mode-toggle.js, styles.css, favicon.png
tests/testthat/             # The test suite (about 1,500 expectations)
.github/workflows/          # tests, fetch_data, check_library_urls, deploy_shiny_app
infra/, fixes/              # Artifact Registry cleanup policy, the monitoring setup script
schema.sql, Dockerfile, docker-compose.yml, deploy.sh, renv.lock

CLAUDE.md describes how the pieces fit together (for people and for Claude Code), and bibliostatus-refactor-plan.md is the record of the 2026-10 refactor.

🔄 Data Pipeline

Daily schedule update (2:00 AM UTC; GitHub often starts the job a few hours late):

1. GitHub Actions runs fetch_library_data.R in "schedules" mode
2. Fetches seven days of opening hours (today and the six days after, by the Finnish date) from the Kirkanta API (v4) - the days ahead are already stored when midnight comes, so there is a status from the first minute of the day
3. Replaces that window in Turso a group of libraries at a time, each group in one transaction, so a page loaded meanwhile always sees a library's old hours or its new ones, never none; history before today is kept
4. Writes the whole window to libraries.sqlite as the backup

Weekly library update (Sunday 2:00 AM UTC):

This is the beginning of the README. Read the rest at the original. Read the full README ↗