TorbatYar/docs/phase-handover/phase-8.md

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
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
• 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; future channels via communication-roadmap.md only

Completion Sign-Off

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

Related Documents

• communication-phase-8.md
• communication-phase-8-audit.md
• communication-roadmap.md
• service-snapshots/communication.yaml
• ADR-012