# CLAUDE.md

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

## Project Overview

This is a planning and documentation repository for an **AI-powered maternal organization app** designed to help parents manage childcare for children aged 0-6 years. The app focuses on reducing mental load through intelligent tracking, real-time family sync, and AI-powered parenting support.

**Current Status**: Documentation phase - no code implementation yet. All source files are comprehensive planning documents.

## Core Technology Stack

### Mobile Application
- **Framework**: React Native with Expo
- **State Management**: Redux Toolkit with offline-first architecture
- **Local Database**: SQLite with TypeORM
- **Navigation**: React Navigation
- **UI Components**: React Native Paper (Material Design)

### Backend Infrastructure
- **Framework**: NestJS (Node.js)
- **API Style**: Hybrid REST + GraphQL + WebSocket
- **Primary Database**: PostgreSQL 15+ (with partitioned activity tables)
- **Document Store**: MongoDB (for AI chat history)
- **Cache/Queue**: Redis
- **Object Storage**: MinIO (S3-compatible)

### AI/ML Services
- **LLM**: OpenAI GPT-4 / Anthropic Claude / Google Gemini APIs
- **Framework**: LangChain for context management
- **Voice Recognition**: OpenAI Whisper
- **Pattern Recognition**: Custom algorithms with TensorFlow.js

### Real-Time Features
- **Sync**: Socket.io for family coordination
- **Push Notifications**: Firebase Cloud Messaging / Expo Notifications

## Architecture Highlights

### State Management Design
- **Normalized state shape** with entities stored in `byId` dictionaries
- **Offline-first** with automatic sync queue and conflict resolution
- **Optimistic updates** for instant UI feedback
- Separate slices: auth, user, family, children, activities, ai, sync, offline, ui, notifications, analytics

### API Architecture
- Base URL: `https://api.{domain}/api/v1`
- GraphQL endpoint for complex queries: `/graphql`
- WebSocket for real-time sync: `wss://api.{domain}/ws`
- **Device fingerprinting** for multi-device auth
- **JWT access tokens** (1h) + refresh tokens with rotation
- Rate limiting: 100 requests/minute per user

### Database Schema Strategy
- **Partitioned tables** for activities (feeding, sleep, diapers) using monthly partitions
- **Audit logging tables** for COPPA/GDPR compliance
- **Performance indexes** on commonly queried fields (childId, createdAt)
- Migration scripts numbered V001-V007+ for sequential deployment

### AI Context Management
- **Token budget**: 4000 tokens max per request
- **Priority weighting system** for context selection:
  - Current query: 1.0
  - Recent activities (48h): 0.8
  - Child profile: 0.7
  - Historical patterns: 0.6
  - General guidelines: 0.4
- **Safety boundaries**: Medical disclaimer triggers, mental health resources, prompt injection protection
- **Multi-language support**: 5 languages (English, Spanish, French, Portuguese, Chinese)

## Key Documentation Files

### Technical Architecture
- `docs/maternal-app-tech-stack.md` - Complete technology choices with library recommendations
- `docs/maternal-app-implementation-plan.md` - 8-phase development roadmap with deliverables
- `docs/maternal-app-api-spec.md` - REST/GraphQL/WebSocket endpoint specifications
- `docs/maternal-app-db-migrations.md` - Database schema with migration scripts

### AI/ML Integration
- `docs/maternal-app-ai-context.md` - LangChain configuration, prompt templates, safety boundaries
- `docs/maternal-app-voice-processing.md` - Voice input patterns and NLP processing
- `docs/maternal-app-state-management.md` - Redux Toolkit architecture with offline support

### UI/UX Design
- `docs/maternal-app-design-system.md` - Material Design system with warm color palette
- `docs/maternal-app-mvp.md` - MVP feature scope and success metrics
- `docs/maternal-app-testing-strategy.md` - Testing approach (unit, integration, E2E)

### DevOps & Deployment
- `docs/maternal-app-env-config.md` - Environment variables and Docker setup
- `docs/maternal-app-mobile-deployment.md` - iOS/Android build and release process
- `docs/maternal-app-error-logging.md` - Error codes and logging standards

## Implementation Commands (Future)

### Project Setup
```bash
# Frontend - React Native with Expo
npx create-expo-app maternal-app --template
cd maternal-app
npm install @reduxjs/toolkit react-redux redux-persist
npm install react-navigation react-native-paper
npm install @react-native-async-storage/async-storage
npm install react-native-sqlite-storage

# Backend - NestJS
nest new maternal-app-backend
cd maternal-app-backend
npm install @nestjs/typeorm @nestjs/jwt @nestjs/websockets
npm install @nestjs/graphql @apollo/server graphql
npm install pg redis bull socket.io
```

### Development Workflow
```bash
# Frontend development
npm start              # Start Expo dev server
npm run ios            # Run on iOS simulator
npm run android        # Run on Android emulator
npm test               # Run Jest unit tests

# Backend development
npm run start:dev      # Start NestJS with hot reload
npm run test           # Run unit tests
npm run test:e2e       # Run integration tests
npm run migration:run  # Apply database migrations

# Docker environment
docker-compose up -d   # Start PostgreSQL, Redis, MongoDB, MinIO
```

### Testing
```bash
# Unit tests (Jest)
npm test -- --coverage  # Run with coverage report

# E2E tests (Detox for mobile)
detox build --configuration ios.sim.debug
detox test --configuration ios.sim.debug

# Backend integration tests
npm run test:e2e
```

### Database Management
```bash
# Run migrations in sequence
npm run migration:run

# Rollback last migration
npm run migration:revert

# Generate new migration
npm run migration:generate -- -n MigrationName
```

