Skip to content

CLAUDE.md

Latest commit

 

History

History
109 lines (77 loc) · 4.61 KB

CLAUDE.md

File metadata and controls

109 lines (77 loc) · 4.61 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

bcchildcarebot is a Quarto dashboard for exploring BC childcare facilities with open vacancies. It pulls data from the BC Child Care dataset published by the BC government and is published to GitHub Pages at this link: https://victoryuan.com/bcchildcarebot/ .

Development Environment

Setup

  • Dependency Management: renv - run renv::restore() after cloning to restore packages
# Restore R dependencies
Rscript -e "renv::restore()"

Common Development Commands

Render the dashboard locally:

quarto render dashboard.qmd
# Opens dashboard.html in browser

In RStudio:

  • Open dashboard.qmd and use "Render" button for interactive development

Architecture

Dashboard (dashboard.qmd)

The Quarto dashboard uses crosstalk for client-side interactivity without server overhead:

  • Data Loading: Fetches CSV directly from BC government API on render
  • Filters: City, service type, language, certifications, vacancy status via crosstalk widgets
  • Map View: Leaflet map with popup markers showing facility details and vacancy info
  • Table View: Reactable showing facility listings with vacancy columns
  • Styling: custom.scss defines dashboard theme colors and layout

Key R libraries:

  • tidyverse: Data manipulation and visualization
  • reactable: Interactive table rendering
  • leaflet: Interactive maps
  • crosstalk: Client-side filtering across widgets
  • htmltools: HTML generation for popups

GitHub Actions / Automation

publish.yml

  • Trigger: Push to main branch, manual dispatch, or daily at 3:41 PM UTC (8:41 AM PST)
  • Process: Renders dashboard.qmd → publishes to gh-pages branch
  • Deployment: Accessible at https://victoryuan.com/bcchildcarebot/

update_history.yml

  • Trigger: Daily at 3:10 PM UTC (30 min before publish)
  • Process: Runs update_history.R → commits updated data/vacancy_history.csv

find_urls.yml

  • Trigger: Monthly on the 1st at 4:00 PM UTC, manual dispatch
  • Process: Runs find_urls.R → commits updated data/facility_urls.csv
  • Tuning: Set DDG_THROTTLE_SECS, DDG_BATCH_SIZE, DDG_RETRY_DAYS, DDG_MAX_RUNTIME_SECS, DDG_MAX_CONSEC_BLOCKS env vars to adjust behaviour. Requests run sequentially with throttling because DDG's HTML endpoint returns anti-bot challenge pages (HTTP 202) under burst load. Blocked responses are NOT marked last_searched, so they retry next run instead of being locked out for DDG_RETRY_DAYS.

Data Files

BC government source

  • URL: https://catalogue.data.gov.bc.ca/dataset/.../childcare_locations.csv
  • Update Frequency: BC government publishes data regularly; dashboard renders on schedule
  • Key Columns:
    • VACANCY_LAST_UPDATE: Last timestamp of vacancy status change
    • VACANCY_SRVC_UNDER36, VACANCY_SRVC_30MOS_5YRS, etc.: Vacancy flags by age group
    • CITY, NAME, PHONE, WEBSITE: Facility contact info
    • LATITUDE, LONGITUDE: Map coordinates

data/vacancy_history.csv — one row per facility, updated daily

  • Tracks last_vacancy_* dates and ever_vacancy_* flags per age group
  • Updated by update_history.R

data/facility_urls.csv — one row per facility, updated monthly

  • Stores url, url_source (bc_dataset or duckduckgo), last_searched
  • Seeded from BC dataset WEBSITE field; gaps filled via DuckDuckGo HTML scraping
  • Facilities with no URL are re-searched after DDG_RETRY_DAYS days (default 150)
  • Updated by find_urls.R; run manually with Rscript find_urls.R

Code Style Notes

  • Uses tidyverse conventions: pipe operator |>, dplyr verbs
  • Dashboard uses functional approach with reactable + crosstalk
  • Custom styling in custom.scss (dashboard colors, table formatting)

Testing & Validation

  • Render dashboard locally and verify filters work and map displays correctly
  • Check that vacancy columns update when data changes
  • Verify responsive layout on different screen sizes

Common Issues

renv restore fails: Ensure you have system dependencies installed (see GitHub Action step "Install system dependencies" for required packages)

Dashboard doesn't render: Verify BC government data URL is accessible; check CSV format hasn't changed

Related Links