morteza/TorbatYar
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
5c6a2e78cf
TorbatYar/docs/phase-handover/phase-8.md
Mortezakoohjani 10c3c43a75 feat(communication): add SMS MVP frontend with governance artifacts. 
Ship the full Communication portal (real SMS API, feature-locked future channels), BFF proxy, docs, snapshot, and phase handover.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-27 11:11:25 +03:30

156 lines
7.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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)
Reference in New Issue View Git Blame Copy Permalink