andrei/maternal-app
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: Remove production Docker infrastructure and reorganize docs
Some checks failed
ParentFlow CI/CD Pipeline / Backend Tests (push) Has been cancelled
Details
ParentFlow CI/CD Pipeline / Frontend Tests (push) Has been cancelled
Details
ParentFlow CI/CD Pipeline / Security Scanning (push) Has been cancelled
Details
ParentFlow CI/CD Pipeline / Build Docker Images (map[context:maternal-app/maternal-app-backend dockerfile:Dockerfile.production name:backend]) (push) Has been cancelled
Details
ParentFlow CI/CD Pipeline / Build Docker Images (map[context:maternal-web dockerfile:Dockerfile.production name:frontend]) (push) Has been cancelled
Details
ParentFlow CI/CD Pipeline / Deploy to Development (push) Has been cancelled
Details
ParentFlow CI/CD Pipeline / Deploy to Production (push) Has been cancelled
Details
CI/CD Pipeline / Lint and Test (push) Has been cancelled
Details
CI/CD Pipeline / E2E Tests (push) Has been cancelled
Details
CI/CD Pipeline / Build Application (push) Has been cancelled
Details

Browse Source 
- Remove production Docker Compose files (docker-compose.production.yml, docker-compose.prod-simple.yml)
- Remove production Dockerfiles (backend and frontend)
- Move implementation docs to docs/implementation-docs/ directory
- Remove test scripts (test-embeddings.js, test-voice-*.js/sh)
- Update ecosystem.config.js with production environment variables (CORS, JWT secrets, database config)
- Add database connection pooling configuration
- Update CORS configuration for production domains (parentflowapp.com)
- Fix frontend dev server port configuration (3005)
- Add PWA web push implementation plan documentation
- Simplify health check endpoints (remove MongoDB/Redis specific checks)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Andrei
2025-10-06 21:03:11 +00:00
parent a6b3ad67fb
commit 8ae42ffc75
28 changed files with 547 additions and 1536 deletions
Download Patch File Download Diff File Expand all files Collapse all files

322
docs/implementation-docs/AI_SAFETY_IMPLEMENTATION_SUMMARY.md Normal file
View File

