Add docker-compose for local Postgres and fix the setup docs

Adds docker-compose.yml (Postgres on host port 5433, to avoid clashing
with another project's container already using 5432 on this machine)
and .env.example so `docker compose up -d` + `cp .env.example .env.local`
gets a working local DB. Adds a db:seed script alongside the existing
db:* scripts.

Rewrites README's "Adding a Database" section, which still described
Better Auth's DB as optional/hypothetical even though this project
already requires Postgres for both its own data and Better Auth's
tables. Fills in CLAUDE.md's Data layer connection-details placeholder
and fixes two more stale pnpm references and a wrong migrations path
(src/db/migrations/ instead of the actual drizzle/) found nearby.

Also fixes a real bug the new docs surfaced: `npm run db:seed` didn't
load .env.local the way drizzle-kit does, so DATABASE_URL was silently
unset when run as documented. seed.ts now loads env the same way
drizzle.config.ts already does.

Verified the full documented flow end-to-end against a fresh container:
migrate, better-auth migrate, seed, dev server, real page render.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

.env.example

@@ -0,0 +1 @@
+DATABASE_URL=postgres://postgres:postgres@localhost:5433/ghost_kitchen

CLAUDE.md

@@ -44,12 +44,13 @@ src/
 ├── db/
 │   ├── schema.ts         # Drizzle schema definitions
 │   ├── index.ts          # Drizzle client instance
-│   └── migrations/       # generated SQL migrations — never hand-edit
+│   └── seed.ts            # sample data for local dev / tests
 ├── styles/
 │   ├── globals.scss      # global styles, resets
 │   └── _variables.scss   # shared SCSS variables/mixins (partial)
 public/                  # static assets
 drizzle.config.ts         # Drizzle Kit config (schema path, out dir, dialect)
+drizzle/                  # generated SQL migrations — never hand-edit
 ```
 
 ### Routing conventions
@@ -116,14 +117,17 @@ drizzle.config.ts         # Drizzle Kit config (schema path, out dir, dialect)
 - After changing `schema.ts`, generate a migration rather than editing the
   database by hand:
   ```bash
-  pnpm drizzle-kit generate   # create a migration from schema changes
-  pnpm drizzle-kit migrate    # apply pending migrations
+  npm run db:generate   # create a migration from schema changes
+  npm run db:migrate    # apply pending migrations
   ```
-- Never hand-edit files under `db/migrations/` — they're generated and
-  should be treated as a history, not touched retroactively.
-- [Connection details: env var name for `DATABASE_URL`, whether using a
-  connection pool like `postgres.js` or `node-postgres`, local dev DB setup
-  e.g. Docker Compose]
+- Never hand-edit files under `drizzle/` (the migrations output directory,
+  configured in `drizzle.config.ts`) — they're generated and should be
+  treated as a history, not touched retroactively.
+- Connection string comes from `DATABASE_URL` (see `.env.example`), read via
+  `drizzle-orm/node-postgres`. Local dev DB is a `docker-compose.yml`
+  Postgres container — see the README's "Local development database"
+  section. `.env.local` is picked up automatically by both the dev server
+  and `drizzle-kit`; no manual sourcing needed.
 
 ## Testing
 
@@ -134,7 +138,7 @@ drizzle.config.ts         # Drizzle Kit config (schema path, out dir, dialect)
 
 ## Things to avoid
 
-- Don't hand-edit `routeTree.gen.ts` or files under `db/migrations/`.
+- Don't hand-edit `routeTree.gen.ts` or files under `drizzle/`.
 - Don't run destructive Drizzle commands (`drizzle-kit push` against a
   populated DB, or anything that drops columns/tables) without confirming
   first — prefer `generate` + `migrate` so changes are reviewable.

README.md

@@ -9,6 +9,10 @@ npm install
 npm run dev
 ```
 
+This requires a running Postgres database — see
+[Local development database](#local-development-database) below before your
+first run.
+
 # Building For Production
 
 To build this application for production:
@@ -42,38 +46,43 @@ npm run check
 ```
 
 
+## Local development database
+
+This project requires a Postgres database — both for its own data (Drizzle,
+see `src/db/schema.ts`) and for Better Auth's own tables (users, sessions,
+etc). A `docker-compose.yml` at the repo root starts one:
+
+```bash
+docker compose up -d           # starts Postgres on localhost:5433
+cp .env.example .env.local     # sets DATABASE_URL to match
+npm run db:migrate             # applies this project's Drizzle migrations
+npx @better-auth/cli migrate   # applies Better Auth's own tables
+npm run db:seed                # seeds a sample Brand, menu, and Machines
+npm run dev
+```
+
+`DATABASE_URL` in `.env.local` is picked up automatically by both the dev
+server and the `drizzle-kit` commands above — no other wiring needed.
+
+After changing `src/db/schema.ts`, generate and apply a new migration rather
+than editing the database by hand:
+
+```bash
+npm run db:generate
+npm run db:migrate
+```
+
 ## Setting up Better Auth
 
-1. Generate and set the `BETTER_AUTH_SECRET` environment variable in your `.env.local`:
+Generate and set the `BETTER_AUTH_SECRET` environment variable in your
+`.env.local`:
 
 ```bash
 npx -y @better-auth/cli secret
 ```
 
-2. Visit the [Better Auth documentation](https://www.better-auth.com) to unlock the full potential of authentication in your app.
-
-### Adding a Database (Optional)
-
-Better Auth can work in stateless mode, but to persist user data, add a database:
-
-```typescript
-// src/lib/auth.ts
-import { betterAuth } from "better-auth";
-import { Pool } from "pg";
-
-export const auth = betterAuth({
-  database: new Pool({
-    connectionString: process.env.DATABASE_URL,
-  }),
-  // ... rest of config
-});
-```
-
-Then run migrations:
-
-```bash
-npx -y @better-auth/cli migrate
-```
+See the [Better Auth documentation](https://www.better-auth.com) for more on
+configuring authentication.
 
 
 

docker-compose.yml

@@ -0,0 +1,14 @@
+services:
+  postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: ghost_kitchen
+    ports:
+      - '5433:5432'
+    volumes:
+      - postgres-data:/var/lib/postgresql/data
+
+volumes:
+  postgres-data:

package.json

@@ -15,6 +15,7 @@
     "db:push": "drizzle-kit push",
     "db:pull": "drizzle-kit pull",
     "db:studio": "drizzle-kit studio",
+    "db:seed": "tsx src/db/seed.ts",
     "lint": "eslint",
     "format": "prettier --write . && eslint --fix",
     "check": "prettier --check .",

src/db/seed.ts

@@ -88,6 +88,9 @@ export const seedGhostKitchen = async (db: NodePgDatabase<typeof schema>) => {
 }
 
 if (import.meta.url === `file://${process.argv[1]}`) {
+  const { config } = await import('dotenv')
+  config({ path: ['.env.local', '.env'] })
+
   const { drizzle } = await import('drizzle-orm/node-postgres')
   const db = drizzle(process.env.DATABASE_URL!, { schema })
   await seedGhostKitchen(db)