WhatsApp/Signal/Formstack/admin updates

apps/bridge-migrations/README.md

@@ -0,0 +1,158 @@
+# Bridge Migrations
+
+Database migration management for the CDR Link bridge system.
+
+## Overview
+
+Bridge Migrations handles database schema versioning and migrations for all bridge-related tables using Kysely migration framework. It manages the database structure for authentication, messaging channels, webhooks, and settings.
+
+## Features
+
+- **Schema Versioning**: Track and apply database schema changes
+- **Up/Down Migrations**: Support for rolling forward and backward
+- **Type-Safe Migrations**: TypeScript-based migration files
+- **Migration History**: Track applied migrations in the database
+- **Multiple Migration Strategies**: Run all, run one, or rollback migrations
+
+## Migration Files
+
+Current migrations in order:
+
+1. **0001-add-next-auth.ts** - NextAuth.js authentication tables
+2. **0002-add-signal.ts** - Signal messenger integration
+3. **0003-add-whatsapp.ts** - WhatsApp integration
+4. **0004-add-voice.ts** - Voice/Twilio integration
+5. **0005-add-facebook.ts** - Facebook Messenger integration
+6. **0006-add-webhooks.ts** - Webhook configuration
+7. **0007-add-settings.ts** - Application settings
+8. **0008-add-user-role.ts** - User role management
+
+## Development
+
+### Prerequisites
+
+- Node.js >= 20
+- npm >= 10
+- PostgreSQL database
+- Database connection credentials
+
+### Setup
+
+```bash
+# Install dependencies
+npm install
+
+# Run all pending migrations
+npm run migrate:latest
+
+# Check migration status
+npm run migrate:list
+```
+
+### Environment Variables
+
+Required environment variables:
+
+- `DATABASE_URL` - PostgreSQL connection string
+- `DATABASE_HOST` - Database host
+- `DATABASE_NAME` - Database name
+- `DATABASE_USER` - Database username
+- `DATABASE_PASSWORD` - Database password
+
+### Available Scripts
+
+- `npm run migrate:latest` - Run all pending migrations
+- `npm run migrate:up` - Run next pending migration
+- `npm run migrate:down` - Rollback last migration
+- `npm run migrate:up:all` - Run all migrations (alias)
+- `npm run migrate:up:one` - Run one migration
+- `npm run migrate:down:all` - Rollback all migrations
+- `npm run migrate:down:one` - Rollback one migration
+- `npm run migrate:list` - List migration status
+- `npm run migrate:make <name>` - Create new migration file
+
+## Creating New Migrations
+
+To create a new migration:
+
+```bash
+npm run migrate:make add-new-feature
+```
+
+This creates a new timestamped migration file in the `migrations/` directory.
+
+Example migration structure:
+
+```typescript
+import { Kysely } from 'kysely'
+
+export async function up(db: Kysely<any>): Promise<void> {
+  await db.schema
+    .createTable('new_table')
+    .addColumn('id', 'serial', (col) => col.primaryKey())
+    .addColumn('name', 'varchar', (col) => col.notNull())
+    .addColumn('created_at', 'timestamp', (col) =>
+      col.defaultTo('now()').notNull()
+    )
+    .execute()
+}
+
+export async function down(db: Kysely<any>): Promise<void> {
+  await db.schema.dropTable('new_table').execute()
+}
+```
+
+## Database Schema
+
+### Core Tables
+
+- **users** - User accounts with roles
+- **accounts** - OAuth account connections
+- **sessions** - User sessions
+- **verification_tokens** - Email verification
+
+### Communication Tables
+
+- **bots** - Bot configurations for each service
+- **signal_messages** - Signal message history
+- **whatsapp_messages** - WhatsApp message history
+- **voice_messages** - Voice/call records
+- **facebook_messages** - Facebook message history
+
+### Configuration Tables
+
+- **webhooks** - External webhook endpoints
+- **settings** - Application settings
+
+## Best Practices
+
+1. **Test Migrations**: Always test migrations in development first
+2. **Backup Database**: Create backups before running migrations in production
+3. **Review Changes**: Review migration files before applying
+4. **Atomic Operations**: Keep migrations focused and atomic
+5. **Rollback Plan**: Ensure down() methods properly reverse changes
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Migration Failed**: Check error logs and database permissions
+2. **Locked Migrations**: Check for concurrent migration processes
+3. **Missing Tables**: Ensure all previous migrations have run
+4. **Connection Issues**: Verify DATABASE_URL and network access
+
+### Recovery
+
+If migrations fail:
+
+1. Check migration history table
+2. Manually verify database state
+3. Run specific migrations as needed
+4. Use rollback if necessary
+
+## Integration
+
+Migrations are used by:
+- **bridge-frontend** - Requires migrated schema
+- **bridge-worker** - Depends on message tables
+- **bridge-whatsapp** - Uses bot configuration tables