feat(hackathon): complete hackathon platform with SSO integration

[mjunaidca]

Summary

• New hackathon platform app (apps/hackathon) with complete CRUD operations for organizations, hackathons, teams, and submissions
• OAuth 2.1 + PKCE authentication integrated with SSO app via iron-session
• Multi-tenancy architecture with organization_id on all tables for data isolation
• Next.js 16 compatibility using new proxy.ts convention (replaces deprecated middleware.ts)
• Drizzle ORM with 11 tables and fresh migrations for Neon Postgres
• Tag-based cache invalidation for optimal performance
• Denormalized user data pattern storing username, name, email, image to minimize SSO API calls

Key Features

Feature	Description
Organizations	Multi-tenant organization management with member roles
Hackathons	Full lifecycle (draft → active → judging → completed)
Teams	Invite code system, size constraints, leader management
Submissions	Project submissions with repository/demo/presentation URLs
Judging	Weighted criteria scoring with judge assignment
Public Pages	/explore for discovery, /h/[id] for hackathon details

Database Schema

11 tables with proper foreign keys and cascade deletes:

• organizations, organization_members
• hackathons, hackathon_roles
• teams, team_members, team_messages
• submissions, scores, judging_criteria
• winners

Test Plan

• Run SSO app locally on port 3001
• Start hackathon app on port 3002
• Test OAuth login flow
• Create organization and hackathon
• Test team creation and invite code joining
• Verify submission and judging flows
• Confirm public pages work without auth

🤖 Generated with Claude Code

[mjunaidca]

Detailed Testing Guide

Prerequisites

1. Clone and install dependencies

   pnpm install

2. Database setup (already done - using Neon Postgres tpl database)

   cd apps/hackathon
   pnpm drizzle-kit push

3. Environment variables - Copy .env.local.example to .env.local:

   cp apps/hackathon/.env.local.example apps/hackathon/.env.local

---

Step 1: Start SSO App (Port 3001)

cd apps/sso
pnpm dev

Verify SSO is running: http://localhost:3001

Note: The hackathon app is registered as a trusted OAuth client in apps/sso/src/lib/trusted-clients.ts

---

Step 2: Generate M2M API Key (Required for user lookup)

1. Go to SSO admin or use Better Auth API to create an API key
2. Update apps/hackathon/.env.local:

   SSO_API_KEY="your-generated-api-key"
   

For development, you can temporarily use the dev key already set.

---

Step 3: Start Hackathon App (Port 3002)

cd apps/hackathon
pnpm dev

Verify app is running: http://localhost:3002

---

Test Scenarios

A. Authentication Flow

Test	Steps	Expected Result
Login redirect	Visit /dashboard without auth	Redirects to /login?returnUrl=/dashboard
OAuth flow	Click "Sign in with SSO"	Redirects to SSO, returns with session
Session persistence	Refresh page after login	Stays logged in
Logout	Click logout in navbar	Clears session, redirects to home

B. Organization Management

Test	Steps	Expected Result
Create org	POST /api/organizations with name, slug	Returns new organization
Add member	POST /api/organizations/[id]/members with username	Looks up user via M2M API, adds to org
List members	GET /api/organizations/[id]/members	Returns all members with roles

# Create organization
curl -X POST http://localhost:3002/api/organizations \
  -H "Content-Type: application/json" \
  -H "Cookie: hackathon-session=..." \
  -d '{"name": "Test Org", "slug": "test-org"}'

C. Hackathon CRUD

Test	Steps	Expected Result
Create hackathon	Fill form on /dashboard	Creates draft hackathon
Edit hackathon	Update via /hackathons/[id]/manage	Updates fields
Publish	Toggle publish on manage page	Sets published: true
View public	Visit /h/[slug]	Shows hackathon details

D. Team Formation

Test	Steps	Expected Result
Create team	On participate page, create team	Generates invite code
Join team	Enter invite code	Adds user to team
Team size limit	Try joining full team	Returns error
Leave team	Remove self from team	Updates membership

# Create team
curl -X POST http://localhost:3002/api/hackathons/[id]/teams \
  -H "Content-Type: application/json" \
  -H "Cookie: hackathon-session=..." \
  -d '{"name": "Team Alpha", "description": "Our awesome team"}'

# Join team
curl -X POST http://localhost:3002/api/hackathons/[id]/teams/join \
  -H "Content-Type: application/json" \
  -H "Cookie: hackathon-session=..." \
  -d '{"inviteCode": "ABC123"}'

E. Submissions

Test	Steps	Expected Result
Submit project	Fill submission form	Creates submission record
Edit submission	Update before deadline	Updates submission
View submission	On judge page	Shows all submission details

F. Judging System

Test	Steps	Expected Result
Add criteria	On manage page	Creates judging criteria
Assign judge	Add user with judge role	User can access judge page
Score submission	Fill scoring form	Saves scores per criterion
View analytics	On manage page	Shows score aggregates

