Group Scholar Engagement Timeline

A Lua CLI that logs scholar engagement events into a production Postgres schema and produces quick summaries for program ops. It’s designed for lightweight, consistent capture of outreach touches, check-ins, and follow-ups so teams can see engagement trends without opening a spreadsheet.

Features

• Log engagement events with scholar, type, source, staff owner, and notes.
• List recent engagement activity with optional scholar filtering.
• Summarize engagement volume by event type for a rolling window.
• Production-ready Postgres schema with seeded sample data.

Tech Stack

• Lua 5.4
• pgmoon (Postgres client)
• PostgreSQL

Setup

Install Lua and dependencies:

brew install lua luarocks
luarocks install pgmoon

Create a .env file (or export env vars):

export DB_HOST="your-production-host"
export DB_PORT="23947"
export DB_USER="ralph"
export DB_PASSWORD="your-password"
export DB_NAME="postgres"
export DB_SCHEMA="groupscholar_engagement_timeline"
export DB_SSLMODE="disable"

Usage

./bin/gs-engagement help

./bin/gs-engagement log \
  --scholar "scholar-1042" \
  --type "check_in" \
  --note "Reviewed midterm plan and set next steps" \
  --source "sms" \
  --staff "alyssa"

./bin/gs-engagement list --limit 10

./bin/gs-engagement list --scholar "scholar-1042"

./bin/gs-engagement summary --days 45

Production Database Setup

Create schema + seed data in production:

./scripts/seed_prod.sh

Tests

./scripts/run_tests.sh

Notes

• This CLI expects a production Postgres connection. It intentionally does not support local dev DBs.
• The schema is isolated under groupscholar_engagement_timeline to avoid collisions.