Developer Onboarding Guide

This guide helps you understand the Eventuall codebase and start contributing. It's written for developers who are comfortable with TypeScript and React but new to this specific project.

Prerequisites

Before starting, you should understand:

  • TypeScript fundamentals (types, interfaces, generics)
  • React concepts (components, hooks, state management)
  • Basic SQL knowledge (queries, joins)
  • HTTP and REST API concepts
  • Git workflow basics

If you haven't already, follow the Quick Start Guide to get your development environment running.

Deep Dives

Each topic below has its own detailed page with code examples, architectural context, and pitfall callouts:

  • Authentication — NextAuth setup, Google OAuth, OTP login, custom D1 adapter, middleware, and the RBAC permission system
  • tRPC and Server Actions — The tRPC router tree, writing queries and mutations, Server Actions with next-safe-action, and when to use which
  • UI Components and Styling — shadcn/ui component library, the dual button variant system, form building with React Hook Form and Zod, and Tailwind CSS patterns
  • Testing and Debugging — Vitest setup, Cloudflare API mocking, client-side telemetry, error boundaries, and common debugging scenarios

Technology Stack at a Glance

Layer Technology Purpose
Frontend Next.js 15, React 19 App Router with Server Components
Styling Tailwind CSS, shadcn/ui Utility-first CSS with accessible component primitives
API tRPC End-to-end type-safe API calls
Forms Server Actions, next-safe-action Validated form submissions with auth middleware
Database Cloudflare D1, Drizzle ORM SQLite database with type-safe queries
Auth NextAuth 5.0 (beta) Google OAuth + OTP with database sessions
Video LiveKit WebRTC video/audio rooms
Chat Twilio Conversations Text messaging and reactions
State sync PartyKit (Durable Objects) Real-time presence, queue management via Yjs
Backend Cloudflare Workers, Hono Edge computing with Durable Objects
Infrastructure Terraform Per-environment Cloudflare resource provisioning

The Two Golden Rules

1. Server Components are the default. Only add "use client" when you need browser APIs, React hooks, or event handlers. Every "use client" directive creates a boundary — everything imported below it becomes part of the client bundle.

2. tRPC for data, Server Actions for forms. Use tRPC queries and mutations for reading data and programmatic changes (button clicks, polling). Use Server Actions for form submissions that need validation and progressive enhancement.

Project Structure

eventuall-app/
├── apps/
│   ├── webapp/              # Next.js 15 frontend
│   │   ├── src/
│   │   │   ├── app/         # App Router pages and layouts
│   │   │   ├── components/  # Shared React components
│   │   │   │   ├── ui/      # Base shadcn/ui components
│   │   │   │   ├── livekit/ # LiveKit video components
│   │   │   │   └── chat/    # Twilio chat components
│   │   │   ├── server/      # Server-side code
│   │   │   │   ├── api/     # tRPC routers
│   │   │   │   ├── actions/ # Server Actions
│   │   │   │   ├── auth/    # NextAuth config
│   │   │   │   └── db/      # Drizzle schema and client
│   │   │   ├── hooks/       # Custom React hooks
│   │   │   ├── trpc/        # tRPC client setup
│   │   │   └── utils/       # Shared utilities
│   │   └── drizzle/         # Database migrations
│   └── workers/             # Cloudflare Workers backend
│       └── src/
│           ├── durable-objects/ # Stateful edge logic
│           ├── routes/          # Hono API routes
│           └── db/              # Workers database schema
├── packages/
│   ├── eslint-config/       # Shared ESLint rules
│   └── typescript-config/   # Shared tsconfig
├── terraform/               # Infrastructure as Code
└── scripts/                 # Dev setup and utilities

Common Tasks

Adding a new tRPC endpoint

  1. Find or create a router file in apps/webapp/src/server/api/routers/
  2. Add a query or mutation using protectedProcedure (or publicProcedure if no auth needed)
  3. Define the input schema with Zod
  4. Register the router in apps/webapp/src/server/api/root.ts if it's new
  5. Call it from a Server Component (api.router.method()) or Client Component (api.router.method.useQuery())

Adding a new database table

  1. Define the table in apps/webapp/src/server/db/schema.ts
  2. Add relations if needed
  3. Run cd apps/webapp && pnpm generate to create a migration
  4. Run pnpm migrate:local to apply locally
  5. For remote/production: manually run pnpm wrangler d1 migrations apply <db-name> --remote

Adding a new UI component

  1. Check shadcn/ui docs for existing components
  2. Copy the component into apps/webapp/src/components/ui/
  3. Install any missing Radix UI dependencies
  4. Use cn() for class merging and React.forwardRef if wrapping a native element

Next Steps

Start with the Authentication page to understand how users sign in and how the permission system works. From there, move to tRPC and Server Actions to learn the data flow patterns you'll use daily.

For architecture-level context, see the Architecture Overview and its sub-pages.