Project Atlas AetherDev project hub
Atlas project production

BOUSD-MonthlyAttendance-Dashboard

This project powers the Brea Olinda USD monthly attendance dashboard that school and district leaders use to monitor attendance and chronic absenteeism trends across the academic year. It ingests SQL outputs loaded into `SourceData-year-byschool` and `SourceData-year-bygrade` tabs and produces Apps Script web response; charts and tables rendered in browser.

Type
System
Lifecycle
Active
Last touched
2025-10-21
Visibility
Public

Purpose

This project powers the Brea Olinda USD monthly attendance dashboard that school and district leaders use to monitor attendance and chronic absenteeism trends across the academic year.

Current state

Last touched: 2025-10-21. Functionality and completeness: SQL queries and Apps Script app are documented; manual refresh steps are required.

Next step

Add baseline automated tests to cover critical flows; Add CI pipeline for build/test/lint; Document deployment/runtime environment (or add Dockerfile); Document interfaces (CLI flags, API endpoints, file formats); Add structured logging and basic health checks.

Interfaces

Inputs
  • SQL outputs loaded into `SourceData-year-byschool` and `SourceData-year-bygrade` tabs
  • SQL query outputs (CSV)
  • Google Sheet tabs
  • Browser requests (dashboard UI)
Outputs
  • Apps Script web response
  • charts and tables rendered in browser
  • Query results (reports/extracts)
  • CSV files
  • Rendered HTML output

Reality to Action trace

Reality Ingestion

Contributes in this stage.

Canonical Storage

Contributes in this stage.

Automation Engines

Not in scope.

Human Interfaces

Contributes in this stage.

Operational Adoption

Contributes in this stage.

Core workflow

TBD. Document the 5-10 steps that define the core workflow.

Artifacts

  • Column headers in the source sheet must remain stable for Code.js field mapping

Operational notes

Constraints and scars

  • Relies on manual CSV refresh into the sheet; column/header drift breaks Apps Script parsing.

Reliability posture

Failure modes and safe behavior: Header mismatches or missing tabs cause runtime errors; stale sheet data yields stale dashboard metrics. Idempotency / retries / batching behavior: Sheet refresh is manual; cache TTL and `clearDashboardCache()` control recomputation.

Observability

  • Logs: Apps Script execution logs; cache events and debug helpers in Code.js
  • Metrics/health checks: None built-in; rely on Apps Script logs and visible dashboard behavior
  • Logs: Apps Script execution logs; cache versioning and debug helpers in Code.js; sheet tabs serve as data artifacts.

Security and privacy

Attendance data is sensitive; limit sheet access and Apps Script deployment to authorized users. Ensure access control via `User-Mappings` and role filtering remains aligned with district policy.

Dependencies

Upstream
  • Google Sheets, Google Apps Script web app runtime

Ownership

Owners

Josh Barton

Users

Josh Barton (owner)

BOUSD-MonthlyAttendance-Dashboard

Architecture & Major Components

  • High-level diagram (text):

    • Entry/trigger -> core logic -> outputs (details per docs below)

  • Entry points: BOUSD-MonthlyAttendance-Dashboard/Code.js, BOUSD-MonthlyAttendance-Dashboard/Index.html

  • Top-level folders: aeries-dbinfo (supporting DB metadata), SQL files in repo root

  • Key abstractions: Apps Script handlers, cache layer (CacheService), chart payload shaping, SQL query definitions

Setup / Build / Run

  • Build system(s): Apps Script deployment via clasp and the deploy.sh helper.
  • Run SQL (year-byschool.sql, year-bygrade.sql), export to CSV, paste values into sheet tabs.
  • Push Apps Script changes with clasp push (or ./deploy.sh) and redeploy as needed.
  • When schema changes, run clearDashboardCache() and bump the cache version in Code.js.