maternal-app/docs/maternal-app-env-config.md

# Environment Configuration Guide - Maternal Organization App

## Environment Structure

### Environment Types
- **Development** (`dev`): Local development with hot reload
- **Staging** (`staging`): Pre-production testing environment
- **Production** (`prod`): Live application environment
- **Testing** (`test`): Automated testing environment

---

## Backend Environment Variables (.env)

### Core Configuration
```bash
# Application
NODE_ENV=development
APP_NAME=MaternalApp
APP_VERSION=1.0.0
API_VERSION=v1
PORT=3000
HOST=localhost

# URLs
BACKEND_URL=http://localhost:3000
FRONTEND_URL=http://localhost:8081
WEBSOCKET_URL=ws://localhost:3000
```

### Database Configuration
```bash
# PostgreSQL Primary
DATABASE_URL=postgresql://user:password@localhost:5432/maternal_app
DB_HOST=localhost
DB_PORT=5432
DB_NAME=maternal_app
DB_USER=maternal_user
DB_PASSWORD=secure_password_here
DB_SSL=false
DB_POOL_MIN=2
DB_POOL_MAX=10

# MongoDB (AI Chat History)
MONGODB_URI=mongodb://localhost:27017/maternal_ai
MONGODB_DB=maternal_ai

# Redis
REDIS_URL=redis://localhost:6379
REDIS_PASSWORD=
REDIS_DB=0
REDIS_CACHE_TTL=3600
```

### Authentication & Security
```bash
# JWT Configuration
JWT_SECRET=your-256-bit-secret-key-here
JWT_REFRESH_SECRET=different-256-bit-secret-key-here
JWT_EXPIRES_IN=1h
JWT_REFRESH_EXPIRES_IN=30d

# Encryption
ENCRYPTION_KEY=32-character-encryption-key-here
ENCRYPTION_IV=16-character-iv-here

# Device Fingerprinting
FINGERPRINT_SECRET=device-fingerprint-secret-key

# Rate Limiting
RATE_LIMIT_WINDOW_MS=60000
RATE_LIMIT_MAX_REQUESTS=100
```

### AI Services
```bash
# OpenAI
OPENAI_API_KEY=sk-your-openai-api-key
OPENAI_MODEL=gpt-4
OPENAI_TEMPERATURE=0.7
OPENAI_MAX_TOKENS=1000

# Anthropic Claude (Alternative)
ANTHROPIC_API_KEY=sk-ant-your-anthropic-key
ANTHROPIC_MODEL=claude-3-opus-20240229

# Whisper (Voice Recognition)
WHISPER_API_KEY=your-whisper-api-key
WHISPER_MODEL=whisper-1

# LangChain
LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=your-langchain-api-key
LANGCHAIN_PROJECT=maternal-app
```

### External Services
```bash
# Email Service (SendGrid)
SENDGRID_API_KEY=SG.your-sendgrid-api-key
SENDGRID_FROM_EMAIL=support@maternalapp.com
SENDGRID_FROM_NAME=Maternal App

# Push Notifications
FCM_SERVER_KEY=your-firebase-server-key
FCM_PROJECT_ID=maternal-app-prod
APNS_KEY_ID=your-apple-key-id
APNS_TEAM_ID=your-apple-team-id

# File Storage (MinIO/S3)
S3_ENDPOINT=http://localhost:9000
S3_ACCESS_KEY=minioadmin
S3_SECRET_KEY=minioadmin
S3_BUCKET=maternal-uploads
S3_REGION=us-east-1
S3_USE_SSL=false

# Monitoring
SENTRY_DSN=https://your-sentry-dsn@sentry.io/project-id
SENTRY_ENVIRONMENT=development
SENTRY_TRACES_SAMPLE_RATE=0.1
```

### Compliance & Analytics
```bash
# COPPA/GDPR
COPPA_VERIFICATION_REQUIRED=true
GDPR_ENABLED=true
DATA_RETENTION_DAYS=365
AUDIT_LOG_ENABLED=true

# Analytics
MIXPANEL_TOKEN=your-mixpanel-token
GA_TRACKING_ID=G-XXXXXXXXXX
POSTHOG_API_KEY=your-posthog-key
POSTHOG_HOST=https://app.posthog.com
```

---

## Frontend Environment Variables (.env)

