Feat/add scans

[balebbae]

Summary

• Add scan tracking system for hackathon day-of operations (check-in, meals, swag
  distribution)
• Implement scans table with unique constraint per user+type, plus O(1) stats via a counter
  cache in the settings table
• Add admin endpoints for creating scans, viewing user scan history, and retrieving aggregate
  stats
• Add super-admin endpoint for configuring scan types (check_in, meal, swag categories)

New API Routes

Method: GET
Route: /v1/admin/scans/types
Role: admin
Description: List configured scan types

Method: POST
Route: /v1/admin/scans
Role: admin
Description: Record a scan for a user

Method: GET
Route: /v1/admin/scans/user/{userID}
Role: admin
Description: Get all scans for a user

Method: GET
Route: /v1/admin/scans/stats
Role: admin
Description: Aggregate scan counts by type

Method: PUT
Route: /v1/superadmin/settings/scan-types
Role: super_admin
Description: Replace scan type configuration

Key Design Decisions

• Check-in gate: Non-check_in scans (meals, swag) require the user to have a check_in scan
  first
• One scan per type per user: Enforced at DB level via UNIQUE(user_id, scan_type), returns 409
  on duplicates
• O(1) stats: Scan counts are maintained as a counter cache in settings.scan_stats,
  incremented atomically inside the create-scan transaction — avoids COUNT(*) aggregation on
  every poll
• Configurable scan types: Stored as JSONB in the settings table with three categories:
  check_in, meal, swag

Migrations

• 000013 — scans table with indexes on user_id and scan_type
• 000014 — Seeds default scan_types setting (single "Check In" type)
• 000015 — Seeds empty scan_stats counter cache

[anishalle]

everything else lgtm.

[anishalle]

it it common to have two of the same type of struct? one for update and one for get? This is structurally similar to ScanStatsResponse except for the validate:.

[balebbae]

I mean it could be one but I'm just following existing pattern. Also in the future if I want to add other fields to the response in the future it's easier. Like a created_at.

[NoelVarghese2006]

Did you intentionally remove the first line of the headers:
Examples:

// getOrCreateApplicationHandler returns the user's application, creating a draft if none exists

// updateApplicationHandler updates the user's draft application

[balebbae]

Uh yeah I feel like the swagger descriptions pretty self explanatory already. Also I don't like when comments restate the function. Lowkey claudes faults.

[balebbae]

wait claudes smarter than me... Apparently it's needed 🫩. I'll go add them again.

[NoelVarghese2006]

same questions about the first line

[NoelVarghese2006]

same as previous comments

[NoelVarghese2006]

only first method has the first line in the header

[balebbae]

OPs I gotta delete that

[NoelVarghese2006]

same question about headers

[anishalle]

@copilot Review this PR

(I wanna see what it says)

[Copilot]

@anishalle I've opened a new pull request, #34, to work on those changes. Once the pull request is ready, I'll request review from you.