One Knight Stand

Deterministic, Rutgers-only matching system with OTP auth, phase-gated intake, auditable final match materialization, and run-scoped reveal.

This repo is engineered as an event system, not a social feed:

• strict state transitions
• explicit run IDs
• idempotent admin operations
• durable audit trail

System Snapshot

• Framework: Next.js 14 (App Router)
• Data store: Turso (libsql) via @libsql/client + drizzle-orm/libsql
• Ephemeral controls: Redis (OTP + rate limits)
• Auth: OTP + signed session cookie
• Matching: deterministic greedy algorithm with stable tie-breaks

Core Guarantees

• OTP send endpoint is non-enumerable (200 { ok: true }) across valid/invalid emails.
• OTP verification fails closed (503) when Redis is unavailable.
• Survey payloads are contract-validated server-side (required IDs, no unknown IDs, version-pinned).
• Confirmation is idempotent and phase-gated.
• Final materialization is run-scoped, lock-protected, and auditable.
• Reveal behavior is phase-gated and distinguishes run-missing vs run-incomplete.

Repo Layout

• src/app/api/* - HTTP route handlers
• src/lib/* - domain and infrastructure modules
• drizzle/* - SQL migrations + snapshots
• docs/* - architecture, API, operations, security, runbook

Quick Start

1) Install

npm install

2) Configure env

Create .env.local (or Vercel env vars) with all required values:

# DB / Redis
DATABASE_URL=libsql://<your-db>.turso.io
DATABASE_AUTH_TOKEN=<turso-token>
REDIS_URL=redis://localhost:6379

# Auth
SESSION_SECRET=<32+ random bytes>
OTP_SALT=<16+ random bytes>

# Email
GMAIL_USER=<gmail address>
GMAIL_APP_PASSWORD=<gmail app password>

# Schedule (ISO timestamps)
MATCH_SURVEY_CLOSE_AT=<iso datetime>
MATCH_INITIAL_REVEAL_AT=<iso datetime>
MATCH_CONFIRM_CLOSE_AT=<iso datetime>
MATCH_FINAL_REVEAL_AT=<iso datetime>

# Matching
MATCH_RUN_ID=<stable run id>
MATCH_RESET_MIN_AGE_MS=60000

# Optional legacy admin bridge
MATCH_ADMIN_TOKEN=<optional legacy token>

# Optional admin session freshness override
ADMIN_SESSION_MAX_AGE_SECONDS=1800

# Optional proxy trust override (for IP extraction)
TRUST_PROXY=1

3) Apply migrations (against Turso)

npm run db:migrate

4) Start app

npm run dev

Quality Gates

npx tsc --noEmit
npm run lint

Documentation Index

• Architecture: docs/ARCHITECTURE.md
• API Reference: docs/API.md
• Operations Runbook: docs/OPERATIONS.md
• Security Model: docs/SECURITY.md
• M3 Prod Gate: docs/m3-prod-ready-gate.md
• GitHub About copy/template: docs/GITHUB_ABOUT.md

Deployment Notes

This system is production-ready for single-run operation when Redis + Turso are correctly configured and the M3 gate is passed.

Before declaring production ready, run the mandatory checklist in docs/m3-prod-ready-gate.md.