# Phase Handover — Communication 8 Enterprise Communication Platform

## Metadata

| Field | Value |
| --- | --- |
| Phase ID | communication-8 |
| Title | Enterprise Communication Platform (SMS-first MVP) |
| Status | Complete — **Production Ready (SMS)** |
| Service(s) | communication (`communication-service`, port 8005) |
| Commercial product | Torbat Communication |
| Version | 0.8.10.1 |
| Date | 2026-07-26 |
| ADR(s) | ADR-001, ADR-003, ADR-006, ADR-012 |

## Enterprise Phase Discovery Summary

| Item | Detail |
| --- | --- |
| Discovery Record location | [communication-phase-8.md](../communication-phase-8.md) |
| Gaps promoted & closed | Sub-phases 8.0–8.10 + validation hardening (idempotency, rate limits, permissions, metrics, OTP isolation) |
| Exclusions (future / other service) | Non-SMS channel adapters; Core auth OTP migration; Notification service consumer; Celery worker as optional ops |
| CRUD-only rejected | Yes — router, queue, failover, templates, contacts, OTP, webhooks, monitoring |

## Business Analysis Summary

| Item | Detail |
| --- | --- |
| Capabilities delivered | Independent SMS messaging platform: providers, router/failover, templates, dynamic contacts, queue/DLQ, delivery tracking, business OTP, webhooks, monitoring |
| Explicit non-goals honored | No foreign DB ownership; no provider code in business modules; auth OTP stays on Core; future channels remain stubs |

## Reusable Components

| Component | Location | Reuse notes |
| --- | --- | --- |
| ChannelProvider protocol | `app/providers/contracts.py` | Extend for future channel adapters |
| Provider registry | `app/providers/__init__.py` | Maps `provider_kind` → adapter |
| CommunicationRouter | `app/services/router.py` | Priority, failover, circuit breaker |
| QueueEngine | `app/services/queue_engine.py` | Async drain, DLQ, rate-limit deferral |
| TemplateService | `app/services/template_service.py` | Variables, locale, approval workflow |
| ContactService | `app/services/contact_service.py` | Manual, CSV, remote source resolve |
| OTPService | `app/services/otp_service.py` | Business OTP; rejects Core reserved purposes |
| WebhookService | `app/services/webhook_service.py` | HMAC + external_id dedupe |

## Public APIs

| Method | Path | Auth / Permission | Notes |
| --- | --- | --- | --- |
| GET | `/health` | public | Liveness |
| GET | `/health/ready` | public | DB readiness |
| GET | `/capabilities` | public | Channels, features, contact source types |
| GET | `/metrics` | public | Service feature summary |
| GET/POST | `/api/v1/providers` | `communication.providers.*` | Provider CRUD, status, balance, health |
| POST | `/api/v1/providers/senders` | `communication.senders.manage` | Sender numbers |
| GET/POST | `/api/v1/templates` | `communication.templates.*` | Template CRUD, approve/reject, preview |
| GET/POST | `/api/v1/contacts/*` | `communication.contacts.*` / `communication.sources.*` | Manual, CSV, sources, resolve |
| POST | `/api/v1/messages/send` | `communication.messages.send` | Idempotent on correlation_id + to_address |
| GET | `/api/v1/messages` | `communication.messages.view` | List/filter messages |
| POST | `/api/v1/messages/queue/process` | `communication.queue.manage` | Process due queue items |
| GET | `/api/v1/messages/queue/dead-letters` | `communication.queue.view` | DLQ inspection |
| POST | `/api/v1/otp/request` | `communication.otp.request` | Business OTP generate |
| POST | `/api/v1/otp/verify` | `communication.otp.verify` | Business OTP verify |
| POST | `/api/v1/webhooks/incoming` | `communication.webhooks.manage` | Provider delivery callbacks |
| GET | `/api/v1/monitoring/stats` | `communication.monitoring.view` | Message/queue/provider snapshot |
| GET | `/api/v1/monitoring/metrics` | `communication.monitoring.view` | Latency, failure rate, deferrals |