@@ -0,0 +1,322 @@
# AI Safety Implementation Summary
**Date:** October 2, 2025
**Status:** ✅ COMPLETE
**Test Coverage:** 31/31 tests passing (100%)
---
## Implementation Overview
Comprehensive AI Safety system implemented for the Maternal App to ensure safe, responsible, and helpful AI interactions for parents seeking childcare guidance.
## 1. Files Created
### Strategy & Documentation
- `AI_SAFETY_STRATEGY.md` (518 lines) - Comprehensive safety strategy with 12 sections
- `AI_SAFETY_IMPLEMENTATION_SUMMARY.md` (this file) - Implementation summary
### Backend Services
- `ai-safety.service.ts` (533 lines) - Core safety service with keyword detection
- `ai-rate-limit.service.ts` (350 lines) - Enhanced rate limiting with abuse prevention
- `ai-safety.service.spec.ts` (359 lines) - Comprehensive test suite (31 tests)
### Files Modified
- `ai.module.ts` - Added AISafetyService and AIRateLimitService to providers
- `ai.service.ts` - Integrated safety checks, rate limiting, and safety guardrails
---
## 2. Features Implemented
### 2.1 Keyword Detection (AISafetyService)
✅ **Emergency Keywords** (25 keywords)
- not breathing, choking, seizure, unconscious, severe bleeding, etc.
- **Action:** Immediate override - returns emergency response with 911, Poison Control
✅ **Crisis Keywords** (17 keywords)
- suicide, self-harm, postpartum depression, abuse, hopeless, etc.
- **Action:** Immediate override - returns crisis hotlines (988, 1-800-944-4773, 741741)
✅ **Medical Keywords** (27 keywords)
- fever, vomiting, rash, cough, ear infection, medication, etc.
- **Action:** Add medical disclaimer, allow AI response with disclaimer
✅ **Developmental Keywords** (11 keywords)
- delay, autism, ADHD, regression, not talking, not walking, etc.
- **Action:** Add developmental disclaimer with CDC resources
✅ **Stress Keywords** (13 keywords)
- overwhelmed, burnout, exhausted, crying, isolated, etc.
- **Action:** Add stress support resources (Postpartum Support, Parents Anonymous)
### 2.2 Output Safety Moderation
✅ **Unsafe Pattern Detection** (4 regex patterns)
- Dosage patterns: `/\d+\s*(mg|ml|oz|tbsp|tsp)\s*(of|every|per)/i`
- Specific instructions: `/give\s+(him|her|them|baby|child)\s+\d+/i`
- Diagnostic language: `/diagnose|diagnosis|you have|they have/i`
- Definitive statements: `/definitely|certainly\s+(is|has)/i`
**Action:** Prepend medical disclaimer if unsafe patterns detected
### 2.3 Safety Response Templates
✅ **Emergency Response**
- 911 instructions
- CPR guidance if not breathing
- Poison Control: 1-800-222-1222
✅ **Crisis Hotline Response**
- National Suicide Prevention Lifeline: 988
- Postpartum Support International: 1-800-944-4773
- Crisis Text Line: Text "HOME" to 741741
- Childhelp National Child Abuse Hotline: 1-800-422-4453
✅ **Medical Disclaimer**
- Clear warning about not being medical professional
- Red flags requiring immediate care
- When to call pediatrician
✅ **Developmental Disclaimer**
- "Every child develops at their own pace"
- CDC Milestone Tracker link
- Early Intervention Services recommendation
✅ **Stress Support**
- Validation of parental feelings
- Support hotlines
- Self-care reminders
### 2.4 System Prompt Safety Guardrails
✅ **Base Safety Prompt**
- Critical safety rules (never diagnose, never prescribe)
- Emergency protocol (always direct to 911)
- Crisis recognition guidance
- Evidence-based sources (AAP, CDC, WHO)
- Scope definition (ages 0-6, no medical diagnosis)
✅ **Dynamic Safety Overrides**
- Medical Safety Override (for medical queries)
- Crisis Response Override (for crisis queries)
- Injected dynamically based on trigger detection
### 2.5 Rate Limiting & Abuse Prevention (AIRateLimitService)
✅ **Daily Rate Limits**
- Free tier: 10 queries/day
- Premium tier: 200 queries/day (fair use)
✅ **Suspicious Pattern Detection**
- Same query >3 times in 1 hour → Flag as repeated_query
- Emergency keywords >5 times/day → Flag as emergency_spam
- Volume >100 queries/day → Flag as unusual_volume
- Crisis keywords >5 times/day → Logged as high-risk (compassionate handling)
✅ **Temporary Restrictions**
- Duration: 24 hours
- Limit: 1 query/hour
- Applied for: emergency_spam, unusual_volume patterns
- Includes reason and expiration tracking
✅ **Usage Tracking**
- Redis-backed rate limit counters
- Query hashing for deduplication
- Hourly and daily pattern analysis
- Admin methods to clear restrictions
---
## 3. Integration Points
### 3.1 AI Chat Flow
```
1. Check rate limit FIRST → Reject if exceeded
2. Sanitize input (prompt injection detection)
3. Comprehensive safety check → Emergency/crisis override if triggered
4. Build context with enhanced safety prompt
5. Generate AI response
6. Output safety check → Add disclaimer if unsafe patterns
7. Response moderation
8. Inject trigger-specific safety responses
9. Track query for suspicious patterns
10. Increment rate limit counter
```
### 3.2 Safety Metrics Logging
All safety triggers are logged with:
- userId
- trigger type (emergency, crisis, medical, etc.)
- keywords matched
- query (first 100 chars)
- timestamp
**TODO:** Store in database for analytics dashboard (marked in code)
---
## 4. Test Coverage
### 4.1 Unit Tests (31 tests - all passing)
✅ Emergency keyword detection (3 tests)
✅ Crisis keyword detection (3 tests)
✅ Medical keyword detection (3 tests)
✅ Developmental keyword detection (2 tests)
✅ Stress keyword detection (2 tests)
✅ Safe query validation (2 tests)
✅ Output safety pattern detection (3 tests)
✅ Emergency response template (1 test)
✅ Crisis response template (1 test)
✅ Medical disclaimer (2 tests)
✅ Stress support (1 test)
✅ Safety response injection (3 tests)
✅ Base safety prompt (2 tests)
✅ Safety overrides (2 tests)
**Test Results:** 31/31 passing (100% success rate)
**Execution Time:** ~9 seconds
---
## 5. API Endpoints Verified
✅ `/api/v1/ai/provider-status` - Returns provider configuration
✅ `/api/v1/ai/chat` - Main chat endpoint with all safety features
✅ `/` - Backend health check (Hello World!)
**Backend Status:** Running successfully on port 3020
**Frontend Status:** Running successfully on port 3000
**AI Provider:** Azure OpenAI (gpt-5-mini) - Configured ✅
---
## 6. Safety Metrics
### 6.1 Keyword Coverage
- **Total Keywords:** 93 keywords across 5 categories
- **Emergency:** 25 keywords
- **Crisis:** 17 keywords
- **Medical:** 27 keywords
- **Developmental:** 11 keywords
- **Stress:** 13 keywords
### 6.2 Response Templates
- **5 Safety Response Templates** (Emergency, Crisis, Medical, Developmental, Stress)
- **4 Crisis Hotlines** integrated
- **3 Emergency Resources** (911, Poison Control, Nurse Hotline)
- **2 Prompt Safety Overrides** (Medical, Crisis)
---
## 7. Remaining TODOs (Future Enhancements)
### Database Integration
- [ ] Store safety metrics in database for analytics
- [ ] Create safety metrics dashboard
- [ ] Implement incident tracking system
### Notifications
- [ ] Email notification when user is restricted
- [ ] Alert on high-risk crisis keyword patterns
### Enhanced Features
- [ ] Multi-language safety responses (currently English only)
- [ ] A/B testing of safety disclaimer effectiveness
- [ ] User feedback on safety responses
---
## 8. Key Technical Decisions
1. **Immediate Override for Emergencies/Crises**
- No AI response generated for emergency/crisis queries
- Returns safety resources immediately
- Prevents any chance of harmful AI advice in critical situations
2. **Soft Disclaimer for Medical Queries**
- AI response still generated but with prominent disclaimer
- Provides helpful information while maintaining safety boundaries
- Includes "when to seek care" guidance
3. **Compassionate Crisis Handling**
- High repeated crisis keywords flagged but not restricted
- User may genuinely need repeated support
- Logged for potential outreach/support
4. **Redis-backed Rate Limiting**
- Fast, distributed rate limiting
- Automatic expiration (daily counters reset at midnight)
- Scalable across multiple backend instances
5. **Comprehensive Testing First**
- 31 test cases before production deployment
- All safety scenarios covered
- 100% test pass rate required
---
## 9. Deployment Checklist
✅ Strategy document created
✅ Services implemented
✅ Integration complete
✅ Tests written and passing (31/31)
✅ Backend compiling successfully (0 errors)
✅ Servers running (backend port 3020, frontend port 3000)
✅ AI provider configured (Azure OpenAI)
⏳ Database migrations (TODO in code comments)
⏳ User documentation
⏳ Monitoring dashboard
**Status:** Ready for production deployment with noted TODOs
---
## 10. Safety Compliance
### HIPAA-Adjacent Considerations
✅ Never diagnose or prescribe
✅ Always redirect medical concerns to professionals
✅ Clear disclaimers on all medical content
### Child Safety (COPPA Compliance)
✅ Age-appropriate responses (0-6 years)
✅ No collection of sensitive child health data
✅ Parental guidance emphasized
### Mental Health Crisis Management
✅ Immediate crisis hotline resources
✅ 24/7 support numbers provided
✅ Non-judgmental, supportive language
---
## 11. Performance Impact
- **Rate Limiting:** Redis-backed, <1ms overhead
- **Keyword Detection:** Linear search, ~O(n) where n=93, <5ms
- **Output Moderation:** 4 regex patterns, <1ms
- **Overall Chat Latency:** +10-15ms (negligible)
---
## 12. Conclusion
**Comprehensive AI Safety system successfully implemented and tested.**
The Maternal App now provides:
- ✅ Immediate emergency response guidance
- ✅ Crisis hotline integration
- ✅ Medical disclaimers and safety boundaries
- ✅ Developmental guidance with professional referrals
- ✅ Stress support for overwhelmed parents
- ✅ Abuse prevention with rate limiting
- ✅ 100% test coverage for safety features
**All core safety features are functional and protecting users immediately.**
---
**Next Steps:**
1. Deploy to production
2. Monitor safety metrics
3. Implement database storage for analytics
4. Create monitoring dashboard
5. User education materials

517
docs/implementation-docs/AI_SAFETY_STRATEGY.md Normal file
View File

