maternal-app/README.md

# Maternal App - AI-Powered Parenting Assistant

An AI-powered mobile application designed to help parents manage childcare for children aged 0-6 years. Features intelligent tracking, real-time family sync, and AI-powered parenting support using LLMs.

## 🚀 Project Status

**Phase 0: Development Environment Setup** ✅ **COMPLETED**

- ✅ React Native mobile app initialized with Expo
- ✅ NestJS backend API initialized
- ✅ Docker Compose infrastructure configured
- ✅ ESLint & Prettier configured
- ✅ Environment variables set up
- ✅ All services running

**Next Phase:** Phase 1 - Foundation & Authentication (Week 1-2)

## 🏗️ Architecture

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

### Backend API
- **Framework:** NestJS (Node.js + TypeScript)
- **API Style:** Hybrid REST + GraphQL + WebSocket
- **Authentication:** JWT with refresh tokens

### Infrastructure
- **Database:** PostgreSQL 15 (port 5555)
- **Cache/Queue:** Redis 7 (port 6666)
- **Document Store:** MongoDB 6 (port 27777)
- **Object Storage:** MinIO (ports 9002/9003)

## 📋 Prerequisites

- **Node.js:** v18+ LTS
- **npm:** v8+
- **Docker:** Latest
- **Docker Compose:** Latest
- **Expo CLI:** Installed globally (optional)

## 🛠️ Installation & Setup

### 1. Clone and Install

```bash
# Clone the repository
cd maternal-app

# Install mobile app dependencies
cd maternal-app
npm install
cd ..

# Install backend dependencies
cd maternal-app-backend
npm install
cd ..
```

### 2. Start Infrastructure Services

```bash
# Start all Docker services (PostgreSQL, Redis, MongoDB, MinIO)
docker compose up -d

# Verify services are running
docker compose ps

# View logs if needed
docker compose logs -f
```

**Service Ports (modified to avoid conflicts):**
- PostgreSQL: `localhost:5555`
- Redis: `localhost:6666`
- MongoDB: `localhost:27777`
- MinIO API: `localhost:9002`
- MinIO Console: `localhost:9003`

### 3. Configure Environment Variables

Backend environment file is already created at `maternal-app-backend/.env`. Update API keys as needed:

```bash
# Edit backend .env file
cd maternal-app-backend
nano .env  # or use your preferred editor
```

**Important:** Add your AI service API keys:
- `OPENAI_API_KEY` - For GPT-4 integration
- `ANTHROPIC_API_KEY` - For Claude integration (optional)
- `GOOGLE_AI_API_KEY` - For Gemini integration (optional)

## 🚀 Running the Application

### Start Backend API

```bash
cd maternal-app-backend

# Development mode with hot-reload
npm run start:dev

# Production mode
npm run start:prod

# Watch mode
npm run start:watch
```

Backend will be available at: `http://localhost:3000`

### Start Mobile App

```bash
cd maternal-app

# Start Expo development server
npm start

# Or run directly on iOS simulator
npm run ios

# Or run directly on Android emulator
npm run android

# Or run in web browser
npm run web
```

## 🧪 Testing

### Backend Tests

```bash
cd maternal-app-backend

# Run unit tests
npm test

# Run tests with coverage
npm run test:cov

# Run E2E tests
npm run test:e2e

# Run tests in watch mode
npm run test:watch
```

### Mobile App Tests

```bash
cd maternal-app

# Run tests
npm test
```

## 📁 Project Structure

```
maternal-app/
├── docs/                          # Comprehensive documentation
│   ├── maternal-app-tech-stack.md
│   ├── maternal-app-implementation-plan.md
│   ├── maternal-app-api-spec.md
│   ├── maternal-app-ai-context.md
│   └── ... (12 more detailed docs)
├── maternal-app/                  # React Native mobile app
│   ├── src/
│   │   ├── components/
│   │   ├── screens/
│   │   ├── services/
│   │   ├── redux/
│   │   ├── navigation/
│   │   └── types/
│   ├── package.json
│   └── .eslintrc.js
├── maternal-app-backend/          # NestJS backend API
│   ├── src/
│   │   ├── modules/
│   │   │   ├── auth/
│   │   │   ├── users/
│   │   │   ├── families/
│   │   │   └── ...
│   │   ├── common/
│   │   └── database/
│   ├── package.json
│   └── .env
├── docker-compose.yml             # Infrastructure services
├── .env.example                   # Environment template
├── CLAUDE.md                      # AI assistant guidance
└── README.md                      # This file
```

## 🗄️ Database Management

