Inbox

Email platform monorepo. Built on Next.js 16.

Source of truth

All coding rules, conventions, and architectural constraints live in AGENTS.md. Read it before contributing.

Stack

• Next.js 16 (App Router, Turbopack, React 19)
• TypeScript 5.9, strict mode
• Prisma 6 with PostgreSQL (Neon in production)
• Vitest (unit + integration) and Playwright (E2E)
• ESLint 9 flat config + Prettier
• Turborepo task graph
• pnpm workspace

Workspace layout

inbox/
  packages/
    web/                # Next.js 16 application
      src/              # app/, lib/, components/
      prisma/           # schema.prisma, seed.ts, migrations/
      tests/            # unit/, integration/, e2e/
      public/           # static assets
  docs/adr/             # architecture decision records
  AGENTS.md             # source-of-truth coding rules
  README.md             # this file
  package.json          # workspace root (shared devDeps)
  turbo.json            # Turborepo task graph
  pnpm-workspace.yaml   # pnpm workspace declaration
  eslint.config.mjs     # workspace-wide ESLint config
  tsconfig.base.json    # shared TS base for all packages

Local development

pnpm install
pnpm turbo dev

Or to work on the web package alone:

pnpm --filter web dev

Open http://localhost:3000.

Scripts (root)

Command	What it does
pnpm turbo	Run the full task graph (lint, typecheck, test:unit, format:check, build)
pnpm turbo:all	Run lint, typecheck, test:unit, test:integration, format:check, build
pnpm format	Prettier write across the workspace
pnpm format:check	Prettier check across the workspace

Scripts (web package)

Run with pnpm --filter web <script> from the repo root.

Command	What it does
pnpm dev	Start Next dev server (Turbopack)
pnpm build	Production build
pnpm start	Run production build
pnpm lint	ESLint flat config
pnpm typecheck	tsc --noEmit
pnpm test:unit	Vitest unit suite
pnpm test:integration	Vitest integration suite (requires DATABASE_URL)
pnpm test:e2e	Playwright E2E
pnpm db:generate	Prisma client generate
pnpm db:migrate:dev	Apply dev migrations
pnpm db:migrate:deploy	Apply migrations in CI/prod

Database

Phase 0 uses a local Postgres in Docker. No Docker available? Provision any reachable Postgres and set DATABASE_URL in packages/web/.env.

docker run --name inbox-pg -e POSTGRES_PASSWORD=postgres -p 5432:5432 -d postgres:16
echo 'DATABASE_URL=postgresql://postgres:postgres@localhost:5432/inbox_dev' > packages/web/.env
pnpm --filter web db:migrate:dev

Architectural decisions

• ADR-0001: Prisma 6 instead of locked Prisma 8
• ADR-0002: Monorepo structure with packages/web

Deployment (Vercel)

The Vercel project is named inbox and connected to this repo's main branch. The Next.js app lives at packages/web/; Vercel auto-detects the Turborepo monorepo and runs the build there.

Configuration: vercel.json (repo root). Key settings:

• framework: "nextjs" — explicit preset
• git.deploymentEnabled.main: true — only main produces production deploys; feature branches stay on Vercel previews if enabled
• github.autoAlias: true — auto-assign branch alias to preview URLs

When you create the project, set Root Directory to packages/web in the Vercel dashboard so pnpm install runs at the workspace root. Leave Build Command and Install Command empty so Vercel's Turborepo detection runs the canonical pnpm install and pnpm turbo run build.

Phase 0 deploys without a database (no DATABASE_URL is read at request time). Neon provisioning happens in Phase 1.