### React Native Configuration
```bash
# API Configuration
REACT_APP_API_BASE_URL=http://localhost:3000/api/v1
REACT_APP_GRAPHQL_URL=http://localhost:3000/graphql
REACT_APP_WS_URL=ws://localhost:3000/ws

# Feature Flags
REACT_APP_ENABLE_VOICE=true
REACT_APP_ENABLE_AI_CHAT=true
REACT_APP_ENABLE_DARK_MODE=true
REACT_APP_ENABLE_OFFLINE=true
REACT_APP_MAX_CHILDREN_FREE=2
REACT_APP_AI_QUERIES_FREE=10

# App Configuration
REACT_APP_NAME=Maternal
REACT_APP_VERSION=1.0.0
REACT_APP_BUILD_NUMBER=1
REACT_APP_BUNDLE_ID=com.maternalapp.app
```

### Platform-Specific (iOS)
```bash
# iOS Configuration
IOS_APP_ID=1234567890
IOS_TEAM_ID=XXXXXXXXXX
IOS_PROVISIONING_PROFILE=maternal-app-dev
APPLE_SIGN_IN_SERVICE_ID=com.maternalapp.signin
```

### Platform-Specific (Android)
```bash
# Android Configuration
ANDROID_PACKAGE_NAME=com.maternalapp.app
ANDROID_KEYSTORE_PATH=./android/app/maternal.keystore
ANDROID_KEY_ALIAS=maternal-key
ANDROID_KEYSTORE_PASSWORD=keystore-password
ANDROID_KEY_PASSWORD=key-password
```

---

## Docker Environment Configuration

### docker-compose.yml
```yaml
version: '3.8'

services:
  postgres:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: ${DB_NAME}
      POSTGRES_USER: ${DB_USER}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"

  redis:
    image: redis:7-alpine
    command: redis-server --requirepass ${REDIS_PASSWORD}
    ports:
      - "6379:6379"

  mongodb:
    image: mongo:6
    environment:
      MONGO_INITDB_DATABASE: maternal_ai
    volumes:
      - mongo_data:/data/db
    ports:
      - "27017:27017"

  minio:
    image: minio/minio
    command: server /data --console-address ":9001"
    environment:
      MINIO_ROOT_USER: ${S3_ACCESS_KEY}
      MINIO_ROOT_PASSWORD: ${S3_SECRET_KEY}
    volumes:
      - minio_data:/data
    ports:
      - "9000:9000"
      - "9001:9001"

volumes:
  postgres_data:
  mongo_data:
  minio_data:
```

---

## Secret Management

### Development Secrets (.env.local)
```bash
# Never commit this file
# Copy from .env.example and fill with real values
cp .env.example .env.local
```

### Production Secrets (AWS Secrets Manager)
```bash
# Store production secrets in AWS Secrets Manager
aws secretsmanager create-secret \
  --name maternal-app/production \
  --secret-string file://secrets.json

# Retrieve secrets in application
aws secretsmanager get-secret-value \
  --secret-id maternal-app/production
```

### Kubernetes Secrets
```yaml
apiVersion: v1
kind: Secret
metadata:
  name: maternal-app-secrets
type: Opaque
data:
  jwt-secret: <base64-encoded-secret>
  database-url: <base64-encoded-url>
  openai-api-key: <base64-encoded-key>
```

---

## Environment File Templates

### .env.example (Commit to repo)
```bash
# Copy this file to .env.local and fill in values
NODE_ENV=development
PORT=3000

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/maternal_app

# Add all variables with placeholder values...
JWT_SECRET=change-this-to-random-256-bit-key
OPENAI_API_KEY=sk-your-api-key-here
```

### .env.test (Testing)
```bash
NODE_ENV=test
DATABASE_URL=postgresql://test:test@localhost:5432/maternal_test
REDIS_URL=redis://localhost:6380
JWT_SECRET=test-jwt-secret-not-for-production
```

---

## Platform-Specific Configuration

### iOS Info.plist Additions
```xml
<key>API_BASE_URL</key>
<string>$(API_BASE_URL)</string>

<key>NSMicrophoneUsageDescription</key>
<string>Voice input for hands-free logging</string>

<key>NSCameraUsageDescription</key>
<string>Take photos of your child</string>
```

