Phase 1 & 2: Authentication and Children Management
Completed Features:
- Full JWT authentication system with refresh tokens
- User registration and login with device fingerprinting
- Child profile CRUD operations with permission-based access
- Family management with roles and permissions
- Database migrations for core auth and family structure
- Comprehensive test coverage (37 unit + E2E tests)
Tech Stack:
- NestJS backend with TypeORM
- PostgreSQL database
- JWT authentication with Passport
- bcrypt password hashing
- Docker Compose for infrastructure
🤖 Generated with Claude Code
This commit is contained in:
andupetcu
343
CLAUDE.md
Normal file
343
CLAUDE.md
Normal file
@@ -0,0 +1,343 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user