Add onboarding docs, DAL auth pattern, and GitHub templates

[kevinrutledge]

Summary

• Add developer onboarding documentation
• Implement unified token authentication with DAL pattern
• Replace GitHub issue templates with YAML forms
• Migrate from Jest to Vitest
• Install Contact Groups feature dependencies

Changes

Documentation

• docs/README.md - Documentation index
• docs/architecture.md - System overview with diagrams
• docs/first-exercise.md - First PR onboarding exercise
• docs/decisions/ - ADRs for Prisma, Server Actions, auth, CI/CD
• src/README.md, test/README.md - Directory guides
• Updated README.md, CONTRIBUTING.md, getting-started.md

Authentication

• src/lib/dal.ts - Data Access Layer with verifySession(), requireAdmin(), validateToken()
• src/app/api/auth/callback/route.ts - Token handoff from PRFC portal
• src/app/(public)/dev/mock-portal/page.tsx - Mock portal for local dev
• src/app/api/dev/token/route.ts - Dev token generation
• Simplified middleware to cookie presence check
• Deleted src/lib/auth.ts

Testing

• Migrated from Jest to Vitest (10-20x faster, Next.js 15 recommended)
• vitest.config.mts - Vitest configuration with environment globs
• vitest.setup.ts - Global setup with server-only mock
• Updated all test mocks for Vitest compatibility
• Updated CI workflow with required environment variables

GitHub Templates

• Replaced new-issue.md with YAML form templates
• bug-report.yml - Added environment field
• feature-request.yml - Priority and acceptance criteria
• onboarding.yml - Structured task breakdown with resource links
• config.yml - Disables blank issues

Dependencies

• @tanstack/react-virtual - List virtualization
• @react-email/components, @react-email/render - Email templates
• fuse.js - Fuzzy search
• twilio - SMS integration
• shadcn components: command.tsx, alert-dialog.tsx

Testing

• 55 unit tests pass (Vitest)
• 7 e2e tests pass (Playwright)
• Build succeeds
• No vulnerabilities (npm audit)

Token Format

ownerid|isAdmin|timestamp|hmac_signature

Validated locally via HMAC-SHA256. No API round-trip to portal.

Mock Portal Desktop Viewport

Mock Portal Mobile Viewport

[Copilot]

Pull request overview

This PR implements a comprehensive authentication overhaul, adds extensive developer onboarding documentation, and modernizes GitHub templates. The changes establish a unified token-based authentication system using the Data Access Layer (DAL) pattern, replacing the previous password-based approach with HMAC-signed tokens from the PRFC member portal.

Key Changes:

• Implemented token authentication with DAL pattern for unified admin and member access
• Added comprehensive onboarding documentation including architecture diagrams, ADRs, and first-exercise guide
• Replaced Markdown issue templates with structured YAML forms for better issue tracking

Reviewed changes

Copilot reviewed 42 out of 48 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
src/lib/dal.ts	New Data Access Layer with HMAC token validation, session management, and admin authorization
src/lib/auth.ts	Deleted - replaced by DAL pattern
src/middleware.ts	Simplified to cookie presence check for UX optimization; real auth moved to DAL
src/app/api/auth/callback/route.ts	Token handoff endpoint receiving signed tokens from PRFC portal
src/app/api/dev/token/route.ts	Development-only token generation for local testing
src/app/(public)/dev/mock-portal/page.tsx	Mock authentication portal simulating production login flow
src/app/api/referral/route.ts	Updated GET endpoint to use requireAdmin() from DAL
src/actions/referral.ts	Updated toggleRedeemed action to use requireAdmin()
test/api/referral-route.test.ts	Updated tests to mock requireAdmin instead of verifyDatabaseAccess
test/actions/referral.test.ts	Updated tests to mock requireAdmin instead of verifyDatabaseAccess
e2e/referral-database.spec.ts	Updated E2E tests to use mock portal login flow
src/lib/db.ts	Added TiDB adapter for Vercel production environment
src/env.ts	Added PRFC_PORTAL_SECRET validation with 32-character minimum
src/schema/error.ts	Added FORBIDDEN error code for authorization failures
src/utils/errors.ts	Added 403 status mapping for FORBIDDEN error code
docs/README.md	New documentation index linking to all guides and ADRs
docs/getting-started.md	Comprehensive setup guide with fnm, Docker, and environment configuration
docs/contributing.md	Development workflow guide with CI/CD pipeline explanation
docs/architecture.md	System overview with diagrams, tech stack, and key patterns
docs/style-guide.md	Code conventions covering naming, imports, types, and error handling
docs/first-exercise.md	Onboarding exercise guiding new developers to create team page
docs/decisions/*.md	Four ADRs explaining Prisma/MySQL, Server Actions, auth patterns, and CI/CD choices
test/README.md	Test structure documentation with commands and mock descriptions
src/README.md	Source directory guide explaining folder structure and conventions
.github/ISSUE_TEMPLATE/*.yml	YAML forms for bug reports, feature requests, and onboarding issues
.github/pull_request_template.md	Simplified PR template focusing on changes and testing steps
.github/workflows/ci.yml	Added TypeScript type checking step before build
package.json	Added TiDB adapter dependencies and Node.js engine requirement
.env.local.example	Updated with PRFC_PORTAL_SECRET and removed DATABASE_PASSWORD

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.