# Add judging criteria
curl -X POST http://localhost:3002/api/hackathons/[id]/criteria \
  -H "Content-Type: application/json" \
  -H "Cookie: hackathon-session=..." \
  -d '{"name": "Innovation", "description": "How innovative is the solution?", "weight": 30, "maxScore": 10}'

# Submit scores
curl -X POST http://localhost:3002/api/hackathons/[id]/submissions/[subId]/score \
  -H "Content-Type: application/json" \
  -H "Cookie: hackathon-session=..." \
  -d '{"scores": [{"criterionId": "...", "score": 8, "feedback": "Great work!"}]}'

G. Public Pages (No Auth Required)

Page	URL	Test
Explore	/explore	Lists published hackathons
Hackathon detail	/h/[id]	Shows full hackathon info
Countdown timer	/h/[id]	Counts down to start/end

---

Database Verification

# Check tables were created
cd apps/hackathon
pnpm drizzle-kit studio

Or connect directly to Neon console to verify 11 tables:

• organizations, organization_members
• hackathons, hackathon_roles
• teams, team_members, team_messages
• submissions, scores, judging_criteria
• winners

---

API Endpoints Summary

Method	Endpoint	Auth	Description
GET	/api/hackathons	✅	List user's hackathons
POST	/api/hackathons	✅	Create hackathon
GET	/api/hackathons/[id]	✅	Get hackathon details
PATCH	/api/hackathons/[id]	✅	Update hackathon
POST	/api/hackathons/[id]/publish	✅	Toggle publish status
POST	/api/hackathons/[id]/register	✅	Register for hackathon
GET/POST	/api/hackathons/[id]/teams	✅	Team management
POST	/api/hackathons/[id]/teams/join	✅	Join team by invite code
GET/POST	/api/hackathons/[id]/submissions	✅	Submission management
GET/POST	/api/hackathons/[id]/submissions/[id]/score	✅	Judge scoring
GET/POST	/api/hackathons/[id]/criteria	✅	Judging criteria
GET/POST	/api/hackathons/[id]/roles	✅	Role assignment
GET/POST	/api/organizations	✅	Organization management
GET/POST	/api/organizations/[id]/members	✅	Member management

---

Known Limitations

1. M2M API Key: Requires a real API key from SSO for user lookup to work in production
2. Dev Login: /api/auth/dev-login exists for development testing (creates mock session)
3. No email notifications: Invites and announcements are in-app only
4. Single submission per team: Teams can only have one submission per hackathon

[mjunaidca]

Clarification: Organization Setup is a Prerequisite

The organization endpoints are required before creating hackathons. The flow is:

1. Create Organization → User becomes "owner"
2. Create Hackathon → Requires organizationId where user is owner/admin/manager

Quick Setup Commands

# 1. First create an organization (required)
curl -X POST http://localhost:3002/api/organizations \
  -H "Content-Type: application/json" \
  -H "Cookie: hackathon-session=<your-session>" \
  -d '{"name": "My Organization", "slug": "my-org"}'

# Response: {"id": "org_xxx", "name": "My Organization", ...}

# 2. Then create hackathon with that org ID
curl -X POST http://localhost:3002/api/hackathons \
  -H "Content-Type: application/json" \
  -H "Cookie: hackathon-session=<your-session>" \
  -d '{
    "organizationId": "org_xxx",
    "title": "My Hackathon",
    "slug": "my-hackathon",
    "description": "A test hackathon",
    "startDate": "2025-01-15T00:00:00Z",
    "endDate": "2025-01-17T00:00:00Z",
    "registrationDeadline": "2025-01-14T00:00:00Z",
    "submissionDeadline": "2025-01-17T00:00:00Z"
  }'

The member management (GET /api/organizations/[id]/members) is for adding judges/co-organizers to your org - optional but useful for multi-user testing.

[mjunaidca]

⚠️ Architecture Correction Needed

Current Implementation (Wrong)

The hackathon app has its own organizations table and CRUD endpoints. This duplicates SSO's organization management.

Correct Architecture

SSO is the single source of truth for organizations.

From SSO docs (apps/sso/docs/default-organization-setup.md):

• Default org: panaversity-default-org-id (auto-created on seed)
• All users auto-join on signup
• JWT contains tenant_id (organization ID)

What Needs to Change

1. Remove /api/organizations endpoints from hackathon app
2. Get organizationId from SSO session/JWT (not manual creation)
3. Keep organization_id column in tables (for data isolation)
4. Keep organizations table but only for caching/reference (no CRUD)

Correct Testing Flow

# 1. Start SSO and run seed (creates default org)
cd apps/sso
pnpm run seed:setup  # Creates "Panaversity" org + admin user

# 2. Start hackathon app
cd apps/hackathon
pnpm dev

# 3. Login via SSO - user already has organizationId in token
# 4. Create hackathon - uses organizationId from session automatically

Follow-up PR Required

• Remove organization CRUD from hackathon app
• Extract organizationId from JWT/session
• Update hackathon creation to auto-use session's orgId

This PR can be merged as-is for testing, but the organization management should be removed in a follow-up.

