TorbatYar/docs/communication-phase-8.md

Phase 8 — Enterprise Communication Platform

Field	Value
Status	Complete (validated)
Module	communication
Version	0.8.10.1
Database	communication_db
API Port	8005
ADR	ADR-001, ADR-003, ADR-006, ADR-012

Goal

Build an independent Enterprise Communication Platform as shared infrastructure for the SuperApp.

Any tenant may activate only this service without subscribing to CRM, Loyalty, Restaurant, Sports, or other business modules.

All communication consumers interact exclusively through this service’s APIs and events. No module may talk to external providers directly.

Scope Completed (8.0–8.10) + Validation Hardening

Sub-phase	Deliverable
8.0 Foundation	Service scaffold, health/capability APIs, permissions, events, repositories, DTOs, validators
8.1 SMS Providers	Registry, priority, failover, retry, balance, sender numbers, enforced rate limits, circuit breaker
8.2 Template Engine	Templates, variables, localization, approval, versioning, preview, rendering
8.3 Dynamic Contact Sources	Manual, CSV, CRM/Loyalty/Sports/Restaurant/Marketplace/Accounting/Website/External REST — resolve only
8.4 Queue Engine	Async queue, scheduling, priority, backoff retry, DLQ, batch, claim without burning attempts on rate-limit deferral
8.5 Delivery Tracking	queued → sent → delivered / failed / expired / cancelled + timeline + provider logs
8.6 OTP Platform	Business OTP only; Core auth OTP isolated; reserved purpose rejection
8.7 Webhooks	Signature over canonical JSON body; external_id dedupe; delivery updates
8.8 Multi Channel	Common API + unified router; SMS active; stubs for email/push/whatsapp/telegram/rubika/voice
8.9 Monitoring	/health, /health/ready, /capabilities, /metrics, `/api/v1/monitoring/stats
8.10 + Validation	Idempotency (correlation_id+to_address), permission enforcement, indexes, GUID typing, enterprise test suite

Architecture

Business Modules ──API/Events──▶ Communication Service ──Provider Adapters──▶ External Gateways
                                      │
                                      ├── Provider Framework
                                      ├── Communication Router (failover)
                                      ├── Template Engine
                                      ├── Contact Resolver (dynamic)
                                      ├── Queue Engine + DLQ + Rate Limit
                                      ├── Delivery Timeline + Metrics
                                      └── OTP Platform (non-auth)

Layering: API → Services → Repositories → Models.

Database-per-service: communication_db only (ADR-001). Row-level tenant_id (ADR-003).

Provider Framework

• Protocol: ChannelProvider (send, get_balance, health_check)
• Registry maps provider_kind → adapter
• Active SMS adapters: mock, payamak
• Stub adapters for future channels (no provider-specific code outside this service)
• Disable/fail one provider → router selects next by priority; queue continues; no duplicate on correlation_id

Router Flow

1. Resolve body (raw or approved template)
2. Resolve destinations (manual and/or dynamic contact source)
3. Idempotency check on (tenant_id, correlation_id, to_address)
4. Enqueue message(s)
5. Claim by priority / available_at (Postgres SKIP LOCKED)
6. Apply channel rate limit (strictest provider limit); defer without burning attempts
7. Try providers ordered by priority (circuit-open skipped)
8. On failure → next provider (failover event)
9. Exhausted → failed; retries → DLQ

Health, Capability & Metrics

Method	Path	Notes
GET	/health	Liveness
GET	/health/ready	DB readiness
GET	/capabilities	Channels, features, contact source types, independence
GET	/metrics	Service feature summary
GET	/api/v1/providers/status	Provider health/circuit
GET	/api/v1/monitoring/stats	Message/queue/provider snapshot
GET	/api/v1/monitoring/metrics	Latency, failure rate, rate-limit deferrals

Business Rules

1. Communication is completely independent.
2. Business modules communicate only through APIs and events.
3. No provider-specific code outside this service.
4. Dynamic contact sources never duplicate business data.
5. Provider failover is automatic.
6. Communication failures must never stop business transactions.
7. Health, Capability, and Metrics APIs are mandatory.
8. Tenant-specific providers, credentials, templates, and sender numbers.
9. Audit log for every message send.
10. Auth OTP stays on Core; Communication OTP rejects reserved Core purposes.
11. Reused correlation_id + destination is idempotent (no duplicate send).

Events

Event	Meaning
communication.message.queued	Enqueued (+ channel/to/correlation)
communication.message.sent	Accepted by provider
communication.message.delivered	Delivery confirmed
communication.message.failed	Terminal send failure
communication.provider.failover	Switched provider
communication.otp.*	OTP lifecycle
communication.queue.dead_letter	DLQ
communication.webhook.received	Inbound webhook

Permissions

Enforced via require_permissions (admin roles bypass). Trees under communication.*.

APIs (selected)

Area	Prefix
Providers / senders	/api/v1/providers
Templates	/api/v1/templates
Contacts / sources	/api/v1/contacts
Messages / queue	/api/v1/messages
OTP	/api/v1/otp
Webhooks	/api/v1/webhooks
Monitoring	/api/v1/monitoring

Tests

Architecture, health/ready/security, providers/SMS/failover cascade, queue/DLQ, rate limit, idempotency, templates, dynamic contacts (incl. sports), OTP isolation, webhooks, metrics, concurrency, validators, migration, permissions, documentation — 42 passing.

Integration Boundaries

Consumer	Integration
Core / Identity	Auth OTP remains on Core; no shared OTP tables
CRM / Loyalty / Sports / Restaurant / Marketplace / Accounting	Contact resolve via HTTP APIs only; messaging via Communication APIs/events
AI / Storage / Notification	No ownership; Notification may later consume Communication events
Future modules	Pluggable via public APIs + events; no internal code changes required

Known Limitations

• Email / Push / WhatsApp / Telegram / Rubika / Voice remain architecture-ready stubs.
• Continuous Celery worker drain is optional ops work (API/process_immediately covers correctness).
• Real message bus consumers not wired (publish-only envelopes).
• Sender unique constraint is not soft-delete-aware (recreate after soft-delete may conflict).

Audit Report

See communication-phase-8-audit.md.

Completion Checklist

• Code completed (8.0–8.10)
• Enterprise validation + self-heal cycle
• Tests passed (42)
• Documentation updated
• ADR-012 referenced
• Module Registry updated
• Progress updated
• No TODO remains

Related Documents

• Progress
• Module Registry
• Audit Report
• ADR-012
• Service README