# {{PROJECT_NAME}} Development Rules > **Read and follow all rules in AGENTS.md at the project root.** It contains mandatory security constraints for database, API, and infrastructure code. ## Security Quick Reference - MUST check auth on every endpoint: `if (!c.get('user')) return c.json({ error: 'Unauthorized' }, 401)` - MUST validate all input with Zod schemas before processing - MUST run user-facing queries through `withUserDb(user.id, (tx) => ...)` from `src/server/db/client.ts` (runs as role `app_user`, RLS applies). `adminDb` bypasses RLS: only in the files `tests/structural/db-access-census.test.ts` allows, and only after checking the caller may touch the rows - MUST enable RLS on every new table, with policies `TO app_user` reading `(SELECT app.user_id())`, and a `WITH CHECK` mirroring `USING` on every write policy - NEVER build SQL text from input: use Drizzle's query builder or the `sql` template (bound parameters), never `sql.raw()` with user input - MUST log database errors as `dbErrorForLog(err)`, never `err.message` (it carries the SQL and bound values) - MUST read the signed-in user from the session middleware (`c.get('user')`, `c.get('session')`); check super admin with `isSuperAdmin(user)` from `src/server/lib/auth.ts` - NEVER return raw database errors to clients - NEVER expose `BETTER_AUTH_SECRET` (or any server-only secret) to the client: nothing secret may carry a `VITE_` prefix ## Stack - Frontend: React 19, Vite, React Router, TanStack Query, Shadcn UI, Launch UI, Tailwind CSS v4 - Backend: Hono (Node.js), Pino logger, Zod validation - Database: PostgreSQL via Drizzle ORM (`src/server/db/`), RLS on every table - Auth: In-process auth in the API server (Better Auth, `src/server/auth/`) - Tooling: Biome (lint/format), TypeScript, esbuild, Vitest ## Commands - `npm run dev:start` - Full cold start (Docker + migrations + dev servers) - `npm run dev` - Start API and Vite dev servers - `npm run build` - Build client and server - `npm run lint` - Biome linting - `npm run typecheck` - TypeScript checking - `npm test` - Run vitest tests - `npm run db:migrate` - Run SQL migrations ## Path Aliases - `@/*` → `src/client/*` - `@shared/*` → `src/shared/*` - Never use `@/shared/*` - it won't resolve ## Key Patterns ### Database access - The browser never queries the database: it calls `/api/v1` routes (via `apiJson` in `src/client/lib/api.ts`) - Server: `withUserDb(userId | null, fn)` for anything done for a user or anonymous visitor (default); `adminDb` for webhooks, admin tools, jobs (bypasses RLS) - New table: migration in `db/migrations/` (RLS + policies in the same file), then its Drizzle definition in `src/server/db/schema.ts` - Use `(SELECT app.user_id())` in RLS policies (not bare `app.user_id()`), so it is evaluated once per statement ### Auth (Better Auth, in-process) - Server: the auth instance lives in `src/server/auth/`, mounted at `/api/auth`; sessions are HttpOnly cookies - Client: use `useAuth()` from `src/client/components/auth/AuthProvider.tsx`; never handle tokens in page code - Don't build a parallel auth path: extend the existing auth instance (plugins, hooks) instead ### API Routes - Create in `src/server/routes/v1/`, mount in `src/server/index.ts` - Validate input with Zod schemas - Get user via `c.get('user')`, query via `withUserDb(user.id, (tx) => ...)` ### React Pages - Protected pages: wrap with `` in `App.tsx` - Admin pages: wrap with `` - App pages use `` + `` + `` layout ### UI - **Two design libraries**: Shadcn UI primitives (`src/client/components/ui/`) for interface elements; Launch UI blocks (MIT, vendored copy/paste; retinted to the OKLCH palette) for marketing/landing sections. Build custom only when neither fits — and comment why. - Shadcn UI components in `src/client/components/ui/` - Use `cn()` from `@/lib/utils` for conditional classes - Use `toast` from `sonner` for notifications - Button `asChild` with Link children: add `className="inline-flex items-center gap-2"` to the Link, `shrink-0` on icons ### Data Fetching - **NEVER use raw `fetch` in `useEffect`** — always use `useQuery` for reads, `useMutation` for writes. Raw fetch bypasses deduplication/caching and React StrictMode will double-fire it. - **Gate authenticated queries** with `enabled: !!user` to prevent 401s for logged-out users - **Call the API through `apiJson` / `apiFetch`** from `@/lib/api.ts`: the session is an HttpOnly cookie sent same-origin, so never add an `Authorization` header - Shared hooks in `src/client/hooks/api/` - Invalidate related queries after mutations: `queryClient.invalidateQueries({ queryKey: ['items'] })` ### Database (migrations) - Schema changes start in `src/server/db/schema.ts`; `npx drizzle-kit generate` writes the migration to `db/migrations/`, and the app applies it at startup - Always enable RLS on new tables - Helper functions: `get_user_org_ids()`, `get_user_admin_org_ids()`, `is_super_admin()` ### Environment Variables - Server env vars validated in `src/server/lib/env.ts` - Client env vars must start with `VITE_` - Feature flags use `isXConfigured()` pattern