Support Circle

The Support Circle feature enables students to build a trusted network of up to 5 support buddies who can provide help during difficult times.

Overview

Support Circle provides a comprehensive buddy support system with:

Verification workflows with email consent
User-initiated check-in requests
System-initiated wellbeing alerts
Full GDPR compliance and audit trails

Key Features

For Students

Buddy Management

Add up to 5 support buddies
Drag-and-drop to prioritize buddy order (rank 1-5)
Store contact details: name, phone, email, relationship
Remove buddies at any time

User-Initiated Requests

Tap "Ask for Check-in" on any buddy card
SMS sent immediately to verified buddy
Rate limited to 1 request per buddy per 24 hours
Trackable engagement via unique links

System-Initiated Alerts

Automated alerts when concerning patterns detected
SMS sent to top 2 ranked buddies
Triggered by configurable thresholds
Full audit trail for safety

For Support Buddies

Verification Workflow

Receive verification email when nominated
Accept or decline with informed consent
7-day token expiry
Complete privacy policy disclosure

Check-in Response

SMS with trackable link
Response options: Called, Messaged, Unavailable
Engagement logged for student's records
Opt-out option in every message

Database Schema

buddy_contacts Table

CREATE TABLE buddy_contacts (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID REFERENCES profiles(user_id) ON DELETE CASCADE,
  name VARCHAR(255) NOT NULL,
  phone VARCHAR(50) NOT NULL,
  email VARCHAR(255),
  relationship VARCHAR(100),
  notify_channel VARCHAR(20) DEFAULT 'sms',
  is_active BOOLEAN DEFAULT true,
  verified BOOLEAN DEFAULT false,
  verification_token VARCHAR(64) UNIQUE,
  verification_token_expires_at TIMESTAMP WITH TIME ZONE,
  verified_at TIMESTAMP WITH TIME ZONE,
  declined_at TIMESTAMP WITH TIME ZONE,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
  updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

buddy_verification_audit Table

CREATE TABLE buddy_verification_audit (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  buddy_contact_id UUID REFERENCES buddy_contacts(id) ON DELETE CASCADE,
  user_id UUID REFERENCES profiles(user_id) ON DELETE CASCADE,
  event_type VARCHAR(50) NOT NULL,
  ip_address INET,
  user_agent TEXT,
  metadata JSONB,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

Event types:

verification_sent
verification_resent
verification_accepted
verification_declined
verification_expired

buddy_check_in_requests Table

CREATE TABLE buddy_check_in_requests (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  buddy_contact_id UUID REFERENCES buddy_contacts(id) ON DELETE CASCADE,
  user_id UUID REFERENCES profiles(user_id) ON DELETE CASCADE,
  request_type VARCHAR(20) NOT NULL,
  trigger_reason TEXT,
  sent_at TIMESTAMP WITH TIME ZONE,
  delivery_status VARCHAR(20),
  link_clicked_at TIMESTAMP WITH TIME ZONE,
  response_received_at TIMESTAMP WITH TIME ZONE,
  response_type VARCHAR(20),
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

Request types:

user_initiated - Student pressed button
system_initiated - Automated alert

API Endpoints

POST /api/buddy/send-verification

Sends verification email to buddy after nomination.

Request:

{
  "buddyContactId": "uuid",
  "userId": "uuid"
}

Response:

{
  "success": true,
  "message": "Verification email sent"
}

Features:

Generates secure 64-character token
7-day expiry
Rate limited to 1 email per hour per buddy
Logs verification event

GET /api/buddy/verify

Handles buddy's Accept/Decline response.

Query Parameters:

token - Verification token from email
action - "accept" or "decline"
reason - Optional decline reason

Response: HTML page confirming action

SMS Strategy

Read Receipt Challenge

Standard SMS does not support true "read receipts". We track:

Delivery confirmation (AWS SNS)
Link engagement (tracking URL)
Response confirmation

Message Templates

User-Initiated Check-in:

Hi [Buddy Name], [Student Name] has asked if you could check in on them. 
They might need some support right now.

Tap here to confirm: https://mobile.mindmeasure.app/buddy/checkin/[token]

Reply STOP to opt out.

System-Initiated Alert:

Hi [Buddy Name], Mind Measure has detected concerning wellbeing patterns 
for [Student Name] over the past [X] days. They may need support.

Tap here for details: https://mobile.mindmeasure.app/buddy/alert/[token]

This is an automated safety alert. Reply STOP to opt out.

Privacy & GDPR Compliance

Data Collection

Buddy personal data: name, phone, email, relationship
Verification events: timestamps, IP addresses, user agents
Check-in requests: SMS delivery status, link clicks, responses

Consent Mechanisms

Explicit consent via "Accept" button in email
Informed consent with full disclosure
Right to withdraw via "Reply STOP"
7-day token expiry
Complete audit trail

User Rights (GDPR)

Right to access data
Right to erasure
Right to withdraw consent
Right to data portability

Rate Limiting

Verification Emails:

Maximum 1 email per hour per buddy
Maximum 3 total verification attempts

Check-in Requests:

Maximum 1 request per buddy per 24 hours
Prevents spam and maintains trust

System Alerts:

Maximum 1 alert per 72 hours per student
Escalation if no buddy response after 6 hours

Security Features

Token Security

64-character cryptographically secure tokens
URL-safe base64 encoding
7-day expiry for verification
Single-use tokens for check-in requests

Data Protection

Buddy data encrypted at rest
TLS encryption for all API calls
PII masked in logs
Field-level encryption for phone numbers

Audit Logging

All events logged to buddy_verification_audit:

verification_sent
verification_accepted
verification_declined
verification_expired

Implementation Status

Completed

Database migrations (verification + check-in tracking)
API endpoint: /api/buddy/send-verification
API endpoint: /api/buddy/verify
HTML email templates with placeholders
Verification response pages
Audit logging for GDPR compliance
Frontend UI with drag-and-drop
CRUD operations for buddy management

Phase 2 (Planned)

SMS integration via AWS SNS
Email service via AWS SES
Frontend verification status display
Check-in request implementation
System alert triggers
Response tracking page

Testing

Manual Testing Checklist

Add buddy with valid phone/email
Verification email received
Accept link marks buddy as verified
Decline link deactivates buddy
Expired link shows appropriate message
Rate limiting prevents spam
Drag-and-drop reordering works
Delete buddy removes from list
Ask for check-in button visible for verified buddies only