Project Atlas AetherDev project hub
Atlas project production

BOUSD-Staff-Technology-Dashboard

This project powers the Brea Olinda USD staff technology dashboard that the Technology Services department uses to manage technology needs and plan device replacement strategies. It ingests SQL outputs loaded into `SourceData-staff` and `SourceData-devices` tabs; mapping tabs for roles and models and produces Apps Script web response; charts and tables rendered in browser.

Type
System
Lifecycle
Active
Last touched
2025-12-13
Visibility
Public

Purpose

This project powers the Brea Olinda USD staff technology dashboard that the Technology Services department uses to manage technology needs and plan device replacement strategies.

Current state

Last touched: 2025-12-13. 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-staff` and `SourceData-devices` tabs
  • mapping tabs for roles and models
  • 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

  • Required column headers in the sheet tabs must remain stable for Code.js 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 messages when payloads are too large
  • 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

Staff and device inventory data is sensitive; limit sheet access and Apps Script deployment to authorized users. Access control via `User-Mappings` and role scoping must remain aligned with district policy. README includes direct web app and sheet links; keep those URLs private.

Dependencies

Upstream
  • Google Sheets, Google Apps Script web app runtime

Ownership

Owners

Josh Barton

Users

Josh Barton (owner)

BOUSD-Staff-Technology-Dashboard

Architecture & Major Components

  • High-level diagram (text):

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

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

  • Top-level folders: SQL files in repo root; Apps Script and HTML assets

  • Key abstractions: Access control via User-Mappings, tier expectations via Role-Tier-Mapping, model mapping via Tier-Model-Mapping, cached payload builder

Setup / Build / Run

  • Build system(s): Apps Script deployment via clasp and the deploy.sh helper.
  • Run SQL (staff.sql, devices.sql), export to CSV, paste values into sheet tabs.
  • Push Apps Script changes with clasp push (or ./deploy.sh) and redeploy as needed.
  • After data refresh, run clearDashboardCache(); large payloads may skip caching by design.