docs: README and architecture refresh

[V-prajit]

Summary

• Rewrites the README to a Tier 1 standard: problem statement, core functionality, architecture Mermaid diagram, offline data-pipeline Mermaid diagram, key technical decisions, setup/usage/testing/deployment sections, known limitations, and team attribution.
• No application code was changed. This PR is documentation only.
• Follow-up commit applies reviewer feedback: corrects the overstated LRU-cache scope (diagram + prose), rewords the pull.yml deployment note, and removes all em dashes per the style guide.

Why it matters

The previous README (about 1.5KB) was a generic tech-stack/quick-start list with no explanation of what MavGrades actually does, how data gets from UTA's public records office into the running app, or what the API surface looks like. New contributors and the ACM UTA team had no single accurate reference for the architecture.

Docs changed

• README.md — full rewrite, plus a follow-up accuracy/style pass.

Diagrams added

1. Application architecture (browser -> Next.js API routes -> bundled SQLite), derived from src/app/api/*/route.ts, src/lib/db.ts, and the components under src/app/components. Updated so /api/courses/search connects directly to grades.sqlite via its persistent connection (PRAGMA cache_size/temp_store), not through the LRU-cache node — that route does not import lru-cache.
2. Offline grade-data pipeline (UTA FOIA CSV -> csv_to_json.py -> json_to_sqlite.cjs -> committed grades.sqlite) plus the separate scrape_rmp.py -> professors.db path, derived from public/data/*.py, public/data/*.cjs, package.json's process script, and public/data/README.md.

Both diagrams are Mermaid flowchart, checked for balanced brackets/quotes.

Metadata changed

• gh repo edit description/topics update (see separate commit-less metadata step; recorded in the audit artifact for this repo). Homepage left unchanged (https://www.mavgrades.com, verified 200 today).

Metrics used

• Semester coverage (Fall 2020 through 2024-2025 academic year, 15 semester tables) — verified directly against public/data/raw/*.csv and the tables inside public/data/grades.sqlite.
• grades.sqlite size (~21MB) — verified with du -sh.
• Live deployment platform and HTTP status — verified with curl -sIL https://www.mavgrades.com (200, server: Vercel).
• Contributor list — from git shortlog -sn --all.

Metrics softened or removed

• No user counts, traffic, or "impact" numbers were available in the repo, so none are claimed. The README explicitly avoids invented adoption/impact metrics.
• Softened the LRU-cache claim from "in front of every API handler" to naming only the two handlers that actually import lru-cache (/api/grades, /api/professor-rating), with /api/courses/search's SQLite-PRAGMA approach called out separately, after review found the original claim did not match src/app/api/courses/search/route.ts.
• Reworded the pull.yml deployment claim from "auto-syncs main" to describe the rule accurately: it hard-resets a master base against the upstream template, a branch distinct from this repo's main default.

Validation performed

• Read every API route handler, src/lib/db.ts, both data-pipeline scripts (csv_to_json.py, json_to_sqlite.cjs, scrape_rmp.py), package.json, .github/pull.yml, .gitignore, and LICENSE.md.
• Inspected public/data/grades.sqlite directly (sqlite3 .tables) to confirm semester-table coverage matches the raw CSVs.
• Ran git log/git shortlog/git log --author across all branches to determine contributor history and confirm no commits from Prajit Viswanadha exist in this repo.
• Verified https://www.mavgrades.com returns HTTP 200 via curl -sIL.
• Confirmed no test suite, no CI workflow beyond the upstream-sync pull.yml, and no .env/secret usage anywhere in the app code.
• Reviewer-feedback pass: grepped src/app/api/*/route.ts for lru-cache imports (confirmed only grades/route.ts and professor-rating/route.ts import it) and for PRAGMA usage (confirmed courses/search/route.ts sets cache_size/temp_store on a persistent connection instead); re-read .github/pull.yml to confirm its base: master / upstream: lryanle:master / mergeMethod: hardreset fields before rewording the deployment note; grepped the full README for the em dash character (U+2014) and confirmed zero remaining after the edit.

Known uncertainties

• Whether scrape_rmp.py is still actively run/maintained, or was a point-in-time data pull, is not verifiable from the repo alone.
• Why professors.db uses WAL mode toggling (turn off wal mode for db commit) is inferred from the commit message and Vercel read-only filesystem constraints in src/app/api/professor-rating/route.ts, but the full reasoning isn't documented anywhere.
• The exact relationship to .github/pull.yml's lryanle:master upstream (an earlier template/original author repo) is stated in the README as historical context; I did not attempt to characterize how much of the current app still resembles that template, since the git history shows extensive divergence from the first commit onward.

Needs owner confirmation

• Prajit Viswanadha has zero commits in this repository's git history (checked across all branches, all author-name variants). The README intentionally does not claim any personal code contribution from him and instead attributes the work to the visible contributor list (Kevin Farokhrouz, Atiqur Rahman, Talha Tahmid, and others). If Prajit has a non-commit role (org maintainer, FOIA-request coordinator, reviewer, etc.), please add it explicitly — I left a placeholder in the Team & attribution section rather than guess.
• Confirm whether scrape_rmp.py should get a requirements.txt (flagged as a known limitation, not fixed here since this PR is docs/metadata only).
• Confirm current license intent (custom LICENSE.md + CC BY-NC-SA 4.0 for data) is still accurate/desired; no license file was added or changed.

Missing media

• No architecture screenshots or product screenshots exist in the repo (only public/landing.jpeg, public/assets/UTA.png, and stock Next.js/Vercel SVGs). None were added since fabricating screenshots is out of scope; consider adding a real product screenshot in a follow-up.

Security notes

• git push reported GitHub found 94 Dependabot alerts (2 critical, 43 high, 40 moderate, 9 low) on the default branch. Not investigated or remediated here (out of scope for a docs-only PR) — flagging for maintainer awareness. No secret values are referenced or exposed anywhere in this PR.