@@ -0,0 +1,517 @@
# AI Safety Strategy - Maternal App
**Purpose:** Ensure safe, responsible, and helpful AI interactions for parents seeking childcare guidance.
**Last Updated:** October 2, 2025
---
## 1. Safety Principles
### 1.1 Core Safety Values
1. **Medical Disclaimer First** - Never provide medical diagnoses or emergency advice
2. **Crisis Detection** - Recognize mental health crises and provide resources
3. **Age-Appropriate** - Responses suitable for child ages 0-6 years
4. **Evidence-Based** - Reference pediatric guidelines when possible
5. **Non-Judgmental** - Support all parenting styles without criticism
6. **Privacy-Focused** - Never request or store unnecessary medical information
### 1.2 What AI SHOULD Do
- ✅ Provide general parenting information and tips
- ✅ Suggest routines and organizational strategies
- ✅ Explain developmental milestones
- ✅ Offer emotional support and encouragement
- ✅ Direct to professional resources when appropriate
- ✅ Help track and interpret patterns in child's data
### 1.3 What AI MUST NOT Do
- ❌ Diagnose medical conditions
- ❌ Prescribe medications or dosages
- ❌ Handle medical emergencies
- ❌ Replace professional medical advice
- ❌ Make definitive statements about child development delays
- ❌ Encourage unsafe practices
---
## 2. Medical Disclaimer Triggers
### 2.1 Emergency Keywords (Immediate Disclaimer)
Trigger immediate medical disclaimer and emergency guidance:
**Critical Symptoms:**
- `emergency`, `911`, `ambulance`
- `not breathing`, `can't breathe`, `choking`
- `unconscious`, `unresponsive`, `passed out`
- `seizure`, `convulsion`, `shaking uncontrollably`
- `severe bleeding`, `blood loss`, `won't stop bleeding`
- `severe burn`, `burned`, `scalded`
- `poisoning`, `swallowed`, `ingested`
- `head injury`, `fell`, `hit head`
- `allergic reaction`, `anaphylaxis`, `swelling`
**Response Template:**
```
⚠️ EMERGENCY DISCLAIMER ⚠️
This appears to be a medical emergency. Please:
1. Call emergency services immediately (911 in US)
2. If child is not breathing, start CPR if trained
3. Stay calm and follow dispatcher instructions
I'm an AI assistant and cannot provide emergency medical guidance.
Please seek immediate professional medical help.
Emergency Resources:
- US: 911
- Poison Control: 1-800-222-1222
- Nurse Hotline: [Local number]
```
### 2.2 Medical Concern Keywords (Soft Disclaimer)
Trigger medical disclaimer but allow response with disclaimer:
**Symptoms:**
- `fever`, `temperature`, `hot`, `feverish`
- `vomiting`, `throwing up`, `vomit`
- `diarrhea`, `loose stools`, `watery stool`
- `rash`, `spots`, `bumps`, `hives`
- `cough`, `coughing`, `wheezing`
- `ear infection`, `ear pain`, `ear ache`
- `cold`, `flu`, `sick`, `illness`
- `constipation`, `not pooping`, `hard stool`
- `dehydration`, `not drinking`, `dry`
- `injury`, `hurt`, `pain`, `ache`
- `medication`, `medicine`, `dosage`, `dose`
**Response Pattern:**
```
⚠️ Medical Disclaimer: I'm an AI assistant, not a medical professional.
For medical concerns, always consult your pediatrician or healthcare provider.
[General information response, if appropriate]
When to seek immediate care:
- [Specific red flags for the symptom]
Consider calling your pediatrician if:
- [Warning signs]
```
### 2.3 Developmental Concern Keywords
- `delay`, `behind`, `not talking`, `not walking`
- `autism`, `ADHD`, `disability`, `special needs`
- `regression`, `lost skills`, `stopped doing`
**Response Pattern:**
```
⚠️ Developmental Disclaimer: Every child develops at their own pace.
If you have concerns, consult your pediatrician or early intervention specialist.
[General milestone information]
Resources:
- CDC Milestone Tracker: [link]
- Early Intervention Services: [link]
```
---
## 3. Crisis Hotline Integration
### 3.1 Mental Health Crisis Detection
**Crisis Keywords:**
- `suicide`, `kill myself`, `want to die`, `end it all`
- `hurt myself`, `self-harm`, `cutting`
- `can't cope`, `can't do this`, `giving up`
- `hopeless`, `worthless`, `burden`
- `postpartum depression`, `PPD`, `severe depression`
- `psychosis`, `hallucinations`, `voices`
- `abuse`, `hitting`, `hurting`, `violent`
**Crisis Response Template:**
```
🆘 CRISIS SUPPORT 🆘
It sounds like you're going through an incredibly difficult time.
Your feelings are valid, and help is available.
IMMEDIATE CRISIS RESOURCES:
━━━━━━━━━━━━━━━━━━━━━━━━━
🇺🇸 National Suicide Prevention Lifeline
📞 988 (call or text)
💬 Chat: 988lifeline.org
🤱 Postpartum Support International
📞 1-800-944-4773
💬 Text "HELP" to 800-944-4773
🆘 Crisis Text Line
💬 Text "HOME" to 741741
👶 Childhelp National Child Abuse Hotline
📞 1-800-422-4453
These services are:
✓ Free and confidential
✓ Available 24/7
✓ Staffed by trained counselors
✓ No judgment, only support
You don't have to go through this alone. Please reach out.
```
### 3.2 Parental Stress Detection
**Stress Keywords:**
- `overwhelmed`, `stressed`, `exhausted`, `burned out`
- `crying`, `breaking down`, `can't handle`
- `no support`, `alone`, `isolated`
- `angry at baby`, `resentful`, `regret`
**Support Response:**
```
💙 Parenting is Hard 💙
You're not alone in feeling this way. Many parents experience:
- Exhaustion and burnout
- Overwhelming emotions
- Moments of frustration
This doesn't make you a bad parent. It makes you human.
Support Resources:
🤱 Postpartum Support International: 1-800-944-4773
📞 Parents Anonymous: 1-855-427-2736
💬 Crisis Text Line: Text "PARENT" to 741741
Self-Care Reminders:
✓ Taking breaks is necessary, not selfish
✓ Asking for help is a sign of strength
✓ Your mental health matters too
[Followed by relevant coping strategies if appropriate]
```
---
## 4. Content Moderation & Filtering
### 4.1 Input Moderation
**Filter Out:**
- Inappropriate sexual content
- Violent or abusive language
- Requests for illegal activities
- Spam or commercial solicitation
- Personal information requests (addresses, SSN, etc.)
**Moderation Response:**
```
I'm here to provide parenting support and childcare guidance.
This type of content falls outside my intended use.
If you have questions about childcare for children ages 0-6,
I'm happy to help!
```
### 4.2 Output Moderation
**Before Sending AI Response, Check For:**
- Medical advice (trigger disclaimer if present)
- Potentially harmful suggestions
- Contradictory information
- Inappropriate content
- Dosage recommendations (remove/disclaim)
**Content Safety Checks:**
```typescript
const unsafePatterns = [
/\d+\s*(mg|ml|oz|tbsp|tsp)\s*(of|every|per)/i, // Dosage patterns
/give\s+(him|her|them|baby|child)\s+\d+/i, // Specific instructions with amounts
/diagnose|diagnosis|you have|they have/i, // Diagnostic language
/definitely|certainly\s+(is|has)/i, // Definitive medical statements
];
```
---
## 5. Rate Limiting & Abuse Prevention
### 5.1 Current Rate Limits
- **Free Tier:** 10 AI queries per day
- **Premium Tier:** Unlimited queries (with fair use policy)
### 5.2 Enhanced Rate Limiting
**Suspicious Pattern Detection:**
- Same question repeated >3 times in 1 hour
- Medical emergency keywords repeated >5 times in 1 day
- Queries from multiple IPs for same user (account sharing)
- Unusual query volume (>100/day even for premium)
**Action on Suspicious Activity:**
1. Temporary rate limit (1 query per hour for 24 hours)
2. Flag account for manual review
3. Send email notification to user
4. Log to security monitoring
### 5.3 Fair Use Policy (Premium)
- Maximum 200 queries per day (reasonable for active use)
- Queries should be related to childcare (0-6 years)
- No commercial use or data scraping
- No sharing of account credentials
---
## 6. System Prompt Guardrails
### 6.1 Base System Prompt (Always Included)
```
You are a helpful AI assistant for the Maternal App, designed to support
parents of children aged 0-6 years with childcare organization and guidance.
CRITICAL SAFETY RULES:
1. You are NOT a medical professional. Never diagnose or prescribe.
2. For medical emergencies, ALWAYS direct to call 911 immediately.
3. For medical concerns, ALWAYS recommend consulting a pediatrician.
4. Recognize mental health crises and provide crisis hotline resources.
5. Be supportive and non-judgmental of all parenting approaches.
6. Focus on evidence-based information from reputable sources (AAP, CDC, WHO).
7. Never provide specific medication dosages.
8. If asked about serious developmental delays, refer to professionals.
TONE:
- Warm, empathetic, and encouraging
- Clear and concise
- Non-judgmental and inclusive
- Supportive but honest
SCOPE:
- Childcare for ages 0-6 years
- Routines, tracking, organization
- General parenting tips and strategies
- Emotional support for parents
- Interpretation of tracked activity patterns
OUT OF SCOPE:
- Medical diagnosis or treatment
- Legal advice
- Financial planning
- Relationship counseling (beyond parenting partnership)
- Children outside 0-6 age range
```
### 6.2 Context-Specific Safety Additions
**When Medical Keywords Detected:**
```
MEDICAL SAFETY OVERRIDE:
This query contains medical concerns. Your response MUST:
1. Start with a medical disclaimer
2. Avoid definitive statements
3. Recommend professional consultation
4. Provide general information only
5. Include "when to seek immediate care" guidance
```
**When Crisis Keywords Detected:**
```
CRISIS RESPONSE OVERRIDE:
This query indicates a potential crisis. Your response MUST:
1. Acknowledge their feelings without judgment
2. Provide immediate crisis hotline numbers
3. Encourage reaching out for professional help
4. Be brief and focus on resources
5. Do NOT provide coping strategies that could be misinterpreted
```
---
## 7. Monitoring & Analytics
### 7.1 Safety Metrics to Track
**Daily Monitoring:**
- Number of medical disclaimer triggers
- Number of crisis hotline responses sent
- Number of emergency keyword detections
- Number of queries blocked by content filter
- Average response moderation score
**Weekly Review:**
- Trending medical concerns
- Common crisis keywords
- False positive rate for disclaimers
- User feedback on safety responses
### 7.2 Alert Thresholds
**Immediate Alerts:**
- >10 emergency keywords in 1 hour (potential abuse or real emergency pattern)
- >5 crisis keywords from single user in 24 hours (high-risk user)
- Content filter blocking >50 queries/day (attack or misconfiguration)
**Daily Review Alerts:**
- >100 medical disclaimers triggered in 24 hours
- >20 crisis responses in 24 hours
- Pattern of similar medical queries (potential misinformation spread)
---
## 8. User Education
### 8.1 First-Time User Guidance
**On First AI Query, Show:**
```
👋 Welcome to Your AI Parenting Assistant!
I'm here to help with:
✓ Childcare tips and organization
✓ Understanding your baby's patterns
✓ Answering general parenting questions
✓ Providing encouragement and support
Important to Know:
⚠️ I'm NOT a medical professional
⚠️ Always consult your pediatrician for medical concerns
⚠️ Call 911 for emergencies
For the best experience:
💡 Ask specific questions about routines, tracking, or parenting tips
💡 Share your child's age for age-appropriate guidance
💡 Use your activity tracking data for personalized insights
Let's get started! How can I help you today?
```
### 8.2 In-App Safety Reminders
**Random Safety Tips (1 in 20 responses):**
- "Remember: I'm an AI assistant, not a doctor. Always consult your pediatrician for medical advice."
- "Having a tough day? It's okay to ask for help. Check out our Resources section."
- "Emergency? Call 911 immediately. I cannot provide emergency medical guidance."
---
## 9. Implementation Checklist
### 9.1 Backend Implementation
- [ ] Create `ai-safety.service.ts` with keyword detection
- [ ] Implement medical disclaimer injection
- [ ] Add crisis hotline response generator
- [ ] Enhance content moderation filters
- [ ] Update system prompts with safety guardrails
- [ ] Add safety metrics logging
- [ ] Create safety monitoring dashboard
### 9.2 Frontend Implementation
- [ ] Add safety disclaimer modal on first AI use
- [ ] Display crisis hotlines prominently when triggered
- [ ] Show medical disclaimer badges
- [ ] Add "Report Unsafe Response" button
- [ ] Create AI Safety FAQ page
### 9.3 Testing
- [ ] Unit tests for keyword detection (100+ test cases)
- [ ] Integration tests for crisis response flow
- [ ] Manual testing of all disclaimer triggers
- [ ] User acceptance testing with parents
- [ ] Safety audit by medical professional (recommended)
### 9.4 Documentation
- [ ] User-facing AI Safety policy
- [ ] Developer documentation for safety service
- [ ] Incident response playbook
- [ ] Safety metric reporting template
---
## 10. Incident Response
### 10.1 If Harmful Response is Reported
**Immediate Actions (Within 1 hour):**
1. Flag conversation in database
2. Review full conversation history
3. Identify failure point (keyword detection, content filter, prompt)
4. Temporarily disable AI for affected user if serious
5. Notify safety team
**Follow-up Actions (Within 24 hours):**
1. Root cause analysis
2. Update keyword lists or filters
3. Test fix with similar queries
4. Document incident and resolution
5. Update user with resolution
**Communication:**
- Acknowledge report within 1 hour
- Provide resolution timeline
- Follow up when fixed
- Offer support resources if appropriate
### 10.2 Emergency Escalation
**Escalate to Management If:**
- User reports following harmful AI advice and experiencing negative outcome
- Multiple similar harmful responses in short timeframe
- Media or regulatory inquiry about AI safety
- Suicidal ideation not properly handled by crisis detection
---
## 11. Regular Safety Audits
### 11.1 Monthly Audits
- Review 100 random AI conversations
- Test all crisis and medical keyword triggers
- Analyze false positive/negative rates
- Update keyword lists based on new patterns
- Review user reports and feedback
### 11.2 Quarterly Reviews
- External safety audit (if possible)
- Update crisis hotline numbers (verify still active)
- Review and update safety policies
- Train team on new safety features
- Benchmark against industry standards
---
## 12. Compliance & Legal
### 12.1 Disclaimers (Required)
- [ ] Terms of Service mention AI limitations
- [ ] Privacy Policy covers AI data usage
- [ ] Medical disclaimer in AI interface
- [ ] Crisis resources easily accessible
### 12.2 Recommended Legal Review
- AI response liability
- Medical advice disclaimers sufficiency
- Crisis response appropriateness
- Age-appropriate content standards
---
## Status: READY FOR IMPLEMENTATION
**Priority:** HIGH - User Safety Critical
**Estimated Implementation Time:** 3-5 days
**Testing Time:** 2 days
**Total:** 5-7 days with testing
**Next Steps:**
1. Implement `AISafetyService` with keyword detection
2. Update `AIService` to integrate safety checks
3. Add crisis hotline database/configuration
4. Create frontend safety components
5. Comprehensive testing with real scenarios
6. User documentation
This strategy ensures the Maternal App AI is helpful, supportive, and above all, SAFE for parents seeking guidance.

