Recipient Targeting - Quick Start Implementation Guide

✅ Status: Approved & Ready to Implement

All changes have been approved by the team. Let's get started!

---

📋 What's Been Done

✅ Migration file created
✅ Type definitions created
✅ RecipientGroupsRepository created
✅ RecipientRulesRepository created
✅ Module files created
✅ Complete documentation ready

---

🚀 Your Next Steps (Do These Now)

Step 1: Run the Database Migration (5 minutes)

# Make sure you're in the project root
cd /Users/luisrangel/devLR/rpa/flowpos-workspace

# Run the migration
pnpm run migration:up
# or
npm run migration:up

Expected output:

📬 Creating Communication Recipient Targeting System...
📋 Creating communication_recipient_group table...
✅ communication_recipient_group table created
📋 Creating communication_group_member table...
✅ communication_group_member table created
... (more output)
✅ Communication Recipient Targeting System created successfully!

---

Step 2: Verify Migration Success (2 minutes)

Open your PostgreSQL client (pgAdmin, DBeaver, or psql) and run:

-- Check tables exist
SELECT table_name 
FROM information_schema.tables 
WHERE table_schema = 'public' 
  AND table_name IN (
    'communication_recipient_group',
    'communication_group_member', 
    'business_communication_recipient_rule',
    'communication_recipient_log'
  );

Expected: 4 rows returned

-- Check enums exist
SELECT typname 
FROM pg_type 
WHERE typname IN ('recipient_member_type', 'recipient_targeting_type');

Expected: 2 rows returned

-- Inspect a table structure
\d communication_recipient_group
-- or in GUI: right-click table → View Structure

---

Step 3: Test Rollback (2 minutes)

Important: Always test that your migration can roll back!

# Test rollback
pnpm run migration:down

# Verify tables are gone
# Then run migration again
pnpm run migration:up

---

Step 4: Install New Files (Already Done! ✅)

The following files have been created for you:

✅ packages/backend/database/src/types/recipient-targeting.types.ts
✅ apps/backend/src/recipient-groups/infrastructure/recipient-groups.repository.ts
✅ apps/backend/src/recipient-groups/recipient-groups.module.ts
✅ apps/backend/src/recipient-rules/infrastructure/recipient-rules.repository.ts
✅ apps/backend/src/recipient-rules/recipient-rules.module.ts

---

Step 5: Update Database Types (if needed)

If you're using kysely-codegen or a similar tool to generate types:

# Regenerate database types to include new tables
pnpm run generate:types
# or whatever your command is

Otherwise, you may need to manually add the table interfaces to database.types.ts.

---

Step 6: Test the Repositories (10 minutes)

Create a test script to verify repositories work:

Create: apps/backend/src/recipient-groups/test-repository.ts (temporary)

import { RecipientGroupsRepository } from './infrastructure/recipient-groups.repository';

// This is just for manual testing - delete after verification

async function testRepositories() {
  console.log('Testing RecipientGroupsRepository...');
  
  // You'll need to inject the database connection
  // For now, just verify the files compile without errors
}

Better approach: Just compile and verify no errors:

# From project root
pnpm run build
# or
npm run build

# If build succeeds, repositories are syntactically correct!

---

🎯 What to Do Tomorrow (Next Session)

Once migration is successful, your next tasks are:

Tomorrow Task 1: Create RecipientResolverService (Most Important!)

This is the core service that resolves rules to actual recipients.

Create: apps/backend/src/communications/application/services/recipient-resolver.service.ts

See the implementation template in the previous message or in: docs/Multi-Channel-Communication-System/recipient-targeting-implementation-checklist.md (Phase 3)

Tomorrow Task 2: Update Communications Module

Add the new modules to apps/backend/src/communications/communications.module.ts:

import { RecipientGroupsModule } from '@/recipient-groups/recipient-groups.module';
import { RecipientRulesModule } from '@/recipient-rules/recipient-rules.module';

@Module({
  imports: [
    // ... existing imports
    RecipientGroupsModule,
    RecipientRulesModule,
  ],
  // ...
})

Tomorrow Task 3: Update Low Stock Alert Handler

Replace the hardcoded recipient logic with RecipientResolverService.

See template in previous message.

---

📊 Progress Tracker

Use this to track your progress:

Week 1: Foundation

• Migration file reviewed
• Migration run in dev ← YOU ARE HERE
• Migration verified
• Rollback tested
• Types created ✅
• Repositories created ✅
• Modules created ✅
• Build successful
• RecipientResolverService created
• Low stock handler updated

Week 2: Testing

• Create test group via SQL
• Create test rules via SQL
• Trigger low stock alert
• Verify recipients resolved correctly
• Add logging to debug

Week 3: APIs & UI

• Create group management APIs
• Create rule management APIs
• Create admin UI for groups
• Create admin UI for rules
• End-to-end testing

