# AGENTS.md - Server App Guidelines

TanStack Start fullstack web app with ORPC (contract-first RPC).

## Tech Stack

> **⚠️ This project uses Bun — NOT Node.js / npm. All commands use `bun`. Always use `bun run <script>` (not `bun <script>`) to avoid conflicts with Bun built-in subcommands. Never use `npm`, `npx`, or `node`.**

- **Framework**: TanStack Start (React 19 SSR, file-based routing)
- **Runtime**: Bun — **NOT Node.js**
- **Package Manager**: Bun — **NOT npm / yarn / pnpm**
- **Language**: TypeScript (strict mode)
- **Styling**: Tailwind CSS v4
- **Database**: PostgreSQL + Drizzle ORM v1 beta (`drizzle-orm/postgres-js`, RQBv2)
- **State**: TanStack Query v5
- **RPC**: ORPC (contract-first, type-safe)
- **Build**: Vite + Nitro

## Commands

```bash
# Development
bun run dev                    # Vite dev server (localhost:3000)
bun run db:studio              # Drizzle Studio GUI

# Build
bun run build                  # Production build → .output/
bun run compile                # Compile to standalone binary (current platform, depends on build)
bun run compile:darwin         # Compile for macOS (arm64 + x64)
bun run compile:darwin:arm64   # Compile for macOS arm64
bun run compile:darwin:x64     # Compile for macOS x64
bun run compile:linux          # Compile for Linux (x64 + arm64)
bun run compile:linux:arm64    # Compile for Linux arm64
bun run compile:linux:x64      # Compile for Linux x64
bun run compile:windows        # Compile for Windows (default: x64)
bun run compile:windows:x64    # Compile for Windows x64

# Code Quality
bun run fix                    # Biome auto-fix
bun run typecheck              # TypeScript check

# Database
bun run db:generate            # Generate migrations from schema
bun run db:migrate             # Run migrations
bun run db:push                # Push schema directly (dev only)

# Testing (not yet configured)
bun test path/to/test.ts       # Run single test
bun test -t "pattern"          # Run tests matching pattern
```

## Directory Structure

```
src/
├── client/                # Client-side code
│   └── orpc.ts            # ORPC client + TanStack Query utils (single entry point)
├── components/            # React components
├── routes/                # TanStack Router file routes
│   ├── __root.tsx         # Root layout
│   ├── index.tsx          # Home page
│   └── api/
│       ├── $.ts           # OpenAPI handler + Scalar docs
│       ├── health.ts      # Health check endpoint
│       └── rpc.$.ts       # ORPC RPC handler
├── server/                # Server-side code
│   ├── api/               # ORPC layer
│   │   ├── contracts/     # Input/output schemas (Zod)
│   │   ├── middlewares/   # Middleware (db provider, auth)
│   │   ├── routers/       # Handler implementations
│   │   ├── interceptors.ts # Shared error interceptors
│   │   ├── context.ts     # Request context
│   │   ├── server.ts      # ORPC server instance
│   │   └── types.ts       # Type exports
│   └── db/
│       ├── schema/        # Drizzle table definitions
│       ├── fields.ts      # Shared field builders (id, createdAt, updatedAt)
│       ├── relations.ts   # Drizzle relations (defineRelations, RQBv2)
│       └── index.ts       # Database instance (postgres-js driver)
├── env.ts                 # Environment variable validation
├── router.tsx             # Router configuration
├── routeTree.gen.ts       # Auto-generated (DO NOT EDIT)
└── styles.css             # Tailwind entry
```

## ORPC Pattern

### 1. Define Contract (`src/server/api/contracts/feature.contract.ts`)
```typescript
import { oc } from '@orpc/contract'
import { createSelectSchema } from 'drizzle-orm/zod'
import { z } from 'zod'
import { featureTable } from '@/server/db/schema'

const selectSchema = createSelectSchema(featureTable)

export const list = oc.input(z.void()).output(z.array(selectSchema))
export const create = oc.input(insertSchema).output(selectSchema)
```

### 2. Implement Router (`src/server/api/routers/feature.router.ts`)
```typescript
import { ORPCError } from '@orpc/server'
import { db } from '../middlewares'
import { os } from '../server'

export const list = os.feature.list.use(db).handler(async ({ context }) => {
  return await context.db.query.featureTable.findMany({
    orderBy: { createdAt: 'desc' },
  })
})
```

### 3. Register in Index Files
```typescript
// src/server/api/contracts/index.ts
import * as feature from './feature.contract'
export const contract = { feature }

// src/server/api/routers/index.ts
import * as feature from './feature.router'
export const router = os.router({ feature })
```

### 4. Use in Components
```typescript
import { useSuspenseQuery, useMutation } from '@tanstack/react-query'
import { orpc } from '@/client/orpc'

const { data } = useSuspenseQuery(orpc.feature.list.queryOptions())
const mutation = useMutation(orpc.feature.create.mutationOptions())
```

## Database (Drizzle ORM v1 beta)