### Android gradle.properties
```properties
API_BASE_URL=http://10.0.2.2:3000/api/v1
ENABLE_VOICE_INPUT=true
ENABLE_PROGUARD=false
```

---

## Configuration Loading Order

### Backend (Node.js)
```javascript
// config/index.ts
import dotenv from 'dotenv';

// Load in order of precedence
dotenv.config({ path: '.env.local' });    // Local overrides
dotenv.config({ path: `.env.${NODE_ENV}` }); // Environment specific
dotenv.config();                          // Default values

export const config = {
  app: {
    name: process.env.APP_NAME || 'MaternalApp',
    version: process.env.APP_VERSION || '1.0.0',
    env: process.env.NODE_ENV || 'development',
  },
  // ... rest of config
};
```

### Frontend (React Native)
```javascript
// config/env.js
import Config from 'react-native-config';

export const ENV = {
  dev: {
    API_URL: 'http://localhost:3000/api/v1',
    WS_URL: 'ws://localhost:3000/ws',
  },
  staging: {
    API_URL: 'https://staging-api.maternalapp.com/api/v1',
    WS_URL: 'wss://staging-api.maternalapp.com/ws',
  },
  prod: {
    API_URL: 'https://api.maternalapp.com/api/v1',
    WS_URL: 'wss://api.maternalapp.com/ws',
  },
}[Config.ENV || 'dev'];
```

---

## Security Best Practices

### Secret Rotation Schedule
- **JWT Secrets**: Every 90 days
- **API Keys**: Every 180 days
- **Database Passwords**: Every 60 days
- **Encryption Keys**: Every year

### Environment Variable Validation
```typescript
// validateEnv.ts
import { cleanEnv, str, port, url, bool, num } from 'envalid';

export const env = cleanEnv(process.env, {
  NODE_ENV: str({ choices: ['development', 'test', 'staging', 'production'] }),
  PORT: port(),
  DATABASE_URL: url(),
  JWT_SECRET: str({ minLength: 32 }),
  OPENAI_API_KEY: str(),
  RATE_LIMIT_MAX_REQUESTS: num({ default: 100 }),
});
```

### Git Security
```bash
# .gitignore
.env
.env.*
!.env.example
secrets/
*.key
*.pem
*.p12
```

---

## Deployment Configuration

### Heroku
```json
// app.json
{
  "env": {
    "NODE_ENV": {
      "value": "production"
    },
    "DATABASE_URL": {
      "required": true
    },
    "JWT_SECRET": {
      "generator": "secret"
    }
  }
}
```

### Docker Build Args
```dockerfile
ARG NODE_ENV=production
ARG API_VERSION=v1

ENV NODE_ENV=${NODE_ENV}
ENV API_VERSION=${API_VERSION}
```

### CI/CD Variables (GitHub Actions)
```yaml
env:
  NODE_ENV: production
  DATABASE_URL: ${{ secrets.DATABASE_URL }}
  JWT_SECRET: ${{ secrets.JWT_SECRET }}
  OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
```

---

## Monitoring & Debugging

### Debug Configuration
```bash
# Development debugging
DEBUG=maternal:*
LOG_LEVEL=debug
PRETTY_LOGS=true

# Production
LOG_LEVEL=info
LOG_FORMAT=json
```

### Health Check Variables
```bash
HEALTH_CHECK_INTERVAL=30000
HEALTH_CHECK_TIMEOUT=3000
HEALTH_CHECK_PATH=/health
```

---

## Quick Start Commands

### Local Development Setup
```bash
# 1. Copy environment template
cp .env.example .env.local

# 2. Start Docker services
docker-compose up -d

# 3. Run migrations
npm run migrate:up

# 4. Seed development data
npm run seed:dev

# 5. Start development server
npm run dev
```

### Environment Verification
```bash
# Check all required variables are set
npm run env:validate

# Display current configuration (masked)
npm run env:debug
```

---

## Troubleshooting

### Common Issues
1. **Missing API Keys**: Ensure all AI service keys are valid
2. **Database Connection**: Check DATABASE_URL format and credentials
3. **Redis Connection**: Verify Redis is running and accessible
4. **CORS Issues**: Confirm FRONTEND_URL is correctly set
5. **WebSocket Failures**: Check WS_URL matches backend configuration