286
docs/implementation-docs/EMBEDDINGS-IMPLEMENTATION.md Normal file
View File

@@ -0,0 +1,286 @@
# Embeddings-Based Conversation Memory Implementation
## ✅ Implementation Complete
Successfully implemented vector embeddings-based semantic search for AI conversation memory in the Maternal App.
## 🎯 What Was Implemented
### 1. Database Layer (pgvector)
- ✅ Installed pgvector extension in PostgreSQL 15
- ✅ Created `V014_create_conversation_embeddings.sql` migration
- ✅ Table: `conversation_embeddings` with 1536-dimension vectors
- ✅ HNSW index for fast similarity search (m=16, ef_construction=64)
- ✅ GIN index on topics array for filtering
- ✅ PostgreSQL functions for semantic search:
- `search_similar_conversations()` - General similarity search
- `search_conversations_by_topic()` - Topic-filtered search
### 2. Entity Layer
- ✅ Created `ConversationEmbedding` entity in TypeORM
- ✅ Helper methods for vector conversion:
- `vectorToString()` - Convert array to PostgreSQL vector format
- `stringToVector()` - Parse PostgreSQL vector to array
- `cosineSimilarity()` - Calculate similarity between vectors
### 3. Embeddings Service (`embeddings.service.ts`)
- ✅ Azure OpenAI integration for text-embedding-ada-002
- ✅ Single and batch embedding generation
- ✅ Semantic similarity search with cosine distance
- ✅ Topic-based filtering support
- ✅ User statistics and health check endpoints
- ✅ Backfill capability for existing conversations
**Key Features:**
```typescript
- generateEmbedding(text: string): Promise<EmbeddingGenerationResult>
- generateEmbeddingsBatch(texts: string[]): Promise<EmbeddingGenerationResult[]>
- storeEmbedding(conversationId, userId, messageIndex, role, content, topics)
- searchSimilarConversations(query, userId, options)
- getUserEmbeddingStats(userId)
- healthCheck()
```
### 4. Enhanced Conversation Memory (`conversation-memory.service.ts`)
- ✅ Integrated embeddings service
- ✅ Semantic context retrieval:
- `getSemanticContext()` - Find similar past conversations
- `getConversationWithSemanticMemory()` - Combined traditional + semantic memory
- `storeMessageEmbedding()` - Async embedding storage
- `backfillConversationEmbeddings()` - Migrate existing conversations
**Context Strategy:**
1. Search for semantically similar conversations using current query
2. Combine with traditional message window (20 most recent)
3. Prune to fit 4000 token budget
4. Return enriched context for AI response
### 5. AI Service Integration (`ai.service.ts`)
- ✅ Embedded `EmbeddingsService` in constructor
- ✅ Automatic semantic search on every chat request
- ✅ Async, non-blocking embedding storage for new messages
- ✅ Graceful fallback if embeddings fail
**Integration Flow:**
```typescript
chat(userId, chatDto) {
// 1. Get conversation with semantic memory
const { context } = await conversationMemoryService
.getConversationWithSemanticMemory(conversationId, userMessage);
// 2. Generate AI response using enriched context
const response = await generateWithAzure(context);
// 3. Store embeddings asynchronously (non-blocking)
conversationMemoryService.storeMessageEmbedding(...)
.catch(err => logger.warn(...));
}
```
### 6. AI Module Configuration
- ✅ Added `EmbeddingsService` to providers
- ✅ Added `ConversationEmbedding` to TypeORM entities
- ✅ Full dependency injection
### 7. Testing Endpoints (Public for Testing)
Added test endpoints in `ai.controller.ts`:
```typescript
@Public()
@Post('test/embeddings/generate')
testGenerateEmbedding(body: { text: string })
@Public()
@Post('test/embeddings/search')
testSearchSimilar(body: { query, userId?, threshold?, limit? })
@Public()
@Get('test/embeddings/health')
testEmbeddingsHealth()
@Public()
@Get('test/embeddings/stats/:userId')
testEmbeddingsStats(userId)
```
### 8. Comprehensive Test Suite (`test-embeddings.js`)
Created automated test script with 6 test scenarios:
1. ✅ Health check verification
2. ✅ Embedding generation (1536 dimensions)
3. ✅ Conversation creation with automatic embedding storage
4. ✅ Semantic search validation
5. ✅ User statistics retrieval
6. ✅ Semantic memory integration test
## 🔧 Technical Specifications
### Vector Embeddings
- **Model**: Azure OpenAI `text-embedding-ada-002`
- **Dimensions**: 1536
- **Similarity Metric**: Cosine distance
- **Indexing**: HNSW (Hierarchical Navigable Small World)
- **Default Threshold**: 0.7 (70% similarity)
### Performance Optimizations
- **HNSW Parameters**:
- `m = 16` (max connections per layer)
- `ef_construction = 64` (build quality)
- **Batch Processing**: Up to 100 embeddings per request
- **Async Storage**: Non-blocking embedding persistence
- **Token Budget**: 4000 tokens per context window
- **Cache Strategy**: Recent 20 messages + top 3 semantic matches
### Database Schema
```sql
CREATE TABLE conversation_embeddings (
id VARCHAR(30) PRIMARY KEY,
conversation_id VARCHAR(30) NOT NULL,
user_id VARCHAR(30) NOT NULL,
message_index INTEGER NOT NULL,
message_role VARCHAR(20) NOT NULL,
message_content TEXT NOT NULL,
embedding vector(1536) NOT NULL, -- pgvector type
topics TEXT[], -- Array of topics
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
CONSTRAINT fk_conversation FOREIGN KEY (conversation_id)
REFERENCES ai_conversations(id) ON DELETE CASCADE,
CONSTRAINT fk_user FOREIGN KEY (user_id)
REFERENCES users(id) ON DELETE CASCADE
);
-- HNSW index for fast similarity search
CREATE INDEX idx_conversation_embeddings_vector
ON conversation_embeddings
USING hnsw (embedding vector_cosine_ops)
WITH (m = 16, ef_construction = 64);
-- GIN index for topic filtering
CREATE INDEX idx_conversation_embeddings_topics
ON conversation_embeddings USING GIN (topics);
```
## 📊 Use Cases
### 1. Contextual Parenting Advice
When a parent asks: "My baby is having trouble sleeping"
The system:
1. Generates embedding for the query
2. Searches for similar past conversations (e.g., sleep issues, nap troubles)
3. Retrieves context from semantically related discussions
4. Provides personalized advice based on user's history
### 2. Pattern Recognition
- Identifies recurring concerns across conversations
- Suggests proactive solutions based on similar experiences
- Tracks topic evolution over time
### 3. Cross-Topic Insights
Connects related concerns even if discussed with different wording:
- "sleepless nights" ↔ "insomnia problems"
- "feeding difficulties" ↔ "eating challenges"
- "development delays" ↔ "milestone concerns"
## 🔐 Security & Privacy
- ✅ User-specific search (never cross-user)
- ✅ Cascade deletion with conversation removal
- ✅ No embedding data in API responses (only metadata)
- ✅ Rate limiting on embedding generation
- ✅ Graceful degradation if embeddings fail
## 📁 Files Created/Modified
### New Files:
1. `/src/database/migrations/V014_create_conversation_embeddings.sql`
2. `/src/database/entities/conversation-embedding.entity.ts`
3. `/src/modules/ai/embeddings/embeddings.service.ts`
4. `/test-embeddings.js` (Test suite)
### Modified Files:
1. `/src/modules/ai/ai.module.ts` - Added embeddings service
2. `/src/modules/ai/ai.service.ts` - Integrated semantic search
3. `/src/modules/ai/memory/conversation-memory.service.ts` - Added semantic methods
4. `/src/modules/ai/ai.controller.ts` - Added test endpoints
5. `/src/database/entities/index.ts` - Exported new entity
## 🚀 How to Test
### 1. Health Check
```bash
curl http://localhost:3020/api/v1/ai/test/embeddings/health
```
### 2. Generate Embedding
```bash
curl -X POST http://localhost:3020/api/v1/ai/test/embeddings/generate \
-H "Content-Type: application/json" \
-d '{"text": "My baby is not sleeping well"}'
```
### 3. Search Similar Conversations
```bash
curl -X POST http://localhost:3020/api/v1/ai/test/embeddings/search \
-H "Content-Type: application/json" \
-d '{
"query": "sleep problems",
"userId": "test_user_123",
"threshold": 0.7,
"limit": 5
}'
```
### 4. Run Automated Test Suite
```bash
node test-embeddings.js
```
## 🔄 Migration Path
### For Existing Conversations:
Use the backfill endpoint to generate embeddings for historical data:
```typescript
await conversationMemoryService.backfillConversationEmbeddings(conversationId);
```
This will:
1. Extract all messages from the conversation
2. Generate embeddings in batch
3. Store with detected topics
4. Skip if embeddings already exist
## 📈 Future Enhancements
### Potential Improvements:
1. **Embedding Model Upgrades**: Support for newer models (ada-003, etc.)
2. **Multi-vector Search**: Combine multiple query embeddings
3. **Hybrid Search**: BM25 + vector similarity
4. **Topic Modeling**: Automatic topic extraction with clustering
5. **Reranking**: Post-search relevance scoring
6. **Caching**: Embedding cache for frequent queries
### Performance Tuning:
- IVFFlat index for larger datasets (>1M vectors)
- Quantization for reduced storage
- Approximate search for better speed
## ✅ Verification Checklist
- [x] pgvector extension installed and functional
- [x] Migration V014 applied successfully
- [x] ConversationEmbedding entity created
- [x] EmbeddingsService implemented with Azure OpenAI
- [x] Conversation memory enhanced with semantic search
- [x] AI service integrated with embeddings
- [x] Test endpoints exposed (public for testing)
- [x] Comprehensive test suite created
- [x] Database indexes optimized
- [x] Error handling and fallbacks implemented
- [x] Documentation complete
## 🎉 Status: COMPLETE & READY FOR TESTING
The embeddings-based conversation memory system is fully implemented and integrated into the Maternal App AI service. The system provides semantic search capabilities that enhance the AI's ability to provide contextual, personalized parenting advice based on the user's conversation history.
**Note**: The test endpoints in `ai.controller.ts` are marked as `@Public()` for testing purposes. Remember to remove or properly secure these endpoints before production deployment.

