Update CLAUDE.md with project status and conventions

This commit is contained in:
Manohar Gupta 2026-05-10 11:44:20 +05:30
parent 5986fba70f
commit 83b8292ca0

158
CLAUDE.md
View file

@ -1,83 +1,93 @@
# CLAUDE.md # CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. Tia - Baby Tracking App. Next.js 16, PostgreSQL, offline-first.
## Project Overview ## Build Rule
**Tia** is a baby tracking app built with Next.js 15/16, designed for a Mama to track her baby's feeds, sleep, diapers, vaccinations, growth, and memories. The app features offline-first logging, AI-powered Q&A, and a Telegram alert system. **ALWAYS run `npm run build` before pushing.** Fix errors locally first.
## Build Verification Rule ## Project Status
**ALWAYS verify the build passes locally BEFORE asking user to deploy.** Run `pnpm build` (or `npm run build`) and confirm it succeeds with no errors. Do not ask the user to trigger a deployment until you've confirmed the build works. - ✅ Fast-log (feed/sleep/diaper + offline queue)
- ✅ PWA manifest + service worker
## Common Commands - ✅ Vaccinations (IAP schedule)
- ✅ Growth tracking
```bash - ✅ Memories gallery (placeholder)
# Development - ✅ AI chat (LiteLLM)
pnpm dev # Start local dev server - ✅ Dark mode toggle
pnpm build # Production build - ✅ Menu navigation
npm ci # Clean install for Docker - ⏳ Cloudflare R2 upload (needs credentials)
- ⏳ Telegram alerts
# Database (Drizzle)
npx drizzle-kit generate # Generate migration from schema
npx drizzle-kit push # Push schema to DB
```
## Environment Variables
Required in `.env.local`:
```env
DATABASE_URL=postgresql://tia:tia_local_dev@localhost:5433/tia_dev
AUTH_SECRET=
AUTH_URL=http://localhost:3000
RESEND_API_KEY=
```
## Hits & Learned Lessons
### Build Issues Fixed
1. **pnpm 11 + Node 20 incompatibility**: pnpm 11 requires Node 22+. Fixed by using Node 22 in Dockerfile.
2. **pnpm ignored builds in Docker**: Had to switch from pnpm to npm in Dockerfile (`npm ci` instead of `pnpm install`).
3. **Drizzle adapter type errors**: Using simplified DrizzleAdapter without passing table configs directly fixes type errors.
4. **nodemailer missing**: NextAuth email provider requires nodemailer as a dependency.
5. **Middleware warning**: Next.js 16 shows deprecation warning for middleware file convention.
### Database Setup
- Local: Docker Compose with pgvector on port 5433, Redis on 6380
- Schema: 8 tables (users, accounts, sessions, verification_tokens, families, family_members, children, family_invites)
- Migrations: Run via `npx drizzle-kit push` or docker exec with SQL files
### Docker Build
- Use `npm ci` instead of pnpm in Docker for reliability
- Node 22 alpine image
- Multi-stage build (deps → builder → runner)
- Need to install nodemailer separately for email auth
## Architecture
- **Framework**: Next.js 16 (App Router) with TypeScript
- **Database**: PostgreSQL 16 with pgvector (Drizzle ORM)
- **Auth**: NextAuth v5 beta
- **Deployment**: Dokploy (Docker)
## Sprint Plan
Current: Sprint 1 (Database + Auth)
- Sprint 0: Dev environment, Docker, Dokploy deploy ✅
- Sprint 1: Auth + Database with RLS (in progress)
- Sprint 2: Fast-log engine
- Sprint 3: Medical vault
- Sprint 4: Media pipeline
- Sprint 5: AI Brain
- Sprint 6: UI/UX polish
- Sprint 7: Telegram alerts + launch
## Key Files ## Key Files
- `src/auth.ts` - NextAuth configuration | Path | Purpose |
- `src/db/schema/auth.ts` - Auth tables (users, sessions, accounts) |------|---------|
- `src/db/schema/family.ts` - Family, members, children tables | `src/app/page.tsx` | Home with quick log, dark mode toggle |
- `src/app/login/page.tsx` - Login page | `src/app/menu/page.tsx` | Navigation drawer |
- `Dockerfile` - Production build (uses npm, not pnpm) | `src/app/medical/page.tsx` | IAP vaccination schedule |
| `src/app/ai/page.tsx` | LiteLLM chat |
| `src/app/api/logs/route.ts` | Feed/sleep/diaper logging |
| `src/app/api/ai/route.ts` | LLM API proxy |
| `src/db/schema/logs.ts` | Log schemas |
| `public/sw.js` | Service worker for offline |
## Routes
- `/` - Home
- `/menu` - Navigation
- `/settings` - Settings + dark mode
- `/medical` - Vaccinations
- `/growth` - Growth records
- `/memories` - Photo gallery
- `/ai` - AI chat
- `/api/logs` - Log entries (type=feed|sleep|diaper)
- `/api/ai` - AI chat
## Conventions
### API Pattern
```typescript
// GET with query params, POST with JSON body
export async function GET(request: Request) {
const { searchParams } = new URL(request.url);
const id = searchParams.get("id");
// use sql.unsafe() for raw queries
}
export async function POST(request: Request) {
const body = await request.json();
// use sql.unsafe() with parameterized values
}
```
### UI Pattern
```typescript
"use client";
import { useState, useEffect } from "react";
// dark mode: document.documentElement.classList.toggle("dark")
// links: use <Link href="..."> not router.push()
```
### Database
- Use `sql.unsafe()` not `db.execute()` - postgres-js method
- Dates: `new Date().toISOString()` string format
- Enums: create manually, no IF NOT EXISTS support
## Local Dev
```bash
cd tia
npm run dev
```
## Deployment
Auto-deploys via webhook on Git push. Database tables created via `/api/setup`.
## Environment
```
DATABASE_URL=postgresql://user:pass@host:5432/db
OPENAI_API_BASE_URL=http://litellm-gateway:4000/v1
LITELLM_MASTER_KEY=sk-tiger-gateway-...
```