Case Study Catalog

Live at case-study-catalog.fly.dev. A public catalog of real examples of generative AI in higher education, in three collections (teaching, research, and reducing AI misuse), with a submission form, a password-gated dashboard for approving new entries before they go live, and a set of analyses built on the catalogs. Every entry must describe something actually built, run or trialled, with a source link.

The code is also usable as a starter template: fork it, replace the seed data and branding with your own topic, and deploy.

• GET / — public catalog (search + facets)
• GET /submit — public submission form
• GET /admin — password-gated review dashboard (approve / reject / edit / delete)
• GET /about — about page
• GET /ai-for-research — companion catalog for research (rather than teaching) case studies
• GET /reducing-ai-use — companion catalog for "reducing AI (mis)use" case studies
• GET /trends, GET /research-trends — aggregate trend/association views over the teaching and research catalogs, respectively
• GET /analyses — landing page for the four analyses: teaching trends, research trends, AI guidance analysis, and research on AI detection
• GET /ai-guidance-analysis — analysis of what UK and Irish universities tell students about generative AI; every count traces to a quote in the institution's own document (method and codebook in policy/, data in data/policy/). Draft, in progress. /ai-policy-atlas redirects here
• GET /teachers-spotting-ai — research dashboard on whether teachers can tell AI-written work from student writing (sources in docs/teachers-spotting-ai-writing.md)
• GET /ai-perceptions — findings explorer for the AI-perceptions research papers (separate from the case-study catalogs above)

How it works

• Your own curated entries ship as data/seed.json and are loaded into the database once, the first time the server starts against an empty database.
• Public submissions land in the same database with status = 'pending' and are invisible to /api/catalog until approved.
• The admin dashboard (/admin) is gated by a single shared password (ADMIN_PASSWORD). It shows every entry — originally-curated and community-submitted alike — with approve/reject/edit/delete on any of them, plus an "Add from email" box that publishes straight from a pasted notification email, and a "Repository suggestions" list for links someone flagged as worth going through by hand.
• Storage is SQLite via Node's built-in node:sqlite module — no native build step, no separate database service to run.
• Every new submission also fires an email notification (see below) — this is optional and skipped silently if not configured.

Email notifications

Sends via Gmail SMTP (not a new account — reuses whichever Gmail address you designate as the sender) whenever someone submits through /submit. Set three env vars:

Var	Meaning
GMAIL_USER	The Gmail address that sends the notification
GMAIL_APP_PASSWORD	An app password for that account (see below) — not your regular Gmail password
NOTIFY_EMAIL	Where notifications are delivered — can be any address, including a different Gmail account or an institutional/shared team inbox

To get an app password: the GMAIL_USER account needs 2-Step Verification turned on (Google Account → Security), then generate one at myaccount.google.com/apppasswords. It's a 16-character code, not your login password — paste it into GMAIL_APP_PASSWORD.

If any of the three vars is missing, the server logs a warning on startup and simply skips sending — submissions still work normally, they just won't trigger an email.

The recipient doesn't need to be related to the sending account or match any domain — Gmail SMTP can deliver to any inbox, so pointing NOTIFY_EMAIL at an institutional address works the same as pointing it at a personal one.

Every notification email also includes the submission as a single-line JSON block, formatted to be pasted straight into the admin dashboard's "Add from email" box (see below) — the email itself is the durable record of a submission, independent of whether its row in the database is still there by the time you get to it. The "Add from email" box also accepts the plain-text part of the email on its own, or the whole email pasted in — it isn't JSON-only.

Repository suggestions

/submit also has a small secondary form for "I know of a whole page/PDF/collection of these, not just one" — it takes a URL and an optional note, emails you the same way a regular submission does, and lists it under "Repository suggestions" in the admin dashboard. There's no automatic extraction (see the note in /submit about why a published page can't fetch or read an arbitrary URL for you) — you visit the link yourself, and add whatever qualifies through the normal form or paste box. Mark a suggestion done once you've gone through it.

Git persistence for approved entries (avoids paying for a persistent volume)