## Design Principles

### Mobile UX Requirements
- **One-handed operation**: All critical actions in bottom 60% of screen
- **Interruption-resilient**: Auto-save all inputs, no data loss on app switch
- **Minimum touch targets**: 44x44px (iOS) / 48x48dp (Android)
- **Performance**: 60fps scrolling, <2s load time, skeleton screens for loading states

### Color Palette (Warm, Nurturing)
- Primary: Peach (#FFB5A0), Coral (#FF8B7D), Rose (#FFD4CC)
- Semantic: Sage green (success), Amber (warning), Soft red (error)
- Material Design principles throughout

### Accessibility
- WCAG AA/AAA compliance
- Screen reader support
- High contrast mode
- Text size adjustment
- Multi-language support (5 languages in MVP)

## Security & Compliance

### Authentication Flow
1. Email/phone signup with verification
2. Device fingerprinting on registration
3. JWT access token (1h) + refresh token
4. Biometric login option (Face ID / Touch ID / Fingerprint)
5. Multi-device session management

### Privacy Considerations
- **COPPA compliance**: Age verification, parental consent flows
- **GDPR compliance**: Data export, right to deletion, consent management
- **End-to-end encryption** for sensitive child data
- **Audit tables** tracking all data access and modifications
- **No third-party data sharing** without explicit consent

### Error Handling Standards
- Structured error codes (e.g., `AUTH_DEVICE_NOT_TRUSTED`, `LIMIT_FAMILY_SIZE_EXCEEDED`)
- User-friendly error messages in all 5 languages
- Sentry integration for error tracking
- Audit logging for security events

## MVP Scope (6-8 Weeks)

### Core Features
1. **Tracking**: Feeding, sleep, diapers with voice input
2. **AI Assistant**: 24/7 contextual parenting support using LangChain
3. **Family Sync**: Real-time updates via WebSocket
4. **Pattern Recognition**: Sleep predictions, feeding trends
5. **Analytics**: Daily/weekly summaries, exportable reports

### Success Metrics
- 1,000 downloads in first month
- 60% daily active users
- 70% of users try AI assistant
- <2% crash rate
- 4.0+ app store rating

### Deferred to Post-MVP
- Meal planning
- Financial tracking
- Community forums
- Smart home integration
- School platform integrations

## Code Organization (Planned)

```
/maternal-app (React Native)
  /src
    /components
      /common        # Reusable UI components
      /tracking      # Activity tracking components
      /ai            # AI chat interface
    /screens         # Screen components
    /services        # API clients, device services
    /hooks           # Custom React hooks
    /redux
      /slices        # Redux Toolkit slices
    /locales         # i18n translations
    /navigation      # React Navigation config
    /types           # TypeScript definitions

/maternal-app-backend (NestJS)
  /src
    /modules
      /auth          # Authentication & authorization
      /users         # User management
      /families      # Family coordination
      /children      # Child profiles
      /tracking      # Activity tracking
      /ai            # AI/LLM integration
    /common
      /guards        # Auth guards
      /interceptors  # Request/response transformation
      /filters       # Exception filters
    /database
      /entities      # TypeORM entities
      /migrations    # Database migrations
```

## Development Best Practices

### Git Workflow
- Branch naming: `feature/`, `bugfix/`, `hotfix/`
- Commit messages: Conventional commits (feat:, fix:, docs:, test:)
- Pre-commit hooks: ESLint, Prettier, type checking

### Testing Strategy
- **Target**: 80% code coverage
- Unit tests for all services and utilities
- Integration tests for API endpoints
- E2E tests for critical user journeys
- Mock AI responses for predictable testing

### Performance Optimization
- Redis caching for frequent queries
- Database query optimization with indexes
- Image optimization with Sharp
- Code splitting and lazy loading
- Offline-first architecture with sync queue

## Multi-Language Support

### Supported Languages (MVP)
1. English (en-US) - Primary
2. Spanish (es-ES)
3. French (fr-FR)
4. Portuguese (pt-BR)
5. Simplified Chinese (zh-CN)

### Localization Framework
- i18next for string externalization
- react-i18next for React integration
- react-native-localize for device locale detection
- All strings externalized from day 1
- Date/time/number formatting per locale
- AI responses localized per user preference

## Critical Implementation Notes

### Offline-First Architecture
- All core features (tracking) work offline
- Automatic sync queue when connectivity restored
- Conflict resolution strategy: last-write-wins with timestamp comparison
- Optimistic UI updates for instant feedback

### Real-Time Family Sync
- WebSocket connection per device
- Event-driven architecture for activity updates
- Presence indicators (who's online)
- Typing indicators for AI chat
- Connection recovery with exponential backoff

### AI Safety Guardrails
- Medical disclaimer triggers for health concerns
- Crisis hotline integration for mental health
- Rate limiting: 10 AI queries/day (free), unlimited (premium)
- Response moderation and filtering
- Prompt injection protection

### Data Migration Strategy
- Sequential migration scripts (V001, V002, etc.)
- Rollback procedures for each migration
- Data seeding for development/testing
- Backup verification before production migrations

## Future Roadmap Considerations

### Phase 2 (Months 2-3)
- Community features with moderation
- Photo milestone tracking
- Meal planning basics
- Calendar integration (Google, Apple, Outlook)

### Phase 3 (Months 4-6)
- Financial tracking
- Smart home integration (Alexa, Google Home)
- Professional tools for caregivers
- Telemedicine integration

### Scalability Preparations
- Kubernetes deployment for horizontal scaling
- Database sharding strategy for multi-tenancy
- CDN for static assets
- Message queue (RabbitMQ/Kafka) for async processing
- Microservices architecture when needed