177
docs/implementation-docs/PACKAGE_UPGRADE_PLAN.md Normal file
View File

@@ -0,0 +1,177 @@
# Package Upgrade Plan
## Overview
Upgrading all packages to latest versions before codebase becomes too complex. Strategy: upgrade incrementally, test after each major upgrade, fix breaking changes.
## Backend Packages to Upgrade
### Critical Major Version Upgrades (Breaking Changes Expected)
1. **NestJS Framework** (v10 → v11) - MAJOR
- @nestjs/common: 10.4.20 → 11.1.6
- @nestjs/core: 10.4.20 → 11.1.6
- @nestjs/platform-express: 10.4.20 → 11.1.6
- @nestjs/platform-socket.io: 10.4.20 → 11.1.6
- @nestjs/websockets: 10.4.20 → 11.1.6
- @nestjs/testing: 10.4.20 → 11.1.6
- @nestjs/cli: 10.4.9 → 11.0.10
- @nestjs/schematics: 10.2.3 → 11.0.7
- **Breaking Changes**: Check NestJS v11 migration guide
- **Risk**: HIGH - Core framework upgrade
- **Test Requirements**: Full regression testing
2. **Apollo Server** (v4 → v5) - MAJOR
- @apollo/server: 4.12.2 → 5.0.0
- **Breaking Changes**: GraphQL schema changes, middleware changes
- **Risk**: MEDIUM - Only affects GraphQL endpoints
- **Test Requirements**: GraphQL endpoint testing
3. **Jest** (v29 → v30) - MAJOR
- jest: 29.7.0 → 30.2.0
- @types/jest: 29.5.14 → 30.0.0
- **Breaking Changes**: Test framework syntax changes
- **Risk**: LOW - Mainly test code
- **Test Requirements**: Run test suite
4. **ESLint** (v8 → v9) - MAJOR
- eslint: 8.57.1 → 9.36.0
- eslint-config-prettier: 9.1.2 → 10.1.8
- **Breaking Changes**: Flat config format
- **Risk**: LOW - Development tool only
- **Test Requirements**: Linting passes
5. **OpenAI SDK** (v5 → v6) - MAJOR
- openai: 5.23.2 → 6.0.1
- **Breaking Changes**: API method signatures
- **Risk**: MEDIUM - Affects AI features
- **Test Requirements**: AI conversation testing
### Minor/Patch Version Upgrades (Low Risk)
6. **AWS SDK** - PATCH
- @aws-sdk/client-s3: 3.899.0 → 3.901.0
- @aws-sdk/lib-storage: 3.900.0 → 3.901.0
- @aws-sdk/s3-request-presigner: 3.899.0 → 3.901.0
- **Risk**: VERY LOW - Patch updates
7. **TypeScript** - PATCH
- typescript: 5.9.2 → 5.9.3
- **Risk**: VERY LOW - Patch update
8. **Node Types** - MAJOR (but safe)
- @types/node: 20.19.18 → 24.6.2
- **Risk**: LOW - Type definitions only
9. **Other Minor Updates**
- @nestjs/graphql: 13.1.0 → 13.2.0
- cache-manager: 7.2.2 → 7.2.3
- redis: 5.8.2 → 5.8.3
## Upgrade Strategy
### Phase 1: Low-Risk Patches (Start Here)
```bash
# Patch updates - safe, no breaking changes
npm update typescript
npm update @aws-sdk/client-s3 @aws-sdk/lib-storage @aws-sdk/s3-request-presigner
npm update cache-manager redis
npm update @types/node
```
- **Test**: Basic compile + server starts
- **Time**: 10 minutes
### Phase 2: Minor Version Bumps
```bash
npm install @nestjs/graphql@latest
```
- **Test**: GraphQL endpoints still work
- **Time**: 15 minutes
### Phase 3: OpenAI SDK Upgrade (Medium Risk)
```bash
npm install openai@latest
```
- **Check**: OpenAI v6 migration guide
- **Fix**: AI conversation code
- **Test**: Voice transcription + AI chat
- **Time**: 30-60 minutes
### Phase 4: Jest Upgrade (Medium Risk)
```bash
npm install -D jest@latest @types/jest@latest
npm install -D ts-jest@latest # May need update too
```
- **Check**: Jest v30 migration guide
- **Fix**: Test configuration
- **Test**: Run full test suite
- **Time**: 30-45 minutes
### Phase 5: ESLint Upgrade (Medium Risk)
```bash
npm install -D eslint@latest eslint-config-prettier@latest
```
- **Check**: ESLint v9 flat config migration
- **Fix**: .eslintrc.js → eslint.config.js
- **Test**: Linting passes
- **Time**: 30-45 minutes
### Phase 6: Apollo Server Upgrade (High Risk)
```bash
npm install @apollo/server@latest
```
- **Check**: Apollo Server v5 migration guide
- **Fix**: GraphQL server setup
- **Test**: All GraphQL queries/mutations
- **Time**: 1-2 hours
### Phase 7: NestJS v11 Upgrade (HIGHEST RISK - DO LAST)
```bash
npm install @nestjs/common@latest @nestjs/core@latest @nestjs/platform-express@latest @nestjs/platform-socket.io@latest @nestjs/websockets@latest
npm install -D @nestjs/cli@latest @nestjs/schematics@latest @nestjs/testing@latest
```
- **Check**: NestJS v11 migration guide: https://docs.nestjs.com/migration-guide
- **Fix**: Breaking changes across entire codebase
- **Test**: FULL regression testing
- **Time**: 2-4 hours
## Testing Checklist After Each Phase
- [ ] Backend compiles with no TypeScript errors
- [ ] Server starts successfully
- [ ] Health endpoint responds
- [ ] Auth endpoints work (login/register)
- [ ] Protected endpoints require JWT
- [ ] Database connections work
- [ ] GraphQL playground loads (if applicable)
- [ ] WebSocket connections work
- [ ] All tests pass
- [ ] No new console warnings
## Rollback Plan
Each phase should be committed separately:
```bash
git add .
git commit -m "Phase X: Upgrade [package names]"
```
If issues arise:
```bash
git revert HEAD
npm install
```
## Estimated Total Time
- Phase 1-2: 30 minutes
- Phase 3-5: 2-3 hours
- Phase 6-7: 3-6 hours
**Total: 5-9 hours** (spread over multiple sessions)
## Notes
- Keep backend server running in watch mode to catch compile errors immediately
- Test each endpoint manually after major upgrades
- Check deprecation warnings in console
- Update this document with any issues encountered

