tia/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Commands

```bash
# Development
pnpm dev          # Start dev server at http://localhost:3000
pnpm build         # Production build
pnpm start         # Start production server

# Database (drizzle)
pnpm db:push      # Push schema to database
pnpm db:generate  # Generate drizzle types
pnpm db:studio   # Open DB studio (or use direct SQL)

# Docker
docker-compose -f docker-compose.dev.yml up -d    # Start local Postgres
```

**Note:** Running from `/Users/manohar_air/MyProjects/Tia/tia` directory.

## Architecture

### Tech Stack

- **Framework:** Next.js 16 with App Router (src/app/)
- **Database:** PostgreSQL 16 with pgvector + Drizzle ORM
- **Auth:** Database sessions with httpOnly cookies
- **AI:** LiteLLM gateway → MiniMax model (minimax-2.7)
- **Storage:** Cloudflare R2 for media uploads
- **Styling:** Tailwind CSS v4

### Project Structure

```
src/
├── app/                    # Next.js App Router pages
│   ├── api/               # API routes (auth, logs, ai, growth, etc.)
│   ├── page.tsx            # Home (Quick Log + AI card)
│   ├── ai/               # AI chat page with sidebar
│   ├── medical/           # Vaccination tracking
│   ├── growth/           # Growth charts
│   ├── memories/         # Photo gallery
│   ├── menu/             # Navigation menu
│   ├── onboarding/      # First-time setup
│   ├── settings/          # Settings with theme picker
│   ├── login/            # User login (magic)
│   ├── admin/            # Admin panel
│   └── admin-login/       # Admin login (separate)
├── ThemeProvider.tsx       # Theme context (light/dark/system/time)
├── FamilyProvider.tsx      # Family/child context (resolves from session)
drizzle/                  # Database migrations
docs/                     # Design docs
```

### Database

- **Migrations:** SQL files in `drizzle/` (not using drizzle-kit push)
- **Apply:** `psql` directly or via docker-compose exec
- **RLS:** Row-level security for multi-family isolation

### Data Models

- **Family:** Parent account container
- **Members:** Adults in family (mom, dad, etc.) via `family_members`
- **Children:** Baby profiles with birth date
- **Sessions:** Login sessions with httpOnly cookies
- **Logs:** Feed, sleep, diaper entries with timestamps
- **Vaccinations:** IAP schedule tracking
- **Growth:** Weight/height over time
- **Memories:** Photos with R2 storage

### Key Patterns

**ThemeProvider:** Wrap app in ThemeProvider from layout.tsx. Use `useTheme()` hook in components.

```typescript
import { useTheme } from "./ThemeProvider";
const { theme, toggle, setMode } = useTheme();
// theme: "light" | "dark"
// mode: "light" | "dark" | "system" | "time"
```

**FamilyProvider:** Resolves family from database session on login.

```typescript
import { useFamily } from "./FamilyProvider";
const { familyId, child, children, tier } = useFamily();
// familyId: string | null (from session)
// child: Child | null
// tier: "free" | "pro"
```

**Offline Queue:** Uses localStorage (`tia_offline_queue`) for failed API calls, retries when online.

**Chat Sessions:** Stored in localStorage (`tia_chat_sessions`) - shared between home page AI card and /ai page.

**API Routes:** Return standard JSON `{ success: true, items: [...] }` format for lists.

**AI Integration:**

- Route: `/api/ai` → LiteLLM at `https://llm.manohargupta.com`
- Model: `minimax-2.7`
- See `/docs/debugging.md` for troubleshooting

## Authentication (Database Sessions)

### Session Flow

1. User logs in at `/login` with email
2. API `/api/auth/signin` creates session in `sessions` table
3. Session token stored in **httpOnly cookie** (NOT localStorage!)
4. On each request, session resolved from database via cookie

### Tables Used

- **users:** User accounts (email, name)
- **families:** Family accounts (name, tier, limits)
- **family_members:** Links users to families (user_id, family_id, role)
- **children:** Child profiles (name, birth_date, family_id)
- **sessions:** Login sessions (session_token, user_id, expires)

### NEVER use localStorage for:
- authentication tokens
- family_id after login
- Any data that should persist across devices