Without this, approved entries only exist in the SQLite file, so a host with no persistent disk (e.g. a bare Fly.io machine with no volume attached) loses them on every rebuild. With it, every approve/edit/delete/reject of any entry — originally-curated or community-submitted, since the admin dashboard can edit or delete either — commits the full current list of approved entries to data/community.json via the GitHub API, including which collection each one belongs to and whether it was seeded or submitted. Once that first sync has ever happened, community.json becomes the living snapshot of the whole catalog: a freshly rebuilt instance loads from it rather than from the original seed.json (which stays untouched as the initial bootstrap for a repo that's never synced yet).

Writes retry automatically on a conflicting commit (e.g. two syncs landing at nearly the same moment) by re-reading the current database state and trying again, rather than silently dropping whichever one loses the race.

Var	Meaning
GITHUB_TOKEN	A GitHub personal access token, scoped to just this repo, with Contents: Read and write permission
GITHUB_REPO	your-username/case-study-catalog
GITHUB_BRANCH	Defaults to main

To create the token: GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens → New token → restrict "Repository access" to just this repo, and under "Permissions" set Contents to Read and write. Paste the generated token into GITHUB_TOKEN — never into this repo or into chat.

If either var is missing, git syncing is silently skipped (a warning is logged once on startup) — approving/editing/deleting still works normally, it just won't survive a from-scratch rebuild without a persistent disk.

The one gap this doesn't close: submissions still sitting in pending review only exist in the database until you act on them. The notification email is the safety net for those — its copy-paste JSON block (see "Add from email" in the admin dashboard) lets you publish a submission directly even if its row never makes it, without needing the original row to still exist.

Local development

npm install
cp .env.example .env   # then edit ADMIN_PASSWORD, SESSION_SECRET, and the email vars above
npm start

Visit http://localhost:3000 (or whatever PORT you set).

Deploying to Fly.io

1. Push this repo to GitHub.
2. Install flyctl and run fly launch from the repo root, or reuse the included fly.toml (app name case-study-catalog) and run fly apps create case-study-catalog to claim it.
3. Set the secrets fly.toml doesn't cover: fly secrets set ADMIN_PASSWORD=... SESSION_SECRET=... — plus the email and git-persistence vars above, if you want those features.
4. fly deploy --remote-only for the first deploy — Fly builds from the included Dockerfile on their own builders, so no local Docker install is needed. First boot seeds the database automatically.

Auto-deploy on push

.github/workflows/fly-deploy.yml runs flyctl deploy --remote-only on every push to master, authenticated with a FLY_API_TOKEN repo secret — a scoped deploy token (fly tokens create deploy --app case-study-catalog), not your full account token. Once that secret is set in the repo's GitHub Actions settings, git push is the whole deploy step; no manual fly deploy needed afterwards.

Important: persistence and cost

The included fly.toml has no [mounts] section, so — like most free-tier PaaS hosting — the local SQLite file resets on every restart/redeploy. That's fine here specifically because git persistence (above) is set up: approved entries are re-seeded from data/community.json on every boot, and pending ones are backed up by the notification email. Without GITHUB_TOKEN/GITHUB_REPO configured, approved entries would be lost on every restart — so treat git persistence as required, not optional, unless you add real storage.

If you'd rather not depend on git for this, two alternatives:

• Add a Fly volume and mount it in fly.toml, with DB_PATH pointing into it — a real persistent disk, no git involvement needed (Fly's free allowance covers a small volume).
• Or swap the storage layer for a free external database (e.g. Turso/libSQL, Neon Postgres) — that's a change to src/db.js, not the rest of the app.

Changing the admin password later

fly secrets set ADMIN_PASSWORD=newpassword --app case-study-catalog — the app redeploys automatically with the new value. No code change needed.

Project layout

src/
  server.js   — Express app, routes, session auth
  db.js       — schema, seed import (seed.json + community.json), all queries
  mailer.js   — Gmail SMTP notification on new submissions
  gitStore.js — commits data/community.json to GitHub on approve/edit/delete
public/
  catalog.html         — public browse/search page for the teaching catalog (fetches /api/catalog)
  ai-for-research.html — companion browse/search page for the research catalog
  reducing-ai-use.html — companion browse/search page for the "reducing AI (mis)use" catalog
  submit.html          — public submission form (posts to /api/submissions)
  admin.html           — password-gated review dashboard + "Add from email" box
  about.html           — about page
  trends.html          — aggregate trends/associations over the teaching catalog
  research-trends.html — aggregate trends/associations over the research catalog
  analyses.html        — landing page linking the four analysis pages
  ai-guidance-analysis.html — analysis of university AI guidance, built from data/policy/
  teachers-spotting-ai.html — research dashboard on human detection of AI writing
  ai-perceptions.html  — findings explorer for the separate AI-perceptions research papers
  shared.css           — shared design system, linked by catalog/submit/admin/about/
                          ai-for-research/reducing-ai-use; the trends and ai-perceptions
                          pages inline their own copy plus page-specific chart extensions
  favicon.svg
policy/   — method, codebook, coding briefs and scripts (`npm run policy:validate`,
             `npm run policy:test`) for the AI guidance analysis; see `policy/README.md`
docs/     — research briefing behind the AI detection page
data/
  seed.json      — your curated entries, imported once on first boot
  community.json — approved community submissions, kept in sync by gitStore.js
  policy/        — institutions, documents, and evidence-backed codes for the guidance analysis

About this project

This catalog and its content were built by Juliana Gerard, a lecturer in Linguistics at Ulster University. The application code was written with Claude Code (Anthropic), which was also used to source candidate case studies, screen them against the inclusion criteria, write entries, and draft the analyses; the human work is setting those criteria, directing the research, and reviewing what actually qualifies.

License

This repository is dual-licensed:

• Code (src/, public/) — MIT. Use, fork, and modify freely.
• Catalog data (data/seed.json, data/community.json) — the summaries, quotes-in-context, and metadata written for this project are CC BY 4.0. Reuse them anywhere, including commercially, as long as you credit this project and link back to the source repository. This license covers only what was written here — it does not extend to the case studies themselves, which remain the copyright of their original authors and institutions; each entry just links out to the source.