maternal-app/CLAUDE.md

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

# 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

# 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

# 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

# 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