Update CLAUDE.md with project status and conventions
This commit is contained in:
parent
5986fba70f
commit
83b8292ca0
1 changed files with 84 additions and 74 deletions
158
CLAUDE.md
158
CLAUDE.md
|
|
@ -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-...
|
||||||
|
```
|
||||||
Loading…
Add table
Reference in a new issue