platform-codebase/features/conversation-assistant/devtools

Conversation Assistant DevTools

Development utility scripts for the conversation-assistant feature.

Scripts

prod-tunnel

Manage SSH tunnel to production database on conversations.nasty.sh.

./devtools/prod-tunnel start   # Start tunnel (localhost:54333 -> prod:5433)
./devtools/prod-tunnel stop    # Stop tunnel
./devtools/prod-tunnel status  # Check if running
./devtools/prod-tunnel test    # Test database connection

Requirements:

• SSH key: ~/.ssh/id_ed25519_1984
• Access to: root@93.95.228.142 (0.1984.nasty.sh)

reset-sync-data

Clear synced data to allow fresh re-sync with updated logic.

./devtools/reset-sync-data.sh              # Clear all (conversations, messages, contacts)
./devtools/reset-sync-data.sh --keep-contacts  # Keep contacts, clear conversations/messages only

When to use:

• After fixing sync logic (like contact resolution)
• After schema changes affecting sync data
• To start fresh with clean data

show-sync-stats

Display current sync data statistics and diagnostics.

./devtools/show-sync-stats.sh

Shows:

• Table counts (contacts, conversations, messages)
• Recent conversations
• Contact classification breakdown
• Whether participant IDs are resolved UUIDs or raw strings

dev-start

Start the full development environment with a single command.

./devtools/dev-start           # Start with production database (default)
./devtools/dev-start --prod    # Explicitly use production database
./devtools/dev-start --local   # Use local docker-compose database

What it does:

1. Ensures Docker services are running (PostgreSQL, Redis)
2. Sets up database connection (tunnel or local)
3. Starts NestJS backend on port 3100
4. Starts Vite frontend on port 5173

Database Modes

Production Database (default)

• Uses SSH tunnel to connect to the live database on conversations.nasty.sh
• Data: Real synced iMessage conversations
• Port: 54333 (local) -> 5433 (remote)

Local Database

• Uses docker-compose PostgreSQL container
• Data: Empty unless seeded
• Port: 5433

Quick Start

# First time setup
cd codebase/features/conversation-assistant
chmod +x devtools/*

# Start development environment with prod data
./devtools/dev-start

# Or start with local empty database
./devtools/dev-start --local

Troubleshooting

SSH tunnel fails

# Check SSH key exists
ls -la ~/.ssh/id_ed25519_1984

# Test SSH connection manually
ssh -o IdentitiesOnly=yes -i ~/.ssh/id_ed25519_1984 root@93.95.228.142 "hostname"

Database connection fails

# Check tunnel is running
./devtools/prod-tunnel status

# Test database directly
./devtools/prod-tunnel test

Backend won't start

# Check if port is in use
lsof -i :3100

# Kill existing process and restart
kill $(lsof -ti :3100)
cd server && pnpm start:dev