# TaskFlow Project management app with real-time collaboration, Kanban boards, and team dashboards. ## Stack - **Language**: TypeScript 5.x - **Frontend**: Next.js 15 (App Router), Tailwind CSS 4, shadcn/ui - **Backend**: Next.js API Routes + tRPC 11 for type-safe RPC - **Database**: PostgreSQL 16, Drizzle ORM - **Auth**: NextAuth.js 5 (GitHub + Google OAuth, magic link) - **Real-time**: Liveblocks (collaborative cursors, presence, storage) - **File Storage**: Uploadthing (S3-backed uploads) - **Email**: React Email + Resend - **Testing**: Vitest (unit), Playwright (e2e) - **Package Manager**: pnpm - **Deployment**: Vercel (frontend), Neon (serverless Postgres) ## Commands - `pnpm install` - Install dependencies - `pnpm dev` - Start Next.js dev server (localhost:3000) - `pnpm build` - Production build - `pnpm start` - Start production server - `pnpm test` - Run Vitest unit tests - `pnpm test:e2e` - Run Playwright tests - `pnpm test:e2e --ui` - Playwright tests with UI mode - `pnpm lint` - ESLint + Prettier check - `pnpm typecheck` - TypeScript compiler check - `pnpm db:push` - Push schema changes to database - `pnpm db:migrate` - Generate and apply migrations - `pnpm db:studio` - Open Drizzle Studio (localhost:4983) - `pnpm db:seed` - Seed database with sample data - `pnpm email:dev` - Preview email templates (localhost:3001) ## Project Structure ``` src/ app/ (auth)/ - Auth pages (sign-in, sign-up, verify) (dashboard)/ - Authenticated dashboard layout projects/ - Project list and detail pages boards/ - Kanban board views settings/ - User and team settings api/ trpc/[trpc]/ - tRPC HTTP handler webhooks/ - Stripe, GitHub webhook handlers uploadthing/ - File upload endpoint components/ ui/ - shadcn/ui primitives (Button, Dialog, Card) layout/ - Shell, Sidebar, Header, Breadcrumbs boards/ - Kanban-specific components (Column, Card, DragOverlay) forms/ - Form components with react-hook-form + zod server/ db/ schema.ts - Drizzle schema definitions index.ts - Database client migrations/ - Generated migration SQL files trpc/ router.ts - Root tRPC router context.ts - tRPC context (session, db) procedures/ - Individual procedure files (projects, tasks, teams) auth/ config.ts - NextAuth.js configuration providers.ts - OAuth provider setup email/ templates/ - React Email components send.ts - Resend client wrapper lib/ utils.ts - Utility functions (cn, formatDate, slugify) constants.ts - App-wide constants validators.ts - Shared Zod schemas hooks/ - Custom React hooks (useDebounce, useMediaQuery) types/ - Shared TypeScript types public/ - Static assets (favicon, og-image) ``` ## Conventions ### Frontend - Server Components by default. Add `'use client'` only for interactivity. - Use `next/image` for all images. No raw `<img>` tags. - Forms use `react-hook-form` with `zodResolver` for validation. - Loading states: use Next.js `loading.tsx` and Suspense boundaries. - Error states: use `error.tsx` boundaries with retry buttons. - Optimistic updates via TanStack Query `onMutate` for mutations. ### Backend - All data access through tRPC procedures. No direct database calls in components. - Input validation with Zod schemas at the procedure level. - Use `protectedProcedure` for authenticated endpoints (enforces session check). - Transactions for multi-table writes using `db.transaction()`. - Background tasks: trigger via API route, process in Vercel Cron or Edge Functions. ### Database - Drizzle schema as source of truth. Generate migrations with `drizzle-kit`. - Use `serial` for internal IDs, `text` with `cuid2()` for public-facing IDs. - All tables include `createdAt` and `updatedAt` with database defaults. - Soft delete via `deletedAt` column for projects and tasks. - Index foreign keys and columns used in filters. ### Testing - 80% coverage minimum on `server/` directory. - Unit test tRPC procedures with mocked database. - E2E tests for: auth flow, project CRUD, board drag-and-drop, team invite. - Visual regression tests for key UI states using Playwright screenshots. ## Environment Variables - `DATABASE_URL` - Neon PostgreSQL connection string - `NEXTAUTH_SECRET` - Auth session encryption key - `NEXTAUTH_URL` - Base URL (http://localhost:3000 in dev) - `GITHUB_CLIENT_ID` / `GITHUB_CLIENT_SECRET` - GitHub OAuth - `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` - Google OAuth - `LIVEBLOCKS_SECRET_KEY` - Real-time collaboration - `UPLOADTHING_SECRET` - File upload service - `RESEND_API_KEY` - Email sending - `STRIPE_SECRET_KEY` / `STRIPE_WEBHOOK_SECRET` - Payments ## Key Decisions | Date | Decision | Rationale | |------|----------|-----------| | 2025-07-01 | Drizzle over Prisma | Better SQL control, lighter runtime, edge-compatible | | 2025-07-15 | tRPC over REST | End-to-end type safety, reduced boilerplate | | 2025-08-01 | Liveblocks over PartyKit | Managed service, presence + storage primitives | | 2025-09-10 | shadcn/ui over Radix directly | Pre-styled, copy-paste, full ownership | | 2025-10-20 | Neon over Supabase | Serverless branching, Vercel integration |