cmu-meal-estimator/README.md

CMU Meal Estimator

A small single-page web app that estimates how many meal blocks and FLEX dollars a Carnegie Mellon student should have consumed by a given date — and how many should remain — based on their dining plan and time spent on campus.

The tool spreads a plan's totals evenly across the days you're expected to be on campus, then reports three views of that budget: a per-week rate, an amount consumed so far, and an estimated remaining balance, for both meal blocks and FLEX.

Estimates are informational and based on even distribution across on-campus days. They are not official dining balances.

Features

• Pick from all eight dining plans (Green, Blue, Red, Yellow, Tartan Flex, Scotty's Choice, Whitfield's Favor, Piper Select).
• "As of" date picker that defaults to today and is clamped to the meal period.
• Checkboxes for configured breaks ("missing periods") you spent off campus.
• A numeric input for any additional days you don't want counted.
• Live-updating results — every input recomputes the estimate instantly.
• Everything is config-driven: plans, dates, and breaks live in one JSON file that is fetched at runtime. Edit it on the server and changes appear on the next page load — no rebuild needed.
• Your plan, checked breaks, and extra-days value are remembered between visits (via localStorage). The date always resets to today.
• Dark theme with restrained CMU Tartan-red accents.
• Ships as plain static files — no server-side code or backend.

Getting started

Requires Node.js 18+.

npm install      # install dependencies
npm run dev      # start the dev server at http://localhost:5173

Other scripts

npm run build    # type-check and produce a production build in dist/
npm run preview  # serve the production build locally
npm test         # run the estimation-engine tests

Configuration

All tunable values live in public/config.json. This file is fetched at runtime, not compiled into the bundle — so after deployment you can edit the deployed config.json directly and the changes take effect on the next page load, with no rebuild.

During development, edit public/config.json and reload the page.

{
  "mealStartDate": "2026-08-24",   // first day of the meal period (YYYY-MM-DD)
  "mealEndDate": "2026-12-13",     // last day of the meal period (YYYY-MM-DD)

  "plans": [
    {
      "id": "green",               // stable unique key
      "displayName": "Green",      // shown in the dropdown
      "totalMealBlocks": 210,      // total blocks for the whole meal period
      "totalFlexDollars": 500      // total FLEX dollars for the whole meal period
    }
    // ...more plans
  ],

  "missingPeriods": [
    {
      "id": "fall-break",          // stable unique key
      "displayName": "Fall Break", // shown next to the checkbox
      "startDate": "2026-10-19",   // inclusive
      "endDate": "2026-10-20"      // inclusive
    }
    // ...add as many as you like; each becomes a checkbox
  ]
}

Notes:

• The shipped plan numbers are placeholders. Replace totalMealBlocks and totalFlexDollars with the real figures from your CMU dining agreement, and set the correct mealStartDate / mealEndDate for your semester.
• Add or remove plans and missing periods freely. Every missing period automatically becomes a checkbox in the UI.
• If the config is malformed (missing fields, bad dates, duplicate ids, negative totals), the app shows a readable list of problems instead of rendering broken estimates.

How the estimate works

1. Total active days = every calendar day in [mealStartDate, mealEndDate], minus the days covered by any break you check.
2. Daily rate = plan total / total active days, computed separately for blocks and FLEX.
3. Active days consumed = active days from the start up to your "as of" date, minus checked breaks in that window, minus any additional excluded days.
4. Consumed = daily rate × active days consumed.
5. Remaining = plan total − consumed.
6. Per week = daily rate × 7.

Checking a break or adding excluded days shifts your expected consumption down, which is what you want when you were away and not eating on campus.

Deployment (static hosting)

The app is a purely client-side static site — no backend, no server-side rendering. To deploy:

npm run build      # outputs everything to dist/

Then copy the contents of dist/ to wherever you're serving from. The build produces:

dist/
  index.html
  config.json      # the live, editable config
  assets/          # hashed JS + CSS

Subpath hosting

Asset paths in the build are relative, and config.json is loaded relative to the page's own location. That means the app works unchanged whether it's served from a domain root or a subpath — e.g. https://www.cmu.edu/~you/meal-estimator/. No base-path configuration or rebuild is needed to move it between locations.

The one requirement is that the app is served as a directory with a trailing slash (e.g. .../meal-estimator/). Virtually all static servers (Apache, nginx, and the like) redirect .../meal-estimator to .../meal-estimator/ automatically, so this is handled for you.

Editing config after deployment

Because config.json sits alongside index.html in the deployed files and is fetched at runtime, you can update plan numbers, dates, or breaks by editing the deployed config.json directly. No rebuild or redeploy of the JS is required — just reload the page.

Data persistence

The selected plan, checked breaks, and additional-days value are saved to the browser's localStorage and restored on the next visit. The "as of" date is intentionally not persisted — it always defaults to today. Persistence fails silently if localStorage is unavailable (e.g. private browsing), and stale entries (a plan or break no longer in the config) are ignored on load.

Project structure

index.html            # app shell
public/
  config.json         # all tunable values (plans, dates, breaks); served + fetched at runtime
src/
  types.ts            # shared types
  dates.ts            # whole-day date helpers
  configLoader.ts     # validates + normalizes config
  configFetch.ts      # fetches config.json at runtime (subpath-aware)
  engine.ts           # pure estimation math (no DOM)
  store.ts            # tiny reactive state store
  persistence.ts      # localStorage load/save of selections
  main.ts             # builds the UI, re-renders on change
  style.css           # dark CMU-accented theme
  engine.test.ts      # engine unit tests
  sanity.test.ts      # checks against the shipped config

Tech stack

• Vite for dev server and bundling
• TypeScript (strict mode)
• Vitest for tests
• No UI framework — plain DOM with a small reactive store

Tests

The estimation engine is a set of pure functions, kept separate from the DOM so it can be tested directly:

npm test

Covers day counting across boundaries, budget conservation, monotonicity when excluding days, the zero-active-days (division-by-zero) edge case, and sanity checks against the shipped config.