NeWomen Platform

NeWomen is an AI-powered personal growth platform featuring an emotionally intelligent AI companion called "NewMe". The platform provides culturally sensitive, speech-to-speech conversations with persistent memory and comprehensive wellness features.

Features

• AI Companion: Emotionally intelligent AI with persistent memory and context awareness
• Speech-to-Speech: Real-time audio conversations using WebRTC and voice recognition
• Balance Wheel Assessment: Life balance evaluation across 8 key areas
• Gamification System: Points, levels, achievements, and daily challenges
• Wellness Resources: Curated content from licensed professionals
• Community Features: Partner connections, group challenges, anonymous sharing
• Cultural Sensitivity: Adapts to user's cultural context and preferences
• Narrative Exploration: AI-powered analysis and transformation roadmaps

Tech Stack

Frontend

• Framework: Next.js 14+ with React 18+ and TypeScript
• Styling: Tailwind CSS with custom glassmorphic components
• Animations: Framer Motion for smooth interactions
• PWA: Service workers with next-pwa for offline functionality
• State Management: React Context API for auth and global state

Backend

• Runtime: Node.js with TypeScript
• API: Next.js API routes with custom middleware
• Database: PostgreSQL with direct pg client (no ORM)
• Caching: Redis for session and data caching
• Vector DB: Pinecone for AI embeddings and memory storage

AI Services

• LLM: OpenAI GPT-4 with Anthropic Claude fallback
• Speech: WebRTC for real-time audio, OpenAI Whisper (STT), ElevenLabs (TTS)
• Processing: Custom prompt engineering with context management

Getting Started

Prerequisites

• Node.js 18+ and npm
• Docker and Docker Compose (for local development)
• PostgreSQL 14+
• Redis 6+

Installation

1. Clone the repository:

   git clone https://github.com/yourusername/NeWomen-platform.git
   cd NeWomen-platform

2. Run the setup script to install dependencies and set up the development environment:

   ./setup.sh

3. Create a .env file based on the .env.example template and fill in your API keys and configuration.

4. Start the development server:

   ./dev.sh
   # or
   npm run dev

5. Open http://localhost:3000 in your browser to see the application.

Development Commands

# Type checking
npm run type-check

# Linting
npm run lint

# Run tests
./test.sh
# or specific test types
npm run test              # Unit tests
npm run test:watch        # Watch mode
npm run test:coverage     # Coverage report
npm run test:integration  # Integration tests
npm run test:e2e          # E2E tests

Project Structure

NeWomen-platform/
├── src/
│   ├── app/                    # Next.js App Router
│   │   ├── api/               # API routes organized by feature
│   │   ├── (pages)/           # Page components
│   │   ├── layout.tsx         # Root layout
│   │   └── globals.css        # Global styles
│   ├── components/            # React components
│   │   ├── ui/               # Reusable UI components (Glass*)
│   │   ├── audio/            # Audio-related components
│   │   ├── chat/             # Chat interface components
│   │   ├── gamification/     # Gamification components
│   │   ├── navigation/       # Navigation components
│   │   └── [feature]/        # Feature-specific components
│   ├── lib/                  # Business logic and services
│   │   ├── [service]/        # Service implementations
│   │   ├── types/            # TypeScript type definitions
│   │   ├── hooks/            # Custom React hooks
│   │   └── utils.ts          # Utility functions
│   ├── styles/               # CSS files
│   └── middleware.ts         # Next.js middleware
├── public/                   # Static assets
├── database/                 # Database migrations and schema
├── docs/                     # Documentation
├── tests/                    # Test files organized by type
├── e2e/                      # End-to-end tests
└── scripts/                  # Utility scripts

Deployment

Overview

The NeWomen platform uses a Build-Runtime Separation Pattern to ensure successful deployments across different environments. Database operations are deferred to runtime initialization to avoid build-time connectivity issues.

Environment Variables

Required for All Environments

# Core Application
NODE_ENV=production
NEXTAUTH_SECRET=your-nextauth-secret-here
JWT_SECRET=your-jwt-secret-here

# Database & Caching
DATABASE_URL=postgresql://user:password@host:port/database
REDIS_URL=redis://user:password@host:port

# AI Services
OPENAI_API_KEY=sk-your-openai-key
ANTHROPIC_API_KEY=sk-ant-your-anthropic-key
ELEVENLABS_API_KEY=your-elevenlabs-key
PINECONE_API_KEY=your-pinecone-key

# Payment Processing
PAYPAL_CLIENT_ID=your-paypal-client-id
PAYPAL_CLIENT_SECRET=your-paypal-client-secret

# Public URLs (for Vercel/production)
NEXT_PUBLIC_APP_URL=https://your-domain.com

Optional Environment Variables

# Additional AI Providers
GOOGLE_AI_API_KEY=your-google-ai-key

# Monitoring & Analytics
SENTRY_DSN=your-sentry-dsn
ANALYTICS_ID=your-analytics-id

# Development Only
SKIP_ENV_VALIDATION=true  # Only for development

Local Development Deployment

1. Setup Environment:

   cp .env.example .env
   # Edit .env with your configuration

2. Install Dependencies:

   npm ci --legacy-peer-deps

3. Start Services:

   docker-compose up -d  # Start PostgreSQL and Redis

4. Initialize Database:

   npm run db:init:local

5. Start Development Server:

   npm run dev

Production Deployment

Build Process

The production build is optimized to avoid database connectivity during build time:

# Validate build environment (no database required)
npm run env:validate:build

# Build application (static assets only)
npm run build:production

Runtime Initialization

Database operations occur during application startup:

# Validate runtime environment (database required)
npm run env:validate:runtime

# Start production server (includes runtime DB initialization)
npm run start:production

Vercel Deployment