[mjunaidca]

✅ Architecture Correction Completed

The organizations tables and CRUD endpoints have been removed. SSO is now the single source of truth for organizations.

What Changed

1. Removed /api/organizations endpoints (no longer needed)
2. Removed organizations and organization_members tables
3. Updated all routes to get organizationId from SSO session/JWT
4. Kept organization_id column in tables for data isolation (plain text, not FK)

Current Tables (9 total)

• hackathons - Main hackathon entity
• hackathon_roles - User roles per hackathon
• judging_criteria - Scoring criteria
• teams - Participant teams
• team_members - Team membership
• team_messages - Team chat
• submissions - Project submissions
• scores - Judge scores
• winners - Winner announcements

Testing Flow

# 1. Start SSO and run seed (creates default org + admin user)
cd apps/sso
pnpm run seed:setup

# 2. Start hackathon app
cd apps/hackathon
pnpm dev

# 3. Login via SSO (/dashboard → redirects to SSO login)
# User gets organizationId from JWT automatically

# 4. Create hackathon
POST /api/hackathons
{
  "title": "AI Innovation Challenge",
  "description": "Build AI solutions",
  "slug": "ai-innovation-2025",
  "startDate": "2025-01-15T00:00:00Z",
  "endDate": "2025-01-17T23:59:59Z",
  "registrationDeadline": "2025-01-14T23:59:59Z",
  "submissionDeadline": "2025-01-17T18:00:00Z"
}
# organizationId is automatically extracted from session

# 5. Test teams, submissions, judging, etc.

No Organization Management Required

• All users auto-join default organization on SSO signup
• organizationId flows through JWT → session → API routes
• Multi-tenancy works via organization_id column filtering

[mjunaidca]

✅ Dynamic Submission Fields & External Form Sync Added

New Features

1. Custom Form Builder - Organizers define fields per hackathon:

PUT /api/hackathons/[id]/submission-fields
{
  "fields": [
    { "name": "youtube_demo", "label": "YouTube Demo Link", "type": "url", "required": true, "order": 0 },
    { "name": "tech_stack", "label": "Tech Stack Used", "type": "text", "required": false, "order": 1 }
  ]
}

2. External Form Sync - Import from Google Forms CSV:

POST /api/hackathons/[id]/submissions/sync
{
  "csvContent": "Email,Name,GitHub URL...\nuser@example.com,...",
  "columnMapping": {
    "email": "Email",
    "repositoryUrl": "GitHub URL"
  },
  "updateExisting": true
}

Response:
{
  "success": true,
  "results": {
    "totalRows": 50,
    "matched": 45,      // Found in registered teams
    "unmatched": 5,     // Email not in teams
    "created": 40,      // New submissions
    "updated": 5        // Existing updated
  }
}

3. Sync History - Track all CSV imports:

GET /api/hackathons/[id]/submissions/sync-history

Schema Updates (11 tables now)

Table	Change
hackathons	+submissionMode, +externalFormUrl
submissions	+submitterEmail, +formData, +syncedFromExternal, +syncedAt
submission_fields	NEW - custom form definitions
submission_syncs	NEW - sync history

Submission Modes

Mode	Description
platform	Use built-in form (default + custom fields)
external	Use Google Forms only (sync via CSV)
hybrid	Platform basics + external for extras

How Email Matching Works

1. Participants register for hackathon → join team → email stored
2. Organizer downloads Google Forms responses as CSV
3. Uploads CSV via sync API
4. System matches by email → creates/updates submissions
5. Unmatched emails reported for follow-up

[mjunaidca]

✅ Final Review Complete - Ready to Ship

All Changes Committed & Pushed

Commit	Description
96bdc193	Core hackathon platform with SSO integration
8dde6462	Dynamic submission fields + external form sync
ffd87757	Scalability fixes (connection pooling, batch ops, N+1 fix, rate limiting)
20378caa	OIDC claim name mapping (preferred_username → username)
f19549ad	SSO M2M response parsing fix (unwrap { user: ... } envelope)
19a63315	UI polish, cache fixes, package updates

Hardcoded Values Check ✅

• ✅ No hardcoded secrets or API keys
• ✅ All config via environment variables
• ✅ Dev-only endpoints protected (NODE_ENV === "production" check)
• ✅ Branding ("Panaversity") is intentional for public UI
• ✅ .env.example has all required variables documented

Environment Variables Required

DATABASE_URL=...
SSO_OAUTH_CLIENT_ID=...
SSO_OAUTH_REDIRECT_URI=...
SSO_OAUTH_AUTHORIZE_URL=...
SSO_OAUTH_TOKEN_URL=...
SSO_OAUTH_JWKS_URL=...
SSO_OAUTH_ISSUER=...
NEXT_PUBLIC_SSO_URL=...
SSO_API_KEY=...
SESSION_SECRET=...
NEXT_PUBLIC_APP_URL=...
NEXT_PUBLIC_APP_NAME=...

Ready for Testing & Deployment 🚀