logicspike/docs

Communication

Communication Service: Detailed Implementation Plan

Overview

We are building a Stateless Delivery Edge on Cloudflare Workers. It acts as a "Universal Adaptor" for sending Emails/SMS via tenant-configured providers.

Phase 1: Infrastructure & Skeleton (Foundation)

Goal: Get a "Hello World" Worker running with database connectivity.

  1. Initialize Worker:
    • Generate apps/communication using pnpm create cloudflare.
    • Configure wrangler.toml (Name: logicspike-communication).
    • Install dependencies: hono, zod, drizzle-orm, postgres.
  2. Database Setup (D1/Postgres):
    • Define Schema in packages/db/schema/communication.ts.
    • Tables: provider_configs, message_logs, message_events.
    • Run migrations.
  3. Internal Bindings:
    • Configure Service Binding in apps/manager/wrangler.toml.
    • Verify manager can call communication.

Phase 2: Core Domain Logic (The Brain)

Goal: Securely manage provider credentials and route messages.

  1. Encryption Utility:
    • Implement lib/crypto.ts (AES-256-GCM).
    • Add ENCRYPTION_SECRET to Cloudflare Secrets.
  2. Provider Factory:
    • Create domain/providers/factory.ts.
    • Define Provider interface.
    • Implement SystemProvider (Console/Mock for dev).
    • Implement "Resolution Logic" (Tenant Config -> Decrypt -> Instantiate).
  3. Types & VALIDATION:
    • Define Zod schemas for Content, ChannelType, ProviderConfig.

Phase 3: The Universal API (The Interface)

Goal: Expose the endpoints defined in API Spec.

  1. Hono Setup:
    • Create src/index.ts with Hono app.
    • Add Error Handling middleware.
  2. Provider Management:
    • POST /v1/providers: Validate & Encrypt config -> Save to DB.
    • GET /v1/providers: List configs (Masked secrets).
  3. Sending Logic:
    • POST /v1/send:
      1. Validate Payload (Zod).
      2. Check Idempotency (KV/DB).
      3. Resolve Provider.
      4. Execute provider.send().
      5. Log result to message_logs.

Phase 4: Provider Adapters (The Plugins)

Goal: Connect to real world services.

  1. Twilio Adapter:
    • Implement TwilioProvider class.
    • Map Content -> SMS Body.
  2. Resend/SMTP Adapter:
    • Implement EmailProvider class.
    • Handle HTML/Text parts.
  3. Failover Logic:
    • Implement retry mechanism if Primary fails.

Phase 5: Manager Integration (The Client)

Goal: Replace existing hardcoded logic in Manager Service.

  1. SDK/Client:
    • Create packages/communication-client (Optional) or just a helper in Manager.
  2. Refactor Auth:
    • Update auth/phone.ts to call communication.send({ channel: 'sms' }).
    • Update auth/email.ts to call communication.send({ channel: 'email' }).

Phase 6: Seller Dashboard (The UI)

Goal: Let Tenants configure their providers.

  1. Settings Page:
    • Create /app/settings/communication route.
  2. Forms:
    • "Add Provider" Modal (Type select, API Key inputs).
    • "Test Connection" button.
  3. Visualization:
    • List active providers.
    • Show usage logs (optional MVP).
Communication