Configuration

The platform is configured for Vercel deployment with the following key settings:

• Build Command: npm run build:vercel (database-free build)
• Install Command: npm ci --legacy-peer-deps
• Start Command: Automatic (Next.js runtime)
• Runtime Initialization: Automatic on first request

Environment Setup in Vercel

1. Go to your Vercel project settings
2. Navigate to "Environment Variables"
3. Add all required environment variables listed above
4. Ensure DATABASE_URL points to your production database
5. Set NODE_ENV=production

Deployment Steps

1. Connect Repository: Link your GitHub repository to Vercel
2. Configure Build Settings:
   • Framework Preset: Next.js
   • Build Command: npm run build:vercel
   • Install Command: npm ci --legacy-peer-deps
3. Set Environment Variables: Add all required variables
4. Deploy: Push to main branch or trigger manual deployment

Post-Deployment Verification

# Check application health
curl https://your-domain.com/api/health

# Verify database initialization
curl https://your-domain.com/api/health/detailed

Docker Deployment

Production Docker Build

# Build production image
docker build -f Dockerfile.production -t newomen-platform:latest .

# Run with environment file
docker run --env-file .env.production -p 3000:3000 newomen-platform:latest

Docker Compose Production

# Start all services
docker-compose -f docker-compose.production.yml up -d

# Check service health
docker-compose -f docker-compose.production.yml ps

Kubernetes Deployment

Production Deployment

# Apply production configurations
kubectl apply -f k8s/production/

# Check deployment status
kubectl get pods -l app=newomen-platform

# View logs
kubectl logs -l app=newomen-platform --tail=100

Health Checks

The platform provides comprehensive health check endpoints:

• Basic Health: GET /api/health

  • Returns 200 if application is running
  • No database dependency

• Detailed Health: GET /api/health/detailed

  • Returns comprehensive system status
  • Includes database, Redis, and AI service connectivity
  • Shows initialization status

Health Check Response Format

{
  "status": "healthy",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "services": {
    "database": "connected",
    "redis": "connected",
    "initialization": "completed"
  },
  "version": "0.1.0"
}

Troubleshooting

Common Deployment Issues

Build Failures

Issue: Build fails with database connection errors

Error: connect ECONNREFUSED 127.0.0.1:5432

Solution: Ensure you're using the correct build command that skips database operations:

# Use this for Vercel/production builds
npm run build:vercel

# NOT this (includes database operations)
npm run build:local

Issue: Missing environment variables during build

Error: Environment validation failed: Missing required variables

Solution: Check that build-time environment variables are set:

# Required for build
NODE_ENV=production
NEXT_PUBLIC_APP_URL=https://your-domain.com

# Optional for build (will use defaults)
DATABASE_URL=postgresql://...

Runtime Initialization Failures

Issue: Application fails to start with database errors

Error: Database initialization failed

Solution:

1. Verify database connectivity:

   # Test database connection
   psql $DATABASE_URL -c "SELECT 1;"

2. Check database permissions:

   # Ensure user has necessary permissions
   GRANT ALL PRIVILEGES ON DATABASE your_db TO your_user;

3. Verify environment variables:

   npm run env:validate:runtime

Issue: Migration failures during startup

Error: Migration failed: relation "users" already exists

Solution:

1. Check migration status:

   npx prisma migrate status

2. Reset migrations if needed:

   npx prisma migrate reset --force
   npm run db:seed

Vercel-Specific Issues

Issue: Vercel build times out

Error: Build exceeded maximum duration

Solution:

1. Optimize build command in vercel.json:

   {
     "buildCommand": "npm run build:vercel",
     "installCommand": "npm ci --legacy-peer-deps --prefer-offline"
   }

2. Check for large dependencies or unnecessary build steps

Issue: Vercel function timeout during initialization

Error: Function execution timed out

Solution:

1. Increase function timeout in vercel.json:

   {
     "functions": {
       "src/app/api/**/*.ts": {
         "maxDuration": 60
       }
     }
   }

2. Optimize database initialization for faster startup

Environment Variable Issues

Issue: Environment variables not loading

Error: Cannot read properties of undefined

Solution:

1. Check variable naming (must start with NEXT_PUBLIC_ for client-side)
2. Verify .env file location (root directory)
3. Restart development server after changes
4. For Vercel, ensure variables are set in dashboard

Issue: Database URL format errors

Error: Invalid DATABASE_URL format

Solution: Use correct PostgreSQL URL format:

# Correct format
DATABASE_URL="postgresql://username:password@hostname:port/database?schema=public"

# With SSL (required for most cloud providers)
DATABASE_URL="postgresql://username:password@hostname:port/database?schema=public&sslmode=require"

Performance Issues

Issue: Slow application startup

Warning: Initialization taking longer than expected

Solution:

1. Check database connection latency
2. Optimize database queries in initialization
3. Consider connection pooling configuration
4. Monitor resource usage

Issue: High memory usage during build

Error: JavaScript heap out of memory

Solution:

1. Increase Node.js memory limit:

   NODE_OPTIONS="--max-old-space-size=4096" npm run build

2. Optimize bundle size and dependencies

Getting Help

1. Check Logs: Always start by checking application logs

   # Local development
   npm run dev
   
   # Production logs
   docker logs container-name
   kubectl logs pod-name

2. Health Checks: Use health endpoints to diagnose issues

   curl https://your-domain.com/api/health/detailed

3. Environment Validation: Verify your configuration

   npm run env:validate:runtime

4. Database Status: Check database connectivity

   npm run db:status  # If available
   psql $DATABASE_URL -c "SELECT version();"

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• OpenAI for GPT-4 API
• Anthropic for Claude API
• ElevenLabs for TTS API
• The Next.js team for the amazing framework