# Communications Module — Specification

## Vision

**One platform. All channels. Unified history.**

Every message to or from a customer — email, SMS, push, in-app — goes through one system. Complete history. No silos.

## Channels

| Channel | Direction | Use Case |
|---------|-----------|----------|
| **Email** | Two-way | Fakturor, aviseringar, nyhetsbrev, support |
| **SMS** | Two-way | Uppdragsnotiser, påminnelser, verifiering |
| **Push** | Outbound | Mobilnotiser, statusuppdateringar |
| **In-App** | Two-way | Chatt, notiser, meddelanden i UI |
| **Slack/Teams** | Outbound | Integrationer, alerts till team |

## Core Principle

**Every communication is a Thread.**

```
Thread
├── Customer: Municipality of Stockholm
├── Subject: Mission #1234 — Road inspection completed
├── Messages:
│   ├── [Email] "Your mission is complete" → sent
│   ├── [SMS] "Mission done, check email for report" → sent
│   ├── [Email] "Re: Invoice question" ← received
│   └── [In-App] "Thanks, all good" ← received
└── Status: Resolved
```

## Data Model

```typescript
interface CommunicationThread {
  id: string;
  customerId: string;           // org-nr
  type: 'mission' | 'invoice' | 'support' | 'marketing' | 'system';
  subject: string;
  referenceId?: string;         // mission_123, invoice_456
  
  messages: Array<{
    id: string;
    channel: 'email' | 'sms' | 'push' | 'in-app' | 'slack';
    direction: 'inbound' | 'outbound';
    status: 'pending' | 'sent' | 'delivered' | 'read' | 'failed' | 'bounced';
    
    // Content
    subject?: string;
    body: string;               // Plain text or HTML
    bodyHtml?: string;
    
    // Recipients
    to: string[];
    cc?: string[];
    from: string;
    
    // Metadata
    sentAt?: Date;
    deliveredAt?: Date;
    readAt?: Date;
    failedAt?: Date;
    errorMessage?: string;
    
    // Provider tracking
    providerMessageId?: string;  // Mailgun, Twilio, etc.
  }>;
  
  status: 'open' | 'waiting' | 'resolved' | 'closed';
  priority: 'low' | 'normal' | 'high' | 'urgent';
  assignedTo?: string;          // User ID
  tags: string[];
  
  createdAt: Date;
  updatedAt: Date;
  resolvedAt?: Date;
}
```

## API Endpoints

```
# Threads
GET    /api/v1/communications/threads              → Lista threads (filter: customer, type, status)
POST   /api/v1/communications/threads              → Skapa ny thread
GET    /api/v1/communications/threads/:id          → Hämta thread med alla meddelanden
PUT    /api/v1/communications/threads/:id          → Uppdatera (status, assignedTo, priority)

# Messages
POST   /api/v1/communications/threads/:id/messages → Skicka meddelande
GET    /api/v1/communications/threads/:id/messages → Lista meddelanden

# Templates
GET    /api/v1/communications/templates            → Lista mallar
POST   /api/v1/communications/templates            → Skapa mall
PUT    /api/v1/communications/templates/:id        → Uppdatera mall

# Webhooks (från providers)
POST   /webhooks/mailgun                           → Mailgun events
POST   /webhooks/twilio                            → Twilio events
POST   /webhooks/sendgrid                          → SendGrid events
```

## Templates

```typescript
interface MessageTemplate {
  id: string;
  name: string;
  channel: 'email' | 'sms' | 'push';
  subject?: string;             // For email
  body: string;                 // Supports {{variables}}
  bodyHtml?: string;
  
  variables: Array<{
    name: string;
    description: string;
    required: boolean;
    defaultValue?: string;
  }>;
  
  // Usage
  usageCount: number;
  lastUsedAt?: Date;
  
  // Governance
  category: 'mission' | 'invoice' | 'support' | 'marketing' | 'system';
  language: 'sv' | 'en';
  
  createdAt: Date;
  updatedAt: Date;
}
```

### Exempel-mallar

**Mission Complete (Email)**
```
Subject: Mission {{missionId}} — {{status}}

Hi {{customerName}},

Your mission {{missionId}} has been completed.

📍 Location: {{location}}
📅 Completed: {{completedAt}}
📊 Findings: {{findingCount}}

View full report: {{reportUrl}}

---
LandveX Control Intelligence
```

**Invoice Reminder (SMS)**
```
LandveX: Invoice {{invoiceNumber}} for {{amount}} is due {{dueDate}}. 
Pay: {{paymentUrl}}
Questions? Reply or call {{supportPhone}}
```

**Budget Alert (Email)**
```
Subject: Budget Alert — {{percentUsed}}% used

Hi {{customerName}},

You have used {{percentUsed}}% of your monthly budget ({{usedAmount}} / {{budgetAmount}}).

Consider adjusting your budget or contact us to discuss.

---
LandveX
```

## Providers

### Email
- **Primary:** Mailgun (transactional)
- **Secondary:** SendGrid (marketing/bulk)
- **Backup:** AWS SES

### SMS
- **Primary:** Twilio
- **Secondary:** 46elks (Swedish)
- **Backup:** AWS SNS

### Push
- **Primary:** Firebase Cloud Messaging
- **Secondary:** OneSignal

## Implementation

### Architecture

```
┌─────────────────────────────────────────┐
│  Communications API (port 3010)         │
│  - Thread management                    │
│  - Template engine                      │
│  - Queue management                     │
└─────────────┬───────────────────────────┘
              │
    ┌─────────┼─────────┐
    │         │         │
┌───▼───┐ ┌──▼────┐ ┌──▼────┐
│Email  │ │ SMS   │ │ Push  │
│Queue  │ │ Queue │ │ Queue │
└───┬───┘ └───┬───┘ └───┬───┘
    │         │         │
┌───▼───┐ ┌──▼────┐ ┌──▼────┐
│Mailgun│ │Twilio │ │FCM    │
│SendGrid│ │46elks │ │OneSignal
└───────┘ └───────┘ └───────┘
```

### Queue System

Every message goes through a queue:

```
1. API receives send request
2. Message saved to DB (status: pending)
3. Message queued (Redis/RabbitMQ)
4. Worker picks up message
5. Send via provider
6. Update status (sent/delivered/failed)
7. Webhook updates status when provider confirms
```

### Retry Policy

| Failure | Retry | Delay |
|---------|-------|-------|
| Network error | 3x | 5s, 30s, 5min |
| Rate limit | 5x | 1min, 5min, 15min, 1h, 4h |
| Invalid address | 0x | Mark as bounced |
| Provider down | 10x | Exponential backoff |

## Integration Points

### Intelligence Lab
- Mission complete → Send notification
- Decision approved → Send report
- Urgent finding → Alert immediately

### Operations API
- Invoice generated → Send invoice email
- Budget threshold → Alert
- New user added → Welcome email

### Support System
- Ticket created → Acknowledgment
- Ticket updated → Notification
- SLA warning → Alert

## MVP (Sprint 1)

- [ ] Email sending (Mailgun)
- [ ] SMS sending (Twilio)
- [ ] Thread model
- [ ] Basic templates
- [ ] Webhook handling

## Sprint 2

- [ ] Template editor
- [ ] Queue system
- [ ] Retry logic
- [ ] Delivery tracking
- [ ] Inbound email (replies)

## Sprint 3

- [ ] Push notifications
- [ ] In-app messages
- [ ] Slack integration
- [ ] Analytics (open rates, etc.)

## Sprint 4

- [ ] A/B testing for templates
- [ ] Advanced scheduling
- [ ] Compliance (GDPR, unsubscribe)
- [ ] Multi-language

## Status

**Specification:** ✅ KLAR
**Implementation:** 🔄 EJ PÅBÖRJAD
**Dependencies:**
- Mailgun account
- Twilio account
- Redis (for queues)

---

**Nästa steg:** Konfigurera Mailgun + Twilio, bygg grundläggande API