526
docs/implementation-docs/TESTING_STRATEGY.md Normal file
View File

@@ -0,0 +1,526 @@
# Testing Strategy - Maternal App
**Target Coverage:** 80%+ across all layers
**Testing Pyramid:** Unit (70%) → Integration (20%) → E2E (10%)
---
## 1. Backend Testing (NestJS)
### 1.1 Unit Tests (Target: 70% of tests)
**Tools:** Jest, @nestjs/testing
**What to Test:**
- **Services** (Business Logic)
- ComplianceService (data export, account deletion)
- AuthService (registration with COPPA validation, login, token management)
- ChildrenService (CRUD operations)
- TrackingService (activity creation, daily summary)
- AIService (chat, conversation memory)
- VoiceService (intent classification, entity extraction)
- EmbeddingsService (vector search, semantic memory)
- **Guards**
- JwtAuthGuard
- Public decorator
- **Pipes**
- ValidationPipe (DTO validation)
- **Utilities**
- Date calculations
- Age verification (COPPA compliance)
- Token generation
**Example Test Structure:**
```typescript
describe('ComplianceService', () => {
let service: ComplianceService;
let userRepository: Repository<User>;
beforeEach(async () => {
const module = await Test.createTestingModule({
providers: [
ComplianceService,
{ provide: getRepositoryToken(User), useClass: Repository },
],
}).compile();
service = module.get<ComplianceService>(ComplianceService);
});
it('should export user data with all entities', async () => {
// Test implementation
});
it('should schedule account deletion with 30-day grace period', async () => {
// Test implementation
});
});
```
### 1.2 Integration Tests (Target: 20% of tests)
**Tools:** Jest, Supertest, @nestjs/testing
**What to Test:**
- **API Endpoints** (Controller + Service + Database)
- POST /api/v1/compliance/data-export
- POST /api/v1/compliance/request-deletion
- POST /api/v1/auth/register (with COPPA validation)
- POST /api/v1/auth/login
- POST /api/v1/activities (tracking)
- POST /api/v1/ai/chat
- **Authentication Flows**
- Register → Login → Protected Route
- Register with COPPA (age 13-17)
- Register blocked (age < 13)
- **Database Operations**
- CRUD operations with real database
- Transaction rollbacks
- Cascade deletions
**Example Test Structure:**
```typescript
describe('ComplianceController (e2e)', () => {
let app: INestApplication;
let authToken: string;
beforeAll(async () => {
const moduleFixture = await Test.createTestingModule({
imports: [AppModule],
}).compile();
app = moduleFixture.createNestApplication();
await app.init();
});
it('/api/v1/compliance/data-export (GET)', () => {
return request(app.getHttpServer())
.get('/api/v1/compliance/data-export')
.set('Authorization', `Bearer ${authToken}`)
.expect(200)
.expect((res) => {
expect(res.body.data).toHaveProperty('user');
expect(res.body.data).toHaveProperty('children');
expect(res.body.data).toHaveProperty('activities');
});
});
});
```
---
## 2. Frontend Testing (Next.js + React)
### 2.1 Unit Tests (Component Testing)
**Tools:** Jest, React Testing Library, @testing-library/user-event
**What to Test:**
- **Components**
- DataExport component (button click, download trigger)
- AccountDeletion component (dialog flow, deletion request)
- Registration form (COPPA age validation, form submission)
- Settings page (profile update, compliance sections)
- Tracking forms (feeding, sleep, diaper)
- **Redux Slices**
- authSlice (login, logout, token refresh)
- childrenSlice (CRUD operations)
- activitiesSlice (create, update, delete)
- offlineSlice (sync queue, conflict resolution)
- **API Clients**
- complianceApi (all methods)
- authApi, childrenApi, trackingApi
- **Utilities**
- Date formatting
- Age calculation
- Token storage
**Example Test Structure:**
```typescript
import { render, screen, fireEvent, waitFor } from '@testing-library/react';
import { DataExport } from '@/components/settings/DataExport';
import { complianceApi } from '@/lib/api/compliance';
jest.mock('@/lib/api/compliance');
describe('DataExport Component', () => {
it('should download user data when button is clicked', async () => {
const mockDownload = jest.fn();
(complianceApi.downloadUserData as jest.Mock) = mockDownload;
render(<DataExport />);
const button = screen.getByText('Download My Data');
fireEvent.click(button);
await waitFor(() => {
expect(mockDownload).toHaveBeenCalledTimes(1);
});
expect(screen.getByText('Your data has been downloaded successfully!')).toBeInTheDocument();
});
it('should show error message on download failure', async () => {
(complianceApi.downloadUserData as jest.Mock).mockRejectedValue(
new Error('Network error')
);
render(<DataExport />);
fireEvent.click(screen.getByText('Download My Data'));
await waitFor(() => {
expect(screen.getByText(/Failed to export data/)).toBeInTheDocument();
});
});
});
```
### 2.2 Integration Tests (API Interaction)
**What to Test:**
- Form submission with API calls
- Authentication flows
- Error handling and retry logic
- Optimistic updates with Redux
---
## 3. End-to-End Tests (Target: 10% of tests)
**Tools:** Playwright
**Critical User Journeys:**
### 3.1 Registration & COPPA Compliance
```typescript
test('User under 13 cannot register', async ({ page }) => {
await page.goto('/register');
await page.fill('[name="name"]', 'John Doe');
await page.fill('[name="email"]', 'john@example.com');
await page.fill('[name="dateOfBirth"]', '2015-01-01'); // 9 years old
await page.fill('[name="password"]', 'SecurePass123');
await page.fill('[name="confirmPassword"]', 'SecurePass123');
await page.check('[name="agreeToTerms"]');
await page.check('[name="agreeToPrivacy"]');
await page.click('button[type="submit"]');
await expect(page.locator('text=/Users under 13/')).toBeVisible();
});
test('User 13-17 requires parental consent', async ({ page }) => {
await page.goto('/register');
await page.fill('[name="dateOfBirth"]', '2010-01-01'); // 14 years old
// Parental email field should appear
await expect(page.locator('[name="parentalEmail"]')).toBeVisible();
await expect(page.locator('text=/parental consent/')).toBeVisible();
});
```
### 3.2 Account Deletion Flow
```typescript
test('User can request account deletion and cancel it', async ({ page }) => {
// Login
await login(page, 'user@example.com', 'password');
// Navigate to settings
await page.goto('/settings');
// Request deletion
await page.click('text=Delete My Account');
await page.fill('[name="reason"]', 'Testing deletion flow');
await page.click('button:has-text("Delete Account")');
// Verify deletion scheduled
await expect(page.locator('text=/Account deletion scheduled/')).toBeVisible();
// Cancel deletion
await page.click('text=Cancel Deletion Request');
await page.click('button:has-text("Cancel Deletion")');
// Verify cancellation
await expect(page.locator('text=/cancelled successfully/')).toBeVisible();
});
```
### 3.3 Data Export Flow
```typescript
test('User can export their data', async ({ page }) => {
await login(page, 'user@example.com', 'password');
await page.goto('/settings');
const [download] = await Promise.all([
page.waitForEvent('download'),
page.click('text=Download My Data')
]);
expect(download.suggestedFilename()).toMatch(/maternal-app-data-export.*\.json/);
});
```
### 3.4 Activity Tracking Flow
```typescript
test('User can track feeding activity', async ({ page }) => {
await login(page, 'user@example.com', 'password');
await page.goto('/track/feeding');
await page.selectOption('[name="childId"]', { index: 0 });
await page.fill('[name="amount"]', '120');
await page.selectOption('[name="unit"]', 'ml');
await page.click('button:has-text("Save")');
await expect(page.locator('text=/Activity saved/')).toBeVisible();
// Verify on dashboard
await page.goto('/');
await expect(page.locator('text=/Feeding/')).toBeVisible();
});
```
---
## 4. Code Coverage Goals
### 4.1 Overall Targets
- **Total Coverage:** 80%+
- **Statements:** 80%+
- **Branches:** 75%+
- **Functions:** 80%+
- **Lines:** 80%+
### 4.2 Module-Specific Targets
**Backend:**
- Auth Module: 90%+ (critical security)
- Compliance Module: 95%+ (legal requirement)
- Tracking Module: 85%+
- AI Module: 80%+
- Voice Module: 80%+
**Frontend:**
- Compliance Components: 95%+
- Auth Components: 90%+
- Tracking Components: 85%+
- API Clients: 90%+
- Redux Slices: 85%+
---
## 5. CI/CD Integration
### 5.1 GitHub Actions Workflow
**Triggers:**
- Push to main branch
- Pull request to main
- Scheduled nightly runs
**Steps:**
1. Checkout code
2. Setup Node.js (v20)
3. Install dependencies
4. Run linter (ESLint)
5. Run backend unit tests
6. Run backend integration tests
7. Run frontend tests
8. Run E2E tests
9. Generate coverage reports
10. Upload coverage to Codecov
11. Fail PR if coverage drops below 80%
**Example `.github/workflows/test.yml`:**
```yaml
name: Test Suite
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
backend-tests:
runs-on: ubuntu-latest
services:
postgres:
image: postgres:15
env:
POSTGRES_PASSWORD: test
options: >-
--health-cmd pg_isready
--health-interval 10s
--health-timeout 5s
--health-retries 5
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: '20'
- run: npm ci
- run: npm test -- --coverage
- uses: codecov/codecov-action@v3
frontend-tests:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
- run: npm ci
- run: npm test -- --coverage
e2e-tests:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
- run: npx playwright install --with-deps
- run: npm run test:e2e
```
---
## 6. Test Data Management
### 6.1 Test Database
- Use separate test database
- Seed with test fixtures
- Clean between tests
### 6.2 Test Fixtures
- Create factory functions for test data
- Predefined users, children, activities
- COPPA-compliant test scenarios (various ages)
**Example:**
```typescript
export const testUsers = {
adult: {
name: 'Adult User',
email: 'adult@example.com',
dateOfBirth: '1990-01-01',
},
minor14: {
name: 'Teen User',
email: 'teen@example.com',
dateOfBirth: '2010-01-01',
parentalEmail: 'parent@example.com',
coppaConsentGiven: true,
},
child12: {
name: 'Child User',
email: 'child@example.com',
dateOfBirth: '2012-01-01', // Should be blocked
},
};
```
---
## 7. Testing Best Practices
### 7.1 General Principles
- **AAA Pattern:** Arrange, Act, Assert
- **DRY:** Don't Repeat Yourself (use factories and helpers)
- **Fast:** Keep unit tests under 100ms
- **Isolated:** No dependencies between tests
- **Deterministic:** Same input = same output
### 7.2 Mocking Strategy
- Mock external services (Azure OpenAI, Mailgun, MinIO)
- Mock time-dependent functions
- Use in-memory database for unit tests
- Real database for integration tests
### 7.3 Naming Conventions
```typescript
describe('ServiceName', () => {
describe('methodName', () => {
it('should do something when condition', () => {
// Test
});
it('should throw error when invalid input', () => {
// Test
});
});
});
```
---
## 8. Continuous Improvement
### 8.1 Metrics to Track
- Code coverage percentage
- Test execution time
- Flaky test rate
- Bug escape rate
### 8.2 Review Process
- All PRs must have tests
- Coverage must not decrease
- CI must pass before merge
---
## 9. Implementation Timeline
**Week 1:**
- ✅ Setup Jest for backend and frontend
- ✅ Create first unit tests (Compliance, Auth)
- ✅ Setup test database
**Week 2:**
- ✅ Create integration tests for critical endpoints
- ✅ Setup Playwright for E2E
- ✅ Create E2E tests for COPPA flows
**Week 3:**
- ✅ Expand coverage to 50%+
- ✅ Setup CI/CD pipeline
- ✅ Configure coverage reporting
**Week 4:**
- ✅ Reach 80%+ coverage
- ✅ Optimize test performance
- ✅ Documentation and training
---
## 10. Quick Start Commands
```bash
# Backend
cd maternal-app-backend
npm test # Run all tests
npm test -- --coverage # With coverage
npm test -- --watch # Watch mode
npm run test:e2e # Integration tests
# Frontend
cd maternal-web
npm test # Run all tests
npm test -- --coverage # With coverage
npm test -- --watch # Watch mode
npm run test:e2e # E2E with Playwright
# Coverage Reports
npm test -- --coverage --coverageReporters=html
# Open coverage/index.html in browser
```
---
## Status: IN PROGRESS
**Current Coverage:** 0%
**Target Coverage:** 80%+
**Estimated Completion:** 3-4 weeks