# CLAUDE.md

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

## Project Overview

Notify is a reminder/todo management application with multi-user reminders, recurring schedules, and push notifications via Bark. It has a Rust backend (primary) and Next.js frontend.

## Development Commands

```bash
# Start development (Rust backend + frontend)
make dev

# Start development (Node.js backend - legacy)
make dev-node

# Stop all services
make stop

# Database migrations (Rust/SeaORM)
make migrate              # Run pending migrations
make migrate-down         # Rollback last migration
make migrate-fresh        # Reset database and re-run all migrations
make generate-entities    # Generate Rust entities from database

# Build release
make build
```

## Architecture

**Stack:**
- Frontend: Next.js 14, React 18, Tailwind CSS 4, Radix UI (shadcn/ui)
- Backend: Actix-web 4, SeaORM 2.0.0-rc (Rust) - primary
- Database: PostgreSQL 16

**Key directories:**
- `backend_rust/src/api/` - REST API endpoints
- `backend_rust/src/timer/` - Background job scheduler (notifications, Bark delivery)
- `backend_rust/src/entity/` - Auto-generated SeaORM models (DO NOT EDIT manually)
- `backend_rust/migration/src/` - Database migrations
- `frontend/src/app/` - Next.js pages (App Router)
- `frontend/src/lib/api.ts` - Centralized API client

**API endpoints (port 4000):**
- `/api/auth` - Login, register
- `/api/todos` - Personal todo CRUD with recurrence
- `/api/reminder-tasks` - Multi-user reminder CRUD
- `/api/notifications` - Notification center
- `/api/me` - User profile/settings
- `/api/invites` - Invite code management

## Database Migration Workflow

Follow `.cursor/skills/database-migration/SKILL.md`:
1. Create migration file: `m{YYYYMMDD}_{sequence}_{description}.rs` in `backend_rust/migration/src/`
2. Register in `migration/src/lib.rs`
3. Run `make migrate`
4. Run `make generate-entities`
5. Never manually edit `backend_rust/src/entity/` files

## Key Patterns

- **Notification generation**: Worker creates notification records for tasks due within N hours
- **Bark delivery**: Retry with exponential backoff (1m/5m/15m/1h/4h) on failure
- **Timezone handling**: All recurrence uses user's timezone; date alignment handles edge cases
- **Multi-recipient**: Each reminder task creates separate notification per recipient

## Documentation

- `docs/spec.md` - Product/technical spec (Chinese) with business rules, API definitions, UI requirements