logicspike/docs

Communication

Phase 1: Discovery & User Journeys (Tenant-Facing)

1. Context & Goal

The Communication Service is a product feature offered to LogicSpike Tenants (Sellers). It empowers Sellers to bring their own communication infrastructure ("Bring Your Own Provider" - BYOP) to their LogicSpike-powered apps.

2. Actors

  1. Tenant (Seller): The LogicSpike customer. Wants to control their brand and costs.
  2. End-User: The customer of the Tenant. Needs to log in to the Tenant's app.
  3. Newsletter Service: Internal system acting on behalf of the Tenant.

3. Core User Journeys

Journey A: Seller Configures "Bring Your Own Provider" (BYOP)

Goal: A Seller wants to use their own Twilio account to get cheaper SMS rates.

  1. Trigger: Seller goes to Dashboard > Settings > Communication.
  2. Action:
    • Seller sees a list of channels: Email, SMS.
    • Seller clicks "Configure" on SMS.
    • Seller selects "Twilio" from a dropdown.
    • Seller enters Account SID, Auth Token, and From Number.
    • Seller clicks "Save & Test".
  3. System Logic:
    • Manager Service validates the credentials by sending a dummy SMS to the Seller's phone.
    • If successful, it encrypts and stores the config in TenantProviders table.
  4. Outcome: The Tenant is now "Active" on Twilio. All future OTPs for their users will route through this account.

Journey B: Seller Monitors Usage & Costs

Goal: A Seller wants to know why their bill is high.

  1. Trigger: Seller views Dashboard > Analytics > Emails.
  2. Action:
    • Seller sees a graph of "Sent Emails" vs "Delivered" vs "Opened".
    • Seller sees a breakdown of "Provider Errors" (e.g., "Twilio: Out of funds").
  3. Outcome: Seller takes action (refills Twilio credits) without contacting LogicSpike support.

Journey C: End-User Login (Transparent Delivery)

Goal: A user logs into "MyStore.com" (Powered by LogicSpike).

  1. Trigger: User verifies login via SMS.
  2. Logic:
    • Manager Service detects the User belongs to Tenant X.
    • It fetches Tenant X's Twilio config.
    • It calls Communication Service with that specific config.
  3. Outcome: User receives an SMS from MyStore's number, not a generic LogicSpike number.

Journey D: Fallback to System Default

Goal: A small Seller doesn't have a Twilio account yet.

  1. Trigger: Seller signs up and starts onboarding users.
  2. Logic:
    • Manager Service sees Tenant Y has NO configured SMS provider.
    • It attempts to use the System Default (LogicSpike's global Twilio).
    • Optional: It checks if Tenant Y has "System Fallback" enabled (Premium feature?).
  3. Outcome: User receives SMS from LogicSpike's shared number.

4. Key Requirements

  • Security: API Keys must be encrypted at rest (AES-256).
  • Validation: Never save a provider config without verifying it works (Test Connection).
  • Isolation: One tenant's bad credentials must not break the system for others.
Communication