docs/agent/implementation-notes/USER_INVITATION_IMPLEMENTATION_PLAN.md

User Invitation System - Implementation Plan

Overview

Implement a secure user invitation system that allows platform admins to invite users to organizations (clients/contractors) via WhatsApp (primary) or Email (fallback). Users are created in Supabase Auth ONLY after accepting the invitation.

---

1. Database Schema Changes

Important Note on User Status

The existing user_status enum (invited, pending_setup, active, suspended) is KEPT.

• user_invitations table tracks PRE-acceptance state (before user exists)
• users.status tracks POST-acceptance state (after user is created)
• Flow: Invitation sent → User accepts → User created with status active → User can be suspended later

New Table: user_invitations

CREATE TYPE invitation_status AS ENUM (
    'pending',
    'accepted',
    'expired',
    'cancelled'
);

CREATE TYPE invitation_method AS ENUM (
    'whatsapp',
    'email',
    'both'
);

CREATE TABLE user_invitations (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    
    -- Invitation Details
    email TEXT NOT NULL,
    phone TEXT,
    invited_role app_role NOT NULL,
    
    -- Organization Link (one must be set based on role)
    client_id UUID REFERENCES clients(id) ON DELETE CASCADE,
    contractor_id UUID REFERENCES contractors(id) ON DELETE CASCADE,
    
    -- Invitation Token & Status
    token TEXT NOT NULL UNIQUE,
    status invitation_status DEFAULT 'pending',
    invitation_method invitation_method DEFAULT 'whatsapp',
    
    -- Lifecycle
    invited_by_user_id UUID NOT NULL REFERENCES users(id) ON DELETE RESTRICT,
    invited_at TIMESTAMP WITH TIME ZONE DEFAULT timezone('utc'::text, now()),
    expires_at TIMESTAMP WITH TIME ZONE NOT NULL,
    accepted_at TIMESTAMP WITH TIME ZONE,
    
    -- Delivery Tracking
    whatsapp_sent BOOLEAN DEFAULT FALSE,
    whatsapp_sent_at TIMESTAMP WITH TIME ZONE,
    email_sent BOOLEAN DEFAULT FALSE,
    email_sent_at TIMESTAMP WITH TIME ZONE,
    
    -- Metadata
    invitation_metadata JSONB DEFAULT '{}',
    created_at TIMESTAMP WITH TIME ZONE DEFAULT timezone('utc'::text, now()),
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT timezone('utc'::text, now()),
    
    -- Constraints
    CONSTRAINT chk_invitation_org_link CHECK (
        (client_id IS NOT NULL AND contractor_id IS NULL) OR
        (client_id IS NULL AND contractor_id IS NOT NULL) OR
        (invited_role = 'platform_admin' AND client_id IS NULL AND contractor_id IS NULL)
    ),
    CONSTRAINT chk_invitation_contact CHECK (
        email IS NOT NULL OR phone IS NOT NULL
    )
);

-- Indexes
CREATE INDEX idx_invitations_token ON user_invitations(token) WHERE status = 'pending';
CREATE INDEX idx_invitations_email ON user_invitations(email, status);
CREATE INDEX idx_invitations_status ON user_invitations(status, expires_at);
CREATE INDEX idx_invitations_client ON user_invitations(client_id) WHERE client_id IS NOT NULL;
CREATE INDEX idx_invitations_contractor ON user_invitations(contractor_id) WHERE contractor_id IS NOT NULL;

-- Prevent duplicate pending invitations
CREATE UNIQUE INDEX idx_invitations_unique_pending ON user_invitations(email, client_id, contractor_id) 
WHERE status = 'pending';

COMMENT ON TABLE user_invitations IS 'Tracks user invitations before Supabase Auth account creation';

---

2. Environment Variables

Add to .env:

# Base URL for invitation links
BASE_URL=https://swiftops.atomio.tech

# Invitation Configuration
INVITATION_TOKEN_EXPIRY_HOURS=72

