From 83b8292ca0dd2c97d03622e2a742bff2043d77bb Mon Sep 17 00:00:00 2001 From: Mannu Date: Sun, 10 May 2026 11:44:20 +0530 Subject: [PATCH] Update CLAUDE.md with project status and conventions --- CLAUDE.md | 158 +++++++++++++++++++++++++++++------------------------- 1 file changed, 84 insertions(+), 74 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index d280520..6424613 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,83 +1,93 @@ # 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. - -## Common Commands - -```bash -# Development -pnpm dev # Start local dev server -pnpm build # Production build -npm ci # Clean install for Docker - -# 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 +- ✅ Fast-log (feed/sleep/diaper + offline queue) +- ✅ PWA manifest + service worker +- ✅ Vaccinations (IAP schedule) +- ✅ Growth tracking +- ✅ Memories gallery (placeholder) +- ✅ AI chat (LiteLLM) +- ✅ Dark mode toggle +- ✅ Menu navigation +- ⏳ Cloudflare R2 upload (needs credentials) +- ⏳ Telegram alerts ## Key Files -- `src/auth.ts` - NextAuth configuration -- `src/db/schema/auth.ts` - Auth tables (users, sessions, accounts) -- `src/db/schema/family.ts` - Family, members, children tables -- `src/app/login/page.tsx` - Login page -- `Dockerfile` - Production build (uses npm, not pnpm) \ No newline at end of file +| Path | Purpose | +|------|---------| +| `src/app/page.tsx` | Home with quick log, dark mode toggle | +| `src/app/menu/page.tsx` | Navigation drawer | +| `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 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-... +``` \ No newline at end of file