← back to Dear Bubbe Nextjs

docs/SYSTEM.md

374 lines

# SYSTEM.md - Dear Bubbe System Configuration

## Project Overview
**Project Name**: Dear Bubbe NextJS  
**Version**: 0.1.0  
**Framework**: Next.js 16.0.3 with React 19.2.0  
**Location**: `/root/Projects/dear-bubbe-nextjs`  
**Server IP**: 45.61.58.125  
**Platform**: Kamatera VPS running Ubuntu (Linux 5.4.0-216-generic)

## Service Information
**Primary Port**: 3011 (Next.js server)  
**URL**: http://45.61.58.125:3011  
**Process Manager**: PM2 (process name: bubbe-ai)  
**Status**: Online and running

## Project Structure
```
/root/Projects/dear-bubbe-nextjs/
├── app/                    # Next.js app directory
│   ├── api/               # API routes
│   ├── page.tsx           # Main page component
│   ├── layout.tsx         # Root layout
│   └── globals.css        # Global styles
├── docs/                  # Private documentation
│   ├── PERSONALITY.md     # Bubbe personality configuration
│   └── SYSTEM.md          # System configuration (this file)
├── public/                # Static assets
│   └── bubbe.png         # Bubbe avatar
├── tests/                 # Test suites
│   └── antisemitism-test-suite.js  # Anti-semitism detection tests
├── node_modules/          # Dependencies
├── .next/                 # Build output
└── Configuration files
```

## Key Dependencies
- **@anthropic-ai/sdk**: ^0.69.0 - Claude AI integration
- **axios**: ^1.13.2 - HTTP client
- **puppeteer**: ^24.30.0 - Browser automation
- **next**: 16.0.3 - Next.js framework
- **react**: 19.2.0 - React library
- **dotenv**: ^17.2.3 - Environment variable management

## Environment Variables
```
ELEVENLABS_API_KEY=<REDACTED — see secrets-manager>
ANTHROPIC_API_KEY=<REDACTED — see secrets-manager>
```

## Available Scripts
```bash
npm run dev          # Development server on port 3011
npm run build        # Build for production
npm run start        # Start production server on port 3011
npm run lint         # Run ESLint
npm run test:antisemitism  # Run anti-semitism test suite
npm run purge-cache  # Clear cache (shell script)
npm run purge-puppeteer  # Clear Puppeteer cache
```

## PM2 Configuration
```javascript
// ecosystem.config.js
module.exports = {
  apps: [{
    name: 'bubbe',
    script: 'npm',
    args: 'start',
    env: {
      PORT: 3011,
      NODE_ENV: 'production',
      ELEVENLABS_API_KEY: '...',
      ANTHROPIC_API_KEY: '...'
    }
  }]
}
```

## API Endpoints
- `/api/chat` - Main chat interface endpoint
- `/api/bubbe-voice` - ElevenLabs voice synthesis endpoint
- `/api/news` - News aggregation endpoint
- `/api/upload-bubbe` - File upload endpoint
- `/api/claude` - Claude AI interaction (deprecated, use /api/chat)
- `/api/webhook` - Webhook handling for external integrations

## Live Data Integration (100% FREE APIs)

### Weather API (Open-Meteo)
- **Status**: ✅ LIVE AND WORKING
- **API**: https://open-meteo.com/ (NO API KEY REQUIRED)
- **Features**:
  - Current weather conditions
  - 3-day forecast
  - Temperature (F and C)
  - Humidity, wind speed
  - Location-based (uses lat/lon from IP geolocation)

### News APIs (Aggregated from FREE sources)
1. **Reddit r/news** - Top headlines from Reddit RSS
2. **Reddit r/worldnews** - International news
3. **HackerNews** - Tech and startup news
4. **NPR News RSS** - Hourly news updates
5. **Local RSS Feeds** - 20+ major US cities supported

**Supported Local News Cities:**
- New York (NYTimes + r/nyc)
- Los Angeles (LA Times + r/losangeles)
- Chicago (Tribune + r/chicago)
- Houston, Phoenix, Philadelphia, San Antonio
- San Diego, Dallas, San Jose, Austin
- Plus 10+ more major cities

### Sports APIs (FREE)
1. **MLB StatsAPI** - Official MLB stats and scores
2. **Balldontlie.io** - Free NBA scores and stats