### Connect to PostgreSQL

```bash
# Using docker exec
docker exec -it maternal-postgres psql -U maternal_user -d maternal_app

# Or use your preferred PostgreSQL client
Host: localhost
Port: 5555
Database: maternal_app
User: maternal_user
Password: maternal_dev_password_2024
```

### Connect to MongoDB

```bash
# Using mongosh
mongosh "mongodb://maternal_admin:maternal_mongo_password_2024@localhost:27777/maternal_ai_chat?authSource=admin"
```

### Connect to Redis

```bash
# Using redis-cli
redis-cli -p 6666
```

### Access MinIO Console

Open browser: `http://localhost:9003`

Login credentials:
- Username: `maternal_minio_admin`
- Password: `maternal_minio_password_2024`

## 📚 Development Workflow

### Branch Naming
- `feature/` - New features
- `bugfix/` - Bug fixes
- `hotfix/` - Critical fixes
- `docs/` - Documentation updates

### Commit Messages (Conventional Commits)
```bash
feat: add voice input for feeding tracker
fix: resolve timezone sync issue
docs: update API documentation
test: add unit tests for sleep predictor
```

### Code Quality

```bash
# Lint mobile app
cd maternal-app
npm run lint

# Lint backend
cd maternal-app-backend
npm run lint

# Format code
npm run format
```

## 🔐 Security Notes

- **Never commit `.env` files** - they are gitignored
- Change all default passwords in production
- Rotate JWT secrets regularly
- Keep API keys secure and never expose them in client code

## 📖 Documentation

Comprehensive documentation is available in the `/docs` directory:

1. **Technical Stack** - Complete technology choices and libraries
2. **Implementation Plan** - 8-phase development roadmap with AI role guidance
3. **API Specification** - REST/GraphQL/WebSocket endpoint specs
4. **AI Context Management** - LangChain configuration and prompt templates
5. **State Management** - Redux architecture with offline support
6. **UI/UX Design System** - Material Design with warm color palette
7. **Testing Strategy** - Unit, integration, and E2E testing approach
8. **Database Migrations** - Schema design and migration scripts
9. **Environment Configuration** - Docker and environment setup
10. **Error Handling** - Error codes and logging standards
11. **Mobile Deployment** - iOS/Android build and release process
12. **Voice Processing** - Voice input patterns and NLP

## 🎯 MVP Features (6-8 Weeks)

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

### Supported Languages
- English (en-US)
- Spanish (es-ES)
- French (fr-FR)
- Portuguese (pt-BR)
- Simplified Chinese (zh-CN)

## 🤝 Development Commands Cheat Sheet

```bash
# Infrastructure
docker compose up -d              # Start all services
docker compose down               # Stop all services
docker compose logs -f            # View logs

# Backend
cd maternal-app-backend
npm run start:dev                 # Start with hot-reload
npm run build                     # Build for production
npm test                          # Run tests
npm run lint                      # Lint code

# Mobile
cd maternal-app
npm start                         # Start Expo
npm run ios                       # Run on iOS
npm run android                   # Run on Android
npm test                          # Run tests
npm run lint                      # Lint code
```

## 🐛 Troubleshooting

### Ports Already in Use
If you see port conflict errors, the docker-compose.yml uses non-standard ports:
- PostgreSQL: 5555 (not 5432)
- Redis: 6666 (not 6379)
- MongoDB: 27777 (not 27017)

### Docker Services Not Starting
```bash
# Check service status
docker compose ps

# View specific service logs
docker compose logs <service-name>

# Restart a specific service
docker compose restart <service-name>
```

### Mobile App Won't Start
```bash
# Clear Expo cache
cd maternal-app
rm -rf .expo
npm start --clear
```

## 📞 Next Steps

1. **Phase 1**: Implement authentication system (Week 1-2)
   - JWT authentication with device fingerprinting
   - User registration and login
   - Password reset flow
   - Multi-language support setup

2. **Phase 2**: Child profiles & family management (Week 2-3)
3. **Phase 3**: Core tracking features (Week 3-4)
4. **Phase 4**: AI assistant integration (Week 4-5)
5. **Phase 5**: Pattern recognition & analytics (Week 5-6)
6. **Phase 6**: Testing & optimization (Week 6-7)
7. **Phase 7**: Beta testing & launch prep (Week 7-8)

## 📄 License

[Add your license here]

## 🙏 Acknowledgments

Built following comprehensive technical documentation and industry best practices for parenting apps.

---

**For detailed implementation guidance, see `/docs/maternal-app-implementation-plan.md`**