- **Driver**: `drizzle-orm/postgres-js` (NOT `bun-sql`)
- **Validation**: `drizzle-orm/zod` (built-in, NOT separate `drizzle-zod` package)
- **Relations**: Defined via `defineRelations()` in `src/server/db/relations.ts`
- **Query**: RQBv2 — use `db.query.tableName.findMany()` with object-style `orderBy` and `where`

### Schema Definition
```typescript
import { pgTable, text, timestamp, uuid } from 'drizzle-orm/pg-core'
import { sql } from 'drizzle-orm'

export const myTable = pgTable('my_table', {
  id: uuid().primaryKey().default(sql`uuidv7()`),
  name: text().notNull(),
  createdAt: timestamp({ withTimezone: true }).notNull().defaultNow(),
  updatedAt: timestamp({ withTimezone: true }).notNull().defaultNow().$onUpdateFn(() => new Date()),
})
```

### Relations (RQBv2)
```typescript
// src/server/db/relations.ts
import { defineRelations } from 'drizzle-orm'
import * as schema from './schema'

export const relations = defineRelations(schema, (r) => ({
  // Define relations here using r.one / r.many / r.through
}))
```

### DB Instance
```typescript
// src/server/db/index.ts
import { drizzle } from 'drizzle-orm/postgres-js'
import { relations } from '@/server/db/relations'
// In RQBv2, relations already contain schema info — no separate schema import needed

const db = drizzle({
  connection: env.DATABASE_URL,
  relations,
})
```

### RQBv2 Query Examples
```typescript
// Object-style orderBy (NOT callback style)
const todos = await db.query.todoTable.findMany({
  orderBy: { createdAt: 'desc' },
})

// Object-style where
const todo = await db.query.todoTable.findFirst({
  where: { id: someId },
})
```

## Code Style

### Formatting (Biome)
- **Indent**: 2 spaces
- **Quotes**: Single `'`
- **Semicolons**: Omit (ASI)
- **Arrow parens**: Always `(x) => x`

### Imports
Biome auto-organizes:
1. External packages
2. Internal `@/*` aliases
3. Type imports (`import type { ... }`)

```typescript
import { createFileRoute } from '@tanstack/react-router'
import { z } from 'zod'
import { db } from '@/server/db'
import type { ReactNode } from 'react'
```

### TypeScript
- `strict: true`
- `noUncheckedIndexedAccess: true` - array access returns `T | undefined`
- Use `@/*` path aliases (maps to `src/*`)

### Naming
| Type | Convention | Example |
|------|------------|---------|
| Files (utils) | kebab-case | `auth-utils.ts` |
| Files (components) | PascalCase | `UserProfile.tsx` |
| Components | PascalCase arrow | `const Button = () => {}` |
| Functions | camelCase | `getUserById` |
| Types | PascalCase | `UserProfile` |

### React
- Use arrow functions for components (Biome enforced)
- Use `useSuspenseQuery` for guaranteed data
- Let React Compiler handle memoization (no manual `useMemo`/`useCallback`)

## Environment Variables

```typescript
// src/env.ts - using @t3-oss/env-core
import { createEnv } from '@t3-oss/env-core'
import { z } from 'zod'

export const env = createEnv({
  server: {
    DATABASE_URL: z.string().url(),
  },
  clientPrefix: 'VITE_',
  client: {
    VITE_API_URL: z.string().optional(),
  },
})
```

## Development Principles

> **These principles apply to ALL code changes. Agents MUST follow them on every task.**

1. **No backward compatibility** — This project is in rapid iteration. Always use the latest API and patterns. Never keep deprecated code paths or old API fallbacks.
2. **Always sync documentation** — When code changes, immediately update all related documentation (`AGENTS.md`, `README.md`, inline code examples). Code and docs must never drift apart.
3. **Forward-only migration** — When upgrading dependencies, fully adopt the new API. Don't mix old and new patterns.

## Critical Rules

**DO:**
- Run `bun run fix` before committing
- Use `@/*` path aliases
- Include `createdAt`/`updatedAt` on all tables
- Use `ORPCError` with proper codes
- Use `drizzle-orm/zod` (NOT `drizzle-zod`) for schema validation
- Use RQBv2 object syntax for `orderBy` and `where`
- Update `AGENTS.md` and other docs whenever code patterns change

**DON'T:**
- Use `npm`, `npx`, `node`, `yarn`, `pnpm` — always use `bun` / `bunx`
- Edit `src/routeTree.gen.ts` (auto-generated)
- Use `as any`, `@ts-ignore`, `@ts-expect-error`
- Commit `.env` files
- Use empty catch blocks
- Import from `drizzle-zod` (use `drizzle-orm/zod` instead)
- Use RQBv1 callback-style `orderBy` / old `relations()` API
- Use `drizzle-orm/bun-sql` driver (use `drizzle-orm/postgres-js`)
- Pass `schema` to `drizzle()` constructor (only `relations` is needed in RQBv2)
- Import `os` from `@orpc/server` in middleware — use `@/server/api/server` (the local typed instance)
- Leave docs out of sync with code changes