### RSS Feed Caching System
- **Cache Duration**: 20 minutes for news/sports, 30 minutes for NPR
- **Auto-Refresh**: Background tasks run automatically
- **Benefits**: Reduced API calls, faster responses

### Detection Patterns
- **Weather**: `/\b(weather|temperature|forecast|rain|snow|storm|hot|cold|sunny|cloudy)\b/i`
- **News**: `/\b(news|headline|breaking|politics|election|president|congress)\b/i`
- **Sports**: `/\b(game|score|sports|team|nba|nfl|mlb|nhl|soccer|football|basketball|baseball|hockey)\b/i`

## Anti-Semitism Detection System

### Detection Rules (from antisemitism_rules.json)

#### High Severity (Immediate Block)
- **Triple Parentheses**: Pattern `\(\(\(.+?\)\)\)` - Used to identify Jews hostilely
- **ZOG Acronym**: Pattern `\bZOG\b` - Extremist conspiracy acronym
- **Jewish Control Conspiracy**: Pattern `\bjews?\s+(run|control|own|dominate)\s+\w+`
- **Jewish Conspiracy Phrases**: Pattern `\b(jewish|zionist)\s+(conspiracy|agenda|plot|cabal|takeover)\b`
- **Holocaust Denial**: Pattern `(holocaust)\s+(is|was)\s+(a\s+)?(myth|hoax|lie|fake)`

#### Medium Severity (Review)
- **Globalist Dogwhistles**: Terms like "globalist elite", "international bankers", "cosmopolitan elites"
- **White Supremacist Numbers**: 14, 18, 88, 109, 110 (when in context)

#### External Sources
- ADL Hate Symbols Database
- SPLC Extremist Files Glossary

### Response Protocol
When anti-semitic content is detected:
1. **Immediate threat response with IP tracking**
2. **Stern warning message**: "I see EXACTLY who you are and where you are..."
3. **Log incident with userId, IP, location, timestamp**
4. **Block further interaction from user**
5. **Display zero-tolerance message**

### Security Features
1. **Anti-Semitism Detection**: 
   - Immediate threat response with IP tracking
   - Logging and blocking of offenders
   - Zero tolerance policy implementation

2. **Environment Protection**:
   - API keys stored in `.env.local`
   - Secure PM2 environment configuration

## Testing & Monitoring

### Test Files
- `antisemitism-test-suite.js` - Comprehensive anti-semitism detection tests
- `comprehensive-voice-test.js` - Voice feature testing
- `auto-test-voice.sh` - Automated voice testing script
- `monitor-bubbe.sh` - Service monitoring script

### Monitoring
- PM2 monitoring: `pm2 monit bubbe`
- Logs: `pm2 logs bubbe`
- Status check: `pm2 status | grep bubbe`

## Related Projects & Services

### DW-Agents System
Multiple agent services running on various ports:
- Master Hub (port 9900)
- Skills Manager (port 9894)
- Control Panel (port 7200)
- Executive suite (CEO, CFO, COO on ports 7120-7123)
- And 20+ other specialized agents

### Important Ports in Use
- 3011: Dear Bubbe NextJS
- 7xxx range: Various agent dashboards
- 8xxx range: Service endpoints
- 9xxx range: Agent control systems

## Maintenance Commands

### Service Management
```bash
# Restart Bubbe
pm2 restart bubbe

# Check status
pm2 status bubbe

# View logs
pm2 logs bubbe --lines 100

# Reload with zero downtime
pm2 reload bubbe
```

### Cache Management
```bash
# Clear Next.js cache
rm -rf .next

# Clear Puppeteer cache
./purge-cache.sh

# Rebuild project
npm run build && pm2 restart bubbe
```

### Testing
```bash
# Test anti-semitism detection
npm run test:antisemitism

# Test voice features
node comprehensive-voice-test.js

# Check service health
curl http://localhost:3011
```

## Troubleshooting

### Common Issues
1. **Port conflicts**: Check with `lsof -ti:3011`
2. **PM2 crashes**: Check logs with `pm2 logs bubbe --err`
3. **Build failures**: Clear cache and rebuild
4. **API issues**: Verify environment variables in `.env.local`

### Log Locations
- PM2 logs: `~/.pm2/logs/`
- Application logs: `monitor.log`
- Test reports: `tests/antisemitism-test-report.html`

## Development Notes

