API Overview

​

Architecture

​

Next.js 16 App Router

• Server Components: All pages are server components by default, fetching data server-side
• Server Actions: All mutations use Next.js server actions with "use server" directive
• Client Components: Interactivity isolated to specific UI components
• Streaming: Progressive rendering with React Suspense boundaries

​

Database Stack

​

Tech Stack Summary

​

Core Framework

• Next.js 16 (App Router, React 19, TypeScript)
• Deployment: Vercel with automatic preview deployments
• Path Aliases: @/ maps to project root

​

Styling & UI

• Tailwind CSS v4 with custom configuration
• shadcn/ui (new-york style) for component primitives
• Radix UI for accessible headless components
• Motion (Framer Motion) for animations
• Fonts: DM Sans (body), Instrument Serif (headings), DM Mono (code)

​

Authentication & Authorization

​

Data Layer

​

Integrations

​

Development Tools

​

Request Flow

​

Authentication Flow

1. User signs in via Clerk custom form (app/(auth)/sign-in)
2. Clerk middleware (proxy.ts) validates session
3. ensureProfile(clerkId) creates profile record just-in-time
4. Profile created with default user role
5. Subsequent requests use cached profile (React cache())

​

Data Mutation Flow

1. Client component calls server action
2. Server action:
   • Validates authentication via auth()
   • Ensures profile exists with ensureProfile()
   • Validates input with Zod schemas
   • Performs database mutations
   • Handles errors with Sentry
   • Revalidates affected paths
3. Returns ActionResult<T> type:
   | { success: true; data?: T }
   | { success: false; error: string }
   

​

Error Handling Pattern

try {
  const profileId = await getProfileId();
  // ... business logic
  revalidatePath("/path");
  return { success: true };
} catch (error) {
  if (isUniqueViolation(error, "constraint_name")) {
    return { success: false, error: "User-friendly message" };
  }
  Sentry.captureException(error, {
    tags: { component: "server-action", action: "actionName" },
    extra: { /* context */ },
  });
  return { success: false, error: "Generic error message" };
}

​

Environment Variables

​

Required (Development & Production)

• DATABASE_URL — Neon Postgres connection string
• NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY — Clerk publishable key
• CLERK_SECRET_KEY — Clerk secret key
• NEXT_PUBLIC_CLERK_SIGN_IN_URL — /sign-in
• NEXT_PUBLIC_CLERK_SIGN_UP_URL — /sign-up
• NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL — /dashboard
• NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL — /hackathon
• ADMIN_USER_IDS — Comma-separated Clerk user IDs with super-admin access

​

Optional

• DISCORD_WEBHOOK_SIGNUPS — Discord webhook for signup notifications
• DISCORD_WEBHOOK_MILESTONES — Discord webhook for milestone alerts
• DISCORD_WEBHOOK_TEAM_CHAT — Discord webhook for team chat notifications
• NEXT_PUBLIC_MAPBOX_TOKEN — Mapbox access token for Globe component
• TWITCH_CLIENT_ID — Twitch API client ID for streamers feature
• TWITCH_CLIENT_SECRET — Twitch API client secret
• LINEAR_API_KEY — Linear API key for issue tracking integration
• LINEAR_TEAM_ID — Linear team identifier
• LINEAR_PROJECT_ID — Linear project identifier
• LINEAR_LABEL_ID — Linear label identifier for categorization
• SENTRY_AUTH_TOKEN — Sentry authentication token for releases
• SENTRY_ORG — Sentry organization slug
• SENTRY_PROJECT — Sentry project slug

​

CI-Only

• PRODUCTION_DATABASE_URL — Production Neon connection string
• VERCEL_DEPLOY_HOOK — Vercel deploy hook URL

​

Next Steps