---

🧪 Quick Test Queries (After Migration)

Once migration is done, try these queries to test:

Test 1: Create a Test Group

-- Insert test group
INSERT INTO communication_recipient_group 
  (business_id, name, description, is_active, created_by, created_at)
VALUES 
  (
    'YOUR_BUSINESS_ID_HERE',  -- Replace with actual business ID
    'Test Finance Team',
    'Testing recipient targeting system',
    true,
    'YOUR_USER_ID_HERE',       -- Replace with actual user ID
    NOW()
  )
RETURNING *;

-- Save the returned 'id' for next step

Test 2: Add Members to Group

-- Add a business user to the group
INSERT INTO communication_group_member 
  (group_id, member_type, business_user_id, is_active, added_by, added_at)
VALUES 
  (
    'GROUP_ID_FROM_STEP_1',    -- Replace with group ID from step 1
    'business_user',
    'BUSINESS_USER_ID_HERE',   -- Replace with actual business_user.id
    true,
    'YOUR_USER_ID_HERE',
    NOW()
  )
RETURNING *;

-- Add an external email to the group
INSERT INTO communication_group_member 
  (group_id, member_type, email_address, display_name, is_active, added_by, added_at)
VALUES 
  (
    'GROUP_ID_FROM_STEP_1',
    'email',
    'test@example.com',
    'Test External Contact',
    true,
    'YOUR_USER_ID_HERE',
    NOW()
  )
RETURNING *;

Test 3: Create Test Rules

-- Rule 1: Send to inventory_manager role
INSERT INTO business_communication_recipient_rule 
  (business_id, communication_type, channel, targeting_type, role_name, is_active, priority, created_by, created_at)
VALUES 
  (
    'YOUR_BUSINESS_ID_HERE',
    'low_stock_alert',
    'email',
    'role',
    'inventory_manager',
    true,
    1,
    'YOUR_USER_ID_HERE',
    NOW()
  )
RETURNING *;

-- Rule 2: Send to test group
INSERT INTO business_communication_recipient_rule 
  (business_id, communication_type, channel, targeting_type, group_id, is_active, priority, created_by, created_at)
VALUES 
  (
    'YOUR_BUSINESS_ID_HERE',
    'low_stock_alert',
    'email',
    'group',
    'GROUP_ID_FROM_STEP_1',
    true,
    2,
    'YOUR_USER_ID_HERE',
    NOW()
  )
RETURNING *;

Test 4: Query Back

-- View your test group
SELECT * FROM communication_recipient_group 
WHERE name = 'Test Finance Team';

-- View group members
SELECT 
  gm.*,
  u.full_name as user_name,
  u.email as user_email
FROM communication_group_member gm
LEFT JOIN business_user bu ON bu.id = gm.business_user_id
LEFT JOIN "user" u ON u.id = bu.user_id
WHERE gm.group_id = 'GROUP_ID_FROM_STEP_1';

-- View rules
SELECT * FROM business_communication_recipient_rule
WHERE business_id = 'YOUR_BUSINESS_ID_HERE'
  AND communication_type = 'low_stock_alert';

---

🆘 Troubleshooting

Error: "relation does not exist"

Problem: Migration didn't run successfully
Solution:

# Check migration status
pnpm run migration:status

# If needed, run migration again
pnpm run migration:up

Error: "type does not exist"

Problem: Enum types not created
Solution: Check migration logs, enums should be created before tables

Error: Build fails with "Cannot find module"

Problem: Type imports are wrong
Solution: Check that database.types.ts exports the new table types

Error: Foreign key constraint violation

Problem: Trying to reference non-existent records
Solution: Make sure you're using valid IDs from existing records (business, user, etc.)

---

📞 Need Help?

If you get stuck:

1. Check the migration logs - Did it complete successfully?
2. Verify table structure - Use \d table_name in psql
3. Check documentation - Detailed info in recipient-targeting-implementation-checklist.md
4. Test queries - Use the SQL queries above to verify data

---

✅ Success Checklist (Today)

After completing today's tasks, you should have:

• Migration successfully run
• 4 new tables visible in database
• 2 new enum types created
• Build completes without errors
• Test group created via SQL (optional)
• Test rules created via SQL (optional)

Once these are done, you're ready for Phase 2: RecipientResolverService! 🎉

---

📅 Timeline

• Today (Day 1): Run migration, verify success ← YOU ARE HERE
• Tomorrow (Day 2-3): Create RecipientResolverService
• Day 4-5: Update low stock handler, test end-to-end
• Week 2: Create APIs
• Week 3: Create admin UI

---

🎯 Your Command to Run Right Now

cd /Users/luisrangel/devLR/rpa/flowpos-workspace && pnpm run migration:up

That's it! Run this command and let me know if you see any errors! 🚀