Asthra 10 - Technical Fest Management System

Build and maintain a full-stack technical fest management system with Next.js 15, tRPC for type-safe APIs, Drizzle ORM for PostgreSQL, role-based authentication, payment processing, and QR-based attendance tracking.

Architecture Overview

**Tech Stack**: Next.js 15 + React 19, tRPC, Drizzle ORM (PostgreSQL), NextAuth.js, TailwindCSS v4, Bun runtime

**Key Application Structure**:

Development Workflow

Environment Setup

```bash

bun install # Install dependencies

bun run dev # Start development server

bun run db:push # Push schema changes to database

bun run db:studio # Open Drizzle Studio for database management

```

Key Commands

tRPC Router Organization

1. **Feature-Based Routers**: Organize routers by domain (`userRouter`, `eventRouter`, `asthraRouter`)

2. **Role-Based Middleware**: Use built-in procedures for access control

3. **Type-Safe Communication**: Server-side uses `api` from `trpc/server.ts`, client-side uses `api` from `trpc/react.tsx`

tRPC Usage Patterns

**Client-side queries with loading state:**

```tsx

const { data, isLoading } = api.event.getAll.useQuery()

```

**Conditional queries with parameters:**

```tsx

const { data: isRegistered } = api.user.isRegisteredThisEvent.useQuery(

{ eventId: event.id },

{ enabled: status === "authenticated" && valid }

)

```

**Mutations with error handling:**

```tsx

const { mutateAsync, isPending } = api.event.registerEvent.useMutation({

onError: (error) => {

toast.error(error.data?.code, {

description: error.message,

})

},

onSuccess: () => toast("Registration successful")

})

```

**Mutations with optimistic updates:**

```tsx

const { mutate: editRole } = api.user.editUserRole.useMutation({

onSuccess: () => {

queryClient.invalidateQueries(['user', 'getUserList'])

}

})

```

**Server-side usage in pages:**

```tsx

// Direct API calls in server components

const event = await api.event.getSpecificCached({ id })

const user = await api.user.getUserForVerification({ id })

// With React cache for performance

const getEventData = reactCache(async (id: string) => {

return await api.event.getSpecificCached({ id })

})

```

Role-Based Access Control

Available Procedures (in `server/api/trpc.ts`)

User Roles Hierarchy

`USER` < `STUDENT_COORDINATOR` < `FACULTY_COORDINATOR` < `MANAGEMENT` < `ADMIN` < `DESK`

Database Schema Conventions

1. **Primary Keys**: All tables use `uuid` primary keys

2. **Enums**: Define with `pgEnum` for roles, departments, years, etc.

3. **Relations**: Define in separate `relations()` blocks

4. **Migrations**: Generate with `bun run db:generate`, apply with `bun run db:migrate`

Route Structure

Component Organization

Business Logic (in `logic/` directory)

Styling Conventions

1. **TailwindCSS v4**: Custom cursor variants and effect classes

2. **Dark Theme**: Default theme with custom CSS variables

3. **Typography**: `ambit` font class for branding

4. **Backgrounds**: Custom patterns and 3D Spline integration (fallback to static images on mobile)

Authentication Flow

1. Google OAuth and email providers configured

2. Custom Drizzle adapter for NextAuth.js

3. Session extended with full user object and role information

4. Profile completion middleware for dashboard access

External Service Integrations

Razorpay (Payments)

Email (Nodemailer)

S3/CloudFlare (File Uploads)

Spline (3D Backgrounds)

Key Data Flows

1. **User Registration**: User registration → Profile completion → Event registration → Payment → Email confirmation

2. **Event Management**: Event creation (coordinators) → Approval (management) → Public listing

3. **Attendance Tracking**: QR scanning via `@yudiel/react-qr-scanner`

Environment Configuration

All environment variables managed via `@t3-oss/env-nextjs` in `env.js` with strict validation. Required variables include:

Important Notes