# Notification Services (already exist)
RESEND_API_KEY=re_xxx
WASENDER_API_KEY=xxx
WASENDER_PHONE_NUMBER=+254xxx

---

3. Project Structure

src/app/
├── services/
│   ├── __init__.py
│   ├── invitation_service.py      # Core invitation logic
│   ├── notification_service.py    # WhatsApp/Email delivery
│   └── token_service.py           # Token generation/validation
├── templates/
│   ├── emails/
│   │   ├── base.html              # Base email template
│   │   ├── invitation.html        # User invitation email
│   │   └── invitation_reminder.html
│   └── whatsapp/
│       ├── invitation.txt         # WhatsApp invitation message
│       └── invitation_reminder.txt
├── models/
│   └── invitation.py              # Invitation model
├── schemas/
│   └── invitation.py              # Invitation schemas
└── api/v1/
    └── invitations.py             # Invitation endpoints

---

4. Implementation Steps

Step 1: Database Migration

• Create migration file for user_invitations table
• Add invitation_status and invitation_method enums
• Run migration

Step 2: Models & Schemas

• Create src/app/models/invitation.py
• Create src/app/schemas/invitation.py with:
  • InvitationCreate
  • InvitationResponse
  • InvitationAccept
  • InvitationValidate

Step 3: Core Services

A. Token Service (src/app/services/token_service.py)

• generate_invitation_token() - Secure random token (32 chars)
• validate_invitation_token(token) - Check validity & expiry
• invalidate_token(token) - Mark as used/expired

B. Notification Service (src/app/services/notification_service.py)

• send_whatsapp_invitation(phone, name, invitation_url) - WaSender integration
• send_email_invitation(email, name, invitation_url) - Resend integration
• send_invitation(invitation, method) - Smart routing (WhatsApp → Email fallback)
• Template rendering with Jinja2

C. Invitation Service (src/app/services/invitation_service.py)

• create_invitation(email, phone, role, org_id, invited_by, method)
• validate_invitation(token) - Check token validity
• accept_invitation(token, user_data) - Create Supabase user + local profile
• cancel_invitation(invitation_id) - Cancel pending invitation
• resend_invitation(invitation_id) - Resend notification
• cleanup_expired_invitations() - Background job

Step 4: Email Templates

src/app/templates/emails/base.html

• Create responsive HTML base template
• Include SwiftOps branding
• Header, footer, styling

src/app/templates/emails/invitation.html

• Personalized greeting
• Organization name
• Role information
• CTA button with invitation URL
• Expiry notice
• Support contact

Step 5: WhatsApp Templates

src/app/templates/whatsapp/invitation.txt

Hi {{name}},

You've been invited to join {{organization_name}} on SwiftOps as a {{role}}.

Click here to accept: {{invitation_url}}

This invitation expires in {{expiry_hours}} hours.

Need help? Contact support@atomio.tech

Step 6: API Endpoints

src/app/api/v1/invitations.py

• POST /invitations - Create invitation (platform_admin, client_admin, contractor_admin)
• GET /invitations - List invitations (filtered by org)
• GET /invitations/{id} - Get invitation details
• POST /invitations/{id}/resend - Resend invitation
• DELETE /invitations/{id} - Cancel invitation
• POST /invitations/validate - Validate token (public endpoint)
• POST /invitations/accept - Accept invitation & create user (public endpoint)

Step 7: Update Existing Endpoints

src/app/api/v1/clients.py

• Add existence check in create_client()
• Return existing client if found (with flag already_exists: true)

src/app/api/v1/contractors.py

• Add existence check in create_contractor()
• Return existing contractor if found (with flag already_exists: true)

src/app/api/v1/auth.py

• Remove self-registration endpoint OR restrict to invitation-only
• Update register() to require invitation token
• Link new user to invitation record

Step 8: Authorization Rules

Who can invite whom:

• platform_admin → Can invite anyone to any organization
• client_admin → Can invite users to their client organization only
• contractor_admin → Can invite users to their contractor organization only
• Other roles → Cannot invite users

Validation:

• Check inviter has permission for target organization
• Validate role is appropriate for organization type
• Prevent duplicate pending invitations

Step 9: Frontend Integration Points

Invitation Flow:

1. User receives WhatsApp/Email with link: https://swiftops.atomio.tech/accept-invitation?token=xxx
2. Frontend validates token via POST /invitations/validate
3. Shows registration form pre-filled with email/phone
4. User completes profile (name, password)
5. Frontend submits to POST /invitations/accept
6. Backend creates Supabase user + local profile
7. Returns auth token
8. User is logged in

---

5. Security Considerations

• Tokens are cryptographically secure (secrets.token_urlsafe)
• Tokens expire after 72 hours (configurable)
• Rate limiting on invitation endpoints
• Validate email/phone format
• Prevent invitation spam (max 3 pending per email)
• Log all invitation activities
• HTTPS only for invitation URLs

---

6. Testing Checklist

• Unit tests for token generation/validation
• Integration tests for invitation flow
• Test WhatsApp delivery (WaSender)
• Test email delivery (Resend)
• Test fallback mechanism (WhatsApp → Email)
• Test expiry handling
• Test duplicate invitation prevention
• Test authorization rules
• Test Supabase user creation on acceptance

---

7. Background Jobs (Future Enhancement)

• Cleanup expired invitations (daily cron)
• Send reminder for pending invitations (24h before expiry)
• Generate invitation analytics

---

8. API Response Examples

Create Invitation

POST /api/v1/invitations
{
  "email": "john@example.com",
  "phone": "+254712345678",
  "role": "field_agent",
  "contractor_id": "uuid",
  "invitation_method": "whatsapp"
}

Response:
{
  "id": "uuid",
  "email": "john@example.com",
  "status": "pending",
  "invitation_url": "https://swiftops.atomio.tech/accept-invitation?token=xxx",
  "expires_at": "2025-11-19T12:00:00Z",
  "whatsapp_sent": true,
  "email_sent": false
}

Accept Invitation

POST /api/v1/invitations/accept
{
  "token": "xxx",
  "first_name": "John",
  "last_name": "Doe",
  "password": "SecurePass123!"
}

Response:
{
  "access_token": "jwt_token",
  "token_type": "bearer",
  "user": {
    "id": "uuid",
    "email": "john@example.com",
    "full_name": "John Doe",
    "role": "field_agent",
    "contractor_id": "uuid"
  }
}

---

9. Implementation Order

1. Phase 1: Foundation (Day 1)

   • Database migration
   • Models & schemas
   • Token service

2. Phase 2: Core Logic (Day 2)

   • Invitation service
   • Notification service
   • Templates (email + WhatsApp)

3. Phase 3: API (Day 3)

   • Invitation endpoints
   • Update client/contractor endpoints
   • Authorization logic

4. Phase 4: Integration (Day 4)

   • Update auth flow
   • Frontend integration
   • Testing

5. Phase 5: Polish (Day 5)

   • Error handling
   • Logging
   • Documentation

---

10. Success Criteria

✅ Platform admin can invite users to any organization ✅ Org admins can invite users to their organization ✅ Invitations sent via WhatsApp (primary) or Email (fallback) ✅ Secure token-based invitation links ✅ Users created in Supabase ONLY after acceptance ✅ Duplicate invitation prevention ✅ Expiry handling ✅ Audit trail for all invitations ✅ Client/contractor existence checks before creation

---

Notes

• WhatsApp Priority: Default to WhatsApp to conserve Resend credits
• Fallback Logic: If WhatsApp fails, automatically try email
• Token Security: Use secrets.token_urlsafe(32) for tokens
• Expiry: 72 hours default, configurable via env
• Email Domain: swiftops@atomio.tech (configured in Resend)
• Base URL: https://swiftops.atomio.tech (from env)