Skip to content

feat(reimbursements): public claim submission + admin review - #373

Merged
gregv merged 6 commits into
developfrom
feat/reimbursement-submissions
Nov 17, 2026
Merged

gregv merged 6 commits into
developfrom
feat/reimbursement-submissions

Conversation

@gregv

@gregv gregv commented Nov 16, 2026

Copy link
Copy Markdown
Contributor

Code written by Tarry (Muse) - Model: Muse Wonder, Effort: xhigh

What was built

Backend half of the reimbursement feature for ohack.dev/reimbursement. People who bought food out of pocket at the Fall Hackathon Nov 14-15 2026 (and future events) can submit a claim; admins review, approve/deny, and mark paid.

IRS accountable-plan rules enforced in code: business connection (businessPurpose + fedDescription required), substantiation (itemized receipt, date, vendor, amount), timely filing (expenseDate within the last 120 days, never in the future). Amount over $0 and at most $10,000.

  • api/reimbursements/reimbursements_service.py - validation, reference ids, receipt verification, status-transition map, no-self-approval, admin list/get/review
  • api/reimbursements/reimbursements_views.py - Flask blueprint, public + volunteer.admin routes
  • api/reimbursements/tests/ - 73 unit tests (service + views)
  • Blueprint registered in api/__init__.py
  • Diagrams: docs/diagrams/reimbursement-submissions.html (architecture) and docs/diagrams/reimbursement-status-lifecycle.html (status state machine), finalized with Archify 3.2.0, all gates pass including browser-check

Endpoints

Public (no login, reCAPTCHA-gated like the contact form):

  • POST /api/reimbursements - submit a claim, 201 {success, id, referenceId, status: submitted}; referenceId format REIMB-YYYY-XXXXXX
  • POST /api/reimbursements/receipt-upload-url - mint a signed GCS PUT URL for a receipt (JPEG/PNG/WebP/PDF, max 10 MB); bytes never pass through Flask
  • GET /api/reimbursements/status?email=&reference_id= - public projection only (referenceId, status, amountCents, expenseDate, updatedAt); 404 on no match or wrong email; never returns receipt URLs or reviewer notes

Admin (volunteer.admin only, req_to_org_id=getOrgId):

  • GET /api/reimbursements/admin?status=&event_id=&limit=&offset= - {data, count}, count is total matching; filters and sort in Python (no composite index); limit default 50, max 200
  • GET /api/reimbursements/admin/<id> - full doc incl. receipt final URL, status history, reviewer info
  • PATCH /api/reimbursements/admin/<id> - body {status, reviewNote} only; any status/reviewedBy/paidAt/statusHistory in the payload is ignored. Transitions: submitted -> under_review|needs_info|approved|denied; under_review -> approved|denied|needs_info|submitted; needs_info -> under_review|approved|denied; approved -> paid; denied -> under_review; anything else (incl. same-status) is 409 invalid_transition. Stamps reviewedBy/reviewedAt, paidAt on paid, appends to statusHistory.

No self-approval is enforced in code: a reviewer whose verified PropelAuth email (or propel id) matches the submitter gets 403 self_approval. Treasurer is Jot Powers, president is Greg Vannoni; neither may approve their own claim.

Storage: Firestore collection reimbursements, snake_case fields per contract. No bank account or routing numbers are stored anywhere in v1 - reimbursementMethod records only ach|check; ACH details are a secure follow-up, never in this API.

Tests run + results

  • ENVIRONMENT=test python -m pytest api/reimbursements/tests/ -q - 73 passed (validation, referenceId format, all valid + invalid transitions, no-self-approval, receipt verification, admin list/get, view auth gates)
  • pylint api/reimbursements/ api/__init__.py --disable=all --enable=E - 10.00/10, no errors. Full pylint is 9.14/10: only style warnings (broad-except matching the contact/jobs pattern, %-formatting, intentional lazy cdn import like jobs_service, too-many-returns in validation functions).
  • Environment note: the repo documents a conda env (py39_ohack_backend, Python 3.9) which is not installed on this machine, and system python3 has no pytest. Tests ran under ~/workspace/be-test-venv (Python 3.12, has pytest + deps). Code follows the Python 3.9 rules (Optional, no PEP 604 unions) so it stays 3.9-safe.
  • Regression: full-suite pytest cannot collect in this environment (50 pre-existing collection errors, e.g. missing FIREBASE_CERT_CONFIG service account). Nearby domains pass: checkin + auth tests 31 passed; the 3 contact-service failures are pre-existing stale tests (verified failing on develop before this branch, e.g. send_confirmation_email called with the old 3-arg signature).

Open decisions for Greg

  1. Who exactly can approve/pay? v1 uses volunteer.admin. Is a dedicated reimbursement.admin permission wanted, like checkin.admin?
  2. Dual approval over a threshold? v1 is single-reviewer for any amount up to $10,000.
  3. Is public no-login submission acceptable, or should claims require login?
  4. How should ACH details be collected securely? v1 collects reimbursementMethod only; no bank details anywhere.
  5. Notifications: v1 sends no confirmation email or Slack ping on submit/review. Want a submitter confirmation and/or a treasurer notification?

Public no-login submission with reCAPTCHA, signed-URL receipt upload
via GCS, public status lookup, and volunteer.admin review with a
status-transition map and no-self-approval enforcement.

Code written by Tarry (Muse) - Model: Muse Wonder, Effort: xhigh
Architecture + claim status lifecycle, finalized with Archify 3.2.0
(all gates pass, incl. browser-check).

Code written by Tarry (Muse) - Model: Muse Wonder, Effort: xhigh
"Missing required fields: %s" % ", ".join(missing),
)
email = str(data["submitterEmail"]).strip().lower()
if not _EMAIL_RE.match(email):
except Exception as e:
logger.exception("Error reviewing reimbursement %s: %s", reimbursement_id, str(e))
return {"success": False, "error": str(e)}, 500
return payload, status
gregv and others added 4 commits November 16, 2026 21:35
- public status lookup / reference-id check use a where() query instead of
  streaming the whole collection
- reject NaN/inf/sub-cent amounts (NaN was a 500), non-object bodies,
  non-string and over-long fields, empty receipt blobs
- receipt path must match the minted shape
- one day of timezone slack on expense-date checks (form-accepted dates
  were rejected every evening in US timezones; tests were clock-dependent)
- reviews fail closed without a reviewer identity; review note trimmed/capped
- Slack audit on submit and status change
- admin 500s no longer echo exception text; run the suite in CI

Co-Authored-By: Claude Fable 5.2 <[email protected]>
…XPIRES

Minting correctly refuses once the event expiry (2026-11-16T01:00Z) has
passed, so 12 tests that mint on the real clock went red on develop.
_key_duration now reads _utc_now() (a seam); the test fixture pins it to
before the expiry. No behaviour change.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
- reimbursementMethod accepts paypal, venmo, zelle with a validated,
  normalized payout handle and the name on the account (Venmo: optional
  last 4 phone digits for the app's new-recipient check)
- payout details are write-once, admin-only, absent from the public status
  view and the Slack audit
- marking a claim paid requires a payment reference, stored with the claim

Co-Authored-By: Claude Fable 5.2 <[email protected]>
return payout, None
# PayPal and Zelle both pay to an email address or a mobile number.
if "@" in handle:
if not _EMAIL_RE.match(handle):
"error": "internal_error",
"message": "An error occurred while processing your request",
}, 500
return payload, status
@gregv
gregv marked this pull request as ready for review November 17, 2026 05:32
@gregv
gregv merged commit 95db3aa into develop Nov 17, 2026
5 of 6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants