Skip to content

Messaging and Notifications Architecture

Overview

This document describes how FarmCove's messaging system, abuse prevention mechanisms, and notification infrastructure work together to provide a secure, scalable, and user-friendly communication platform. The system enables bidirectional conversations across multiple channels (WhatsApp, SMS, web, in-app) while preventing abuse and maintaining conversation context.

Table of Contents

  1. System Components
  2. Architecture Overview
  3. Data Flow and Integration
  4. Storage Strategy
  5. Abuse Prevention Integration
  6. Real-time Capabilities
  7. Key Design Decisions

System Components

Core Tables

  1. Notifications System
  2. notification - Stores all system notifications
  3. notification_template - Reusable notification templates
  4. notification_delivery - Tracks delivery status per channel

  5. notification_preference - User communication preferences

  6. Messaging System

  7. conversation - Permanent container for user interactions
  8. conversation_instance - Time-based message groupings (8-hour windows)
  9. message - Individual messages within instances
  10. message_attachment - Media/file attachments

  11. conversation_summary - AI-generated summaries of closed instances

  12. Abuse Prevention

  13. rate_limit_config - Configurable rate limits per channel
  14. abuse_pattern - Detected abuse patterns and actions
  15. abuse_action_history - History of penalties applied

Architecture Overview

Bidirectional Communication Flow

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│                 │     │                  │     │                 │
│  Notification   │────▶│    Messaging     │◀────│     Abuse       │
│    System       │     │     System       │     │   Prevention    │
│                 │◀────│                  │────▶│                 │
└─────────────────┘     └──────────────────┘     └─────────────────┘
         │                       │                         │
         └───────────────────────┴─────────────────────────┘
                                 │
                          ┌──────▼──────┐
                          │   Supabase  │
                          │  (Storage)  │
                          └─────────────┘

Key Integration Points

  1. Notification → Conversation: Notifications can initiate conversations
  2. Message → Notification: Important messages can trigger in-app alerts
  3. Abuse Prevention: Monitors all messaging activity in real-time
  4. Shared Context: All systems reference the same user records

Data Flow and Integration

Scenario 1: Notification-Initiated Conversation

When a notification needs user response (e.g., transaction alert):

  1. Create Notification
  2. System creates notification in notification table
  3. Marks WhatsApp channel for delivery

  4. Creates delivery record in notification_delivery

  5. Start Conversation

  6. Sana (WhatsApp bot) sends notification
  7. System calls get_or_create_conversation_instance()
  8. Creates/reuses conversation in conversation table

  9. Links notification via conversation_instance_id

  10. Track Message

  11. Creates outbound message in message table
  12. Links to notification via notification_id

  13. Updates delivery status

  14. Handle Response

  15. User reply creates inbound message
  16. Abuse prevention checks rate limits
  17. Conversation continues in same instance

Scenario 2: User-Initiated Conversation

When user starts conversation directly:

  1. Receive Message
  2. WhatsApp webhook receives message
  3. System checks rate limits via check_rate_limits_and_abuse()

  4. If allowed, creates conversation structure

  5. Optional Alert

  6. Can create in-app notification for visibility
  7. Notification links to conversation instance

  8. User sees activity across all channels

  9. Continue Dialog

  10. Messages stay in same instance for 8 hours
  11. After timeout, new instance created
  12. Old instance summarized by AI

Storage Strategy

Database Tables

All data is stored in Supabase (PostgreSQL) with Row-Level Security:

  • conversation: Stores channel type, user association, status
  • conversation_instance: Groups messages in 8-hour windows
  • message: Stores content, direction, sender, timestamps
  • notification: Stores templates, content, delivery preferences
  • rate_limit_config: Defines limits per channel/user type
  • abuse_pattern: Logs detected patterns with confidence scores

Time-Based Instance Management

Conversation (permanent)
    └── Instance 1 (8 hours)
    │     ├── Message 1
    │     ├── Message 2
    │     └── ... up to 500 messages
    │
    └── Instance 2 (new 8-hour window)
          ├── Message 501
          └── ...

Benefits:

  • Prevents unbounded growth
  • Enables efficient AI summarization
  • Maintains conversation context
  • Supports quick message retrieval

Abuse Prevention Integration

Real-Time Protection

  1. Rate Limiting (Before Message Creation)
Per-Minute: 5 messages
Per-Hour: 60 messages
Per-Day: 200 messages
Per-Instance: 500 messages
  1. Pattern Detection (Every 5th Message)
  2. Spam: Identical repeated messages
  3. Flooding: <2 seconds between messages

  4. Gibberish: Short meaningless content

  5. Progressive Penalties

  6. 1st offense: Warning
  7. 2nd offense: 15-minute throttle
  8. 3rd offense: 1-hour throttle
  9. 4th offense: 24-hour suspension
  10. 5th+ offense: 7-day block

Storage in conversation Table

Rate limit data stored as JSONB in conversation:

{
  "daily_message_count": 45,
  "daily_reset_at": "2024-01-09T00:00:00Z",
  "hourly_message_count": 12,
  "hourly_reset_at": "2024-01-08T15:00:00Z",
  "is_throttled": false,
  "throttled_until": null
}

Real-time Capabilities

Enabled Tables

  • conversation - Live conversation updates
  • conversation_instance - Instance status changes
  • message - Real-time message delivery
  • notification - Instant notification alerts

Use Cases

  • Live chat in web interface
  • Message status updates (sent → delivered → read)
  • Instant abuse detection alerts
  • Real-time conversation handoff

Key Design Decisions

1. Unified User Context

  • Single user table referenced by all systems
  • Consistent preferences across channels
  • Unified permission and RLS policies

2. Channel-Agnostic Design

  • Generic fields support any channel
  • Easy to add new channels (Telegram, Email)
  • Channel-specific data in JSONB metadata

3. Notification-Conversation Bridge

  • Notifications can start conversations seamlessly
  • Messages can trigger follow-up notifications
  • Bidirectional flow with clear ownership

4. Time-Windowed Instances

  • 8-hour windows balance context and performance
  • Automatic summarization preserves history
  • Prevents infinite conversation growth

5. Proactive Abuse Prevention

  • Checks happen before resource consumption
  • Progressive penalties educate users
  • Configurable per channel and user type

6. AI-Ready Architecture

  • Summaries provide historical context
  • Pattern detection improves over time
  • Ready for future AI enhancements

Benefits

  1. Seamless Integration: Notifications and messages work together naturally
  2. Scalable Design: Time-based instances prevent performance degradation
  3. User Protection: Robust abuse prevention maintains platform quality
  4. Multi-Channel: Single architecture supports all communication channels
  5. Complete Audit Trail: Every interaction is logged and traceable
  6. Real-Time Experience: Instant updates across all interfaces
  7. Flexible Configuration: Rate limits and rules can be adjusted per channel

Future Enhancements

  1. Cross-Channel Continuity: Start on WhatsApp, continue in-app
  2. Smart Routing: AI decides best channel for each notification
  3. Behavioral Learning: Personalized rate limits based on user history
  4. Rich Media: Enhanced support for videos, documents, voice notes
  5. Conversation Intelligence: AI-powered insights and suggestions