### Code Style
- TypeScript with strict mode enabled
- React functional components
- Tailwind CSS for styling (v4)
- ESLint for code quality

### Build Configuration
- TypeScript target: ES2017
- Module system: ESNext
- JSX: react-jsx
- Strict mode: enabled

## User Onboarding Flow

### 5-Step Interactive Onboarding
1. **Breaking News Display**: Shows 3 breaking news headlines at top of chat
2. **Location Permission**: Request for local news/weather (IP-based)
3. **Content Preferences**: User selects weather, news, sports, advice, or custom
4. **Yiddish Translation Toggle**: Option to show translations like "meshugana (crazy)"
5. **Command Help**: Shows available commands with `:list`

### Available Commands
- `:list` - Show all available commands
- `/bubbe` - Switch to Bubbe Mode (sarcastic grandma)
- `/meshugana` - Switch to Meshugana Mode (crazy grandpa)
- `/comedian` - Switch to Comedian Mode (stand-up comedy)
- `:yiddish on` - Enable Yiddish translations
- `:yiddish off` - Disable Yiddish translations

## Multiple Personality Modes

### Bubbe Mode (Default) 🥯
- **SARCASTIC** Jewish grandma
- Biting wit with Yiddish
- Brutal food metaphors
- Guilt-trip wisdom
- "She loves you but won't sugarcoat it!"

### Meshugana Mode 🤪
- Crazy old grandpa personality
- Thinks YOU'RE meshuga (crazy), not him
- "What are you, meshuga?!"
- Calls you nuts while giving advice

### Comedian Mode 🎤
- Stand-up comedy style
- Observational humor
- Jerry Seinfeld-esque delivery

## SMS Integration Features
- **SMS-optimized**: Automatically generates responses under 320 characters
- **Twilio integration**: Professional SMS delivery (when configured)
- **Cron scheduling**: Daily automated sends at subscriber's preferred time
- **STOP/START handling**: Automatic subscription management
- **Smart selection**: Avoids repeats, ensures variety

## User Memory System

### Memory Persistence
- All conversations are saved to markdown files in `/user-memories/`
- Each user has their own `.md` file tracking:
  - Complete profile data
  - Conversation history (last 50 messages)
  - Topics discussed
  - Location information
  - Preferences and settings
  - Important relationships and dates

### Dynamic Response Generation
- Responses are now UNIQUE and non-repetitive
- System tracks last 15 responses to avoid repetition
- Varied Yiddish terms and insults
- Different relatives mentioned each time
- Creative guilt trips that don't repeat
- Personalized based on conversation history

### Login Gate Features
- 3 free messages before login required
- After login, full profile collection begins
- All data persisted across sessions
- Memory recalls previous conversations
- Location-based content (weather, news)

## Quick Reference

### Access URLs
- **Production**: http://45.61.58.125:3011
- **Domain**: https://www.bubbe.ai (if configured)
- **Local Dev**: http://localhost:3011
- **Original Version**: Port 7800 (B_Version_1)

### Key Files
- Main app: `app/page.tsx`
- API routes: `app/api/` directory
- PM2 config: `ecosystem.config.js`
- Environment: `.env.local`
- Personality: `/docs/PERSONALITY.md`
- System Config: `/docs/SYSTEM.md` (this file)
- Anti-semitism rules: `/root/Projects/B_Version_1/moderation/antisemitism_rules.json`

### Critical Features to Maintain
1. **Anti-semitism detection MUST work at all times**
2. **Voice synthesis integration with ElevenLabs**
3. **RUDE, INVASIVE personality - NOT sweet or nice**
4. **Mobile responsiveness with proper viewport settings**
5. **Zero-tolerance security protocols**
6. **Local sports/news prioritization**
7. **Free API usage (no paid keys required)**

### Response Requirements
- Maximum 280-320 characters (SMS/mobile optimized)
- MUST follow 3-part structure: INSULT → ANSWER → INVASIVE QUESTION
- Include location context when applicable
- Use Yiddish terms liberally
- Be BRUTALLY HONEST and JUDGMENTAL
- **NO REPETITIVE RESPONSES** - Each message must be unique and creative
- **NEVER mention visit counts** - Focus on life failures instead

---

**Last Updated**: December 1, 2025  
**Maintained By**: Claude AI Assistant  
**Server Location**: Kamatera VPS (45.61.58.125)
**Original Author**: DW-Agents Team