## Events

| Event type | Domain / Integration | Payload summary | Version |
| --- | --- | --- | --- |
| `communication.message.queued` | Domain | channel, to, correlation_id | 1 |
| `communication.message.sent` | Domain | provider, provider_message_id | 1 |
| `communication.message.delivered` | Domain | delivery confirmation | 1 |
| `communication.message.failed` | Domain | error, terminal failure | 1 |
| `communication.provider.failover` | Domain | from/to provider | 1 |
| `communication.otp.*` | Domain | OTP lifecycle | 1 |
| `communication.queue.dead_letter` | Domain | queue item exhausted retries | 1 |
| `communication.webhook.received` | Domain | inbound provider webhook | 1 |

## Permissions

| Permission | Routes / actions |
| --- | --- |
| `communication.providers.*` | Provider and sender management |
| `communication.templates.*` | Template CRUD and approval |
| `communication.contacts.*` / `communication.sources.*` | Contacts and dynamic sources |
| `communication.messages.*` | Send, view, cancel |
| `communication.queue.*` | Queue process and DLQ |
| `communication.otp.*` | OTP request/verify |
| `communication.webhooks.manage` | Incoming webhooks |
| `communication.monitoring.view` | Stats and metrics |

## Extension Points

| Extension point | How to extend | Forbidden uses |
| --- | --- | --- |
| ChannelProvider | Register new adapter in provider registry | Provider code in business modules |
| Contact source types | Add resolver for new remote source | Copy foreign-module rows into communication_db |
| Template variables | Extend template schema + validators | Bypass approval for production sends |
| Queue worker | Optional Celery entry via `QueueEngine.process_due` | Blocking business transactions on send failure |

## Known Limitations

- **MVP scope:** SMS active (mock + Payamak); Email/Push/WhatsApp/Telegram/Rubika/Voice are stubs — see [communication-roadmap.md](../communication-roadmap.md)
- No dedicated Celery worker (optional ops; API path is correct)
- Publish-only event envelopes (no wired bus consumers yet)
- In-process rate limiter (per-instance)
- Sender unique constraint not soft-delete-aware
- Core auth OTP remains on Core (ADR-012 neutral note)

## Migration Notes

| Item | Detail |
| --- | --- |
| Alembic revision(s) | `0001_initial`, `0002_validation_hardening` |
| Upgrade steps | `alembic upgrade head` in communication service |
| Downgrade support | Yes |
| Data backfill | None |
| Breaking changes | None (additive validation hardening) |

## Dependencies

| Dependency | Type | Required for |
| --- | --- | --- |
| onboarding-4 | Phase | Core platform baseline |
| shared-lib | Library | Events, security, exceptions |
| Payamak / mock SMS | External provider | SMS delivery |

## Next Phase Entry

Communication is **feature-complete for the current MVP scope (SMS only)**. No registered Communication phases remain.

| Field | Value |
| --- | --- |
| Recommended next phase | None (MVP complete) |
| Blockers for future channels | Explicit product decision + new phase registration when scoped |
| Entry checklist | Read this handover + [service-snapshots/communication.yaml](../service-snapshots/communication.yaml); future channels via [communication-roadmap.md](../communication-roadmap.md) only |

## Completion Sign-Off

- [x] Quality gates passed (see [communication-phase-8-audit.md](../communication-phase-8-audit.md))
- [x] Tests green (42)
- [x] Documentation updated
- [x] Service snapshot generated
- [x] Progress / registries / manifests updated
- [x] Production Ready (SMS) declared
- [x] No TODO for claimed deliverables

## Related Documents

- [communication-phase-8.md](../communication-phase-8.md)
- [communication-phase-8-audit.md](../communication-phase-8-audit.md)
- [communication-roadmap.md](../communication-roadmap.md)
- [service-snapshots/communication.yaml](../service-snapshots/communication.yaml)
- [ADR-012](../architecture/adr/ADR-012.md)