### localStorage Acceptable For:
- Theme preference (user-specific display only)
- Temporary cache (offline queue for retry)
- Chat sessions (upcoming feature: move to database)

## Admin Panel

Access at: `/admin-login` (username: `admin`, password: `admin123`)

### Pages

- `/admin` - Dashboard with stats
- `/admin/families` - Manage families
- `/admin/users` - Manage users
- `/admin/children` - Manage children
- `/admin/revenue` - Revenue analytics
- `/admin/analytics` - Feature usage
- `/admin/support` - Support tickets
- `/admin/settings` - Platform settings

## Data Storage Consistency

### RULE: All user data must persist to database, NOT localStorage

| Data Type | Storage | API Key | Persists After Refresh | Persists After Logout |
|----------|---------|--------|------------------------|-------------------|
| Children | Database | `/api/children` | ✅ Yes | ✅ Yes |
| Activity Logs | Database | `/api/logs` | ✅ Yes | ✅ Yes |
| Vaccinations | Database | `/api/vaccinations` | ✅ Yes | ✅ Yes |
| Growth Records | Database | `/api/growth` | ✅ Yes | ✅ Yes |
| User Profile | Database | `/api/auth/profile` | ✅ Yes | ✅ Yes |
| Memories/Photos | Database + R2 | `/api/upload` | ✅ Yes | ✅ Yes |
| Auth Session | Database + Cookie | `/api/auth/signin` | ✅ Yes | ✅ No |
| Theme | localStorage | `tia_theme` | ✅ Yes | ✅ Yes |
| Chat Sessions | localStorage | `tia_chat_sessions` | ✅ Yes | ❌ No |
| Offline Queue | localStorage | `tia_offline_queue` | ✅ Yes | ❌ No |

## R2 Storage (Cloudflare)

### Setup

1. **Create bucket** in Cloudflare Dashboard → R2
2. **Create API token** with "Object Read & Write" permissions
3. **Enable Public Development URL** in bucket settings (gives pub-*.r2.dev URL)

### API Endpoint Format

The S3 API endpoint is: `https://<accountId>.r2.cloudflarestorage.com`

For your bucket named "tia":
- Account ID: `e71f22a2f8614fb3ba6d9b28a264d8ce`
- S3 Endpoint: `https://e71f22a2f8614fb3ba6d9b28a264d8ce.r2.cloudflarestorage.com`
- Public URL: `https://pub-37a76fd657c94d1dbc521a109c087a11.r2.dev` (no bucket name in path!)

### Code Example

```typescript
const client = new S3Client({
  region: "auto",
  endpoint: `https://${accountId}.r2.cloudflarestorage.com`,
  credentials: { accessKeyId, secretAccessKey },
});

// List objects
const command = new ListObjectsV2Command({ Bucket: "tia" });
const res = await client.send(command);

// Get presigned upload URL
const command = new PutObjectCommand({ Bucket: "tia", Key: key, ContentType });
const url = await getSignedUrl(client, command, { expiresIn: 3600 });
```

### Key Learnings

1. **S3 API endpoint** does NOT include bucket name: `https://...r2.cloudflarestorage.com`
2. **Public URL** does NOT include bucket path: `https://pub-...r2.dev` (NOT `/tia/...`)
3. **CORS** needs GET and PUT methods for uploads
4. ListObjects needs bucket name in command, not endpoint

## Environment Variables

Set in `.env.local` for development, or in Dokploy dashboard for production.

Required:

- `DATABASE_URL` - PostgreSQL connection
- `AUTH_SECRET` - NextAuth secret
- `R2_ACCOUNT_ID` - Cloudflare R2 account ID
- `R2_ACCESS_KEY_ID` - R2 access key
- `R2_SECRET_ACCESS_KEY` - R2 secret key
- `R2_BUCKET_NAME` - R2 bucket name (e.g., "tia")
- `R2_PUBLIC_URL` - Public R2 URL (e.g., `https://pub-...r2.dev`)

Optional for AI:

- `LITELLM_BASE_URL` - AI gateway URL
- `LITELLM_API_KEY` - AI API key