qia-client/CLAUDE.md

CLAUDE.md

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

Project Overview

"掐日子" (Qia Rizi) - A Chinese calendar reminder app with anniversaries, reminders, and notes. Built with React 19 + TypeScript + Supabase.

Commands

# Install dependencies
pnpm install

# Start dev server
pnpm dev

# Build for production
pnpm build

# Run linting
pnpm lint

# Preview production build
pnpm preview

Architecture

Frontend (client/)

• React 19 + TypeScript + Vite - Core framework
• Mantine UI v8 - Component library with custom Apple-inspired theme
• Zustand - State management with localStorage persistence
• React Router v7 - Routing
• Supabase - Backend (auth, database)

Key Directories

• src/pages/ - Route pages (HomePage, LoginPage, RegisterPage, SettingsPage, ArchivePage)
• src/components/ - Reusable components, organized by feature
• src/stores/ - Zustand store (useAppStore for global state)
• src/services/ - API layer (supabase.ts, api.ts)
• src/types/ - TypeScript type definitions
• src/utils/ - Business logic utilities (repeatCalculator, countdown)

Data Model

• Events: Anniversary/Reminder items with repeat rules, lunar calendar support
• Notes: User's personal notes (HTML content)
• AI Conversations: Chat history with AI event parsing

Key Patterns

State Management

• Use useAppStore from src/stores/index.ts for global state (auth, events, notes)
• Store persists to localStorage via zustand/middleware

API Calls

• Direct Supabase calls via services/supabase.ts
• Auth token handling with automatic refresh in store's checkAuth

Components

• Custom date/time pickers in src/components/common/ (FixedCalendar, WheelTimePicker)
• Event cards use context menus from src/stores/contextMenu.ts

Chinese Localization

• App uses Simplified Chinese (zh-cn) throughout
• dayjs configured with Chinese locale
• Mantine DatesProvider set to Chinese