Chapman Reporting Portal

A national reporting and review platform for the Alpha Phi Alpha Fraternity, Inc. chapter reporting program (the "Chapman Report"). Built to serve 800+ chapters, with separate College and Alumni rubrics, Fall and Spring reporting, parallel District/Regional review, and Executive Director final approval.

This is a fresh build, separate from the earlier prototype repo. The application is written to be database-agnostic: it runs credential-free in a seeded demo mode, and attaches to your existing Supabase project by setting environment variables — no code changes required.

• Stack: Hono 4 + TypeScript on Cloudflare Pages (Workers runtime) + Supabase (Postgres / Auth / RLS / Storage)
• Scoring model: Yes = 1, No = 0, N/A = baseline 1 — with a mandatory_penalty column already in the schema so the future "mandatory item = −1" rule ships with no migration.
• Auth today: email + password. Chapters share one login named <chapter_key>@apa1906.net (e.g. [email protected]) with an auto-generated password; reviewers are named individuals who receive an email invite and set their own password. Provisioning lives in the admin Access & Logins console. AlphaMX SSO is planned as a later Supabase auth provider behind the same sign-in interface.

---

1. Project status

Item	State
Application code	✅ Complete (demo-previewable end to end)
Typecheck (tsc --noEmit)	✅ Clean (0 errors)
Production build (vite build)	✅ Passing (dist/_worker.js, ~455 kB)
Schema + RLS + rollup views	✅ Written (supabase/migrations/) + supabase/bootstrap.sql
Seed data	✅ 872 chapters, 300 rubric items (156 collegiate + 144 alumni), 7 document types
SQL validated	✅ bootstrap.sql run twice on Postgres 17 — 0 errors, idempotent
Deployed to Cloudflare	✅ Live — https://chapman-portal.pages.dev
Attached to your Supabase DB	✅ Attached — schema + seed applied, secrets set, auth verified
Admin Access console (logins)	✅ Live — chapter bulk-provision + credentials sheet, reviewer invites
Authorization/RLS hardening	✅ Phases 0-2 merged and applied to production; see docs/security-architecture-plan.md

---

2. Currently completed features

Reporting (chapter side)

• Chapter dashboard: current reporting period, progress, open/closed window handling.
• Submission workspace with the triple answer model: Yes / No / N/A.
  • Yes → item's default_point_value (1 for standard items)
  • No → 0 (or mandatory_penalty when the item is flagged is_required, default 0)
  • N/A → baseline default_point_value (non-applicable items are not penalized)
• Per-section and overall scoring, auto-saved answers, and an explicit Submit that locks the sheet.
• Document upload area for the chapter's own reporting documents.

Review (parallel, then executive)

• District Director queue and Regional Vice President queue operate in parallel — each records its own decision independently (district_review_status, regional_review_status).
• Executive Director final approval is gated: it is only unlocked when both the district and regional reviews are approved. The gate is enforced in the data/update logic, not only in the UI.
• Review detail pages with the scored rubric, reviewer comments, and approve/return decisions.

Rollups

• District, Regional, and National rollup tables built from reporting views.
• CSV export at every level (/rollups/export).

Admin

• Overview dashboard with national KPIs.
• Chapters: paginated roster (search + district/region filters), spreadsheet import, downloadable import template, and roster export.
• Reviewers: assign and invite reviewers (District Director / RVP / Executive Director / Admin).
• Rubrics: inspect the collegiate and alumni rubric trees.
• Reporting windows: open/close the active Fall/Spring window.
• Document framework (the upload module you asked for):
  • Tax documents (annual_irs_990, chapter_audit, chapter_tax_return, foundation_990)
  • Special event checklists (special_event_checklist, special_event_after_action, grip_submission)
  • This is the framework with file-type / size validation and signed-URL download; the per-document format and required-field lists are intentionally left to be filled in later.

Access & Logins (admin console — /admin/access)

• Chapter logins are generated in bulk from the roster:
  • Username convention <chapter_key>@apa1906.net (e.g. [email protected]); the mailbox does not need to exist — it is a login identifier only.
  • Passwords auto-generated per chapter (14 chars, crypto-random, look-alikes 0/O/1/l/I removed). No password is emailed to chapters.
  • A downloadable credentials sheet (.csv: chapter_key,email,password,status) is produced on the result screen — passwords are shown once and cannot be read back later.
  • Scope the batch by region / district and provision 1–300 at a time; single chapters can also be created from the roster table (each shows the one-time password). Lost a password? The row's Reset password action issues a fresh one. A username-only template download is available.
• Reviewers (District Director, RVP) are invited by email:
  • admin.auth.admin.inviteUserByEmail sends a Supabase email invite; the invitee sets their own password at /auth/accept.
  • The invite sets the reviewer's role_code and scope in user metadata and fans out reviewer_assignments to every chapter in that district (DD) or region (RVP).
  • Reviewers can be activated / deactivated (profiles.is_active + auth ban) from the console.
  • Requires custom SMTP + a redirect-URL allow-list entry — see supabase/SETUP.md ("SMTP for reviewer invitations").

This is the beginning of the README. Read the rest at the original. Read the full README ↗