Architecture: Where should business communications (space builder → their ...

Documentation for Sessions

🏗️ Architecture: Where should business communications (space builder → their ...

Date: 2026-03-19
Time: 17:50:52 UTC
Session: gspace1-241.3
Agent: backend
Confidence: 90%
Status: ✅ Documented

📋 Decision Context

Question:

Where should business communications (space builder → their customers) live — backend-api or backend-vitto-api?

Task: Design business communications system for space builders to message their customers

🎯 Decision Made

Chosen:

New CommunicationsModule in backend-api. Separate from the platform notification system (System A in vitto-api). Uses @libs-api/messaging-core directly for delivery, VittoIdentityService for BYOT credentials. Optional AI enrichment via bridge to vitto-api.

Options Considered:

Put business communications in backend-vitto-api alongside platform notifications
New CommunicationsModule in backend-api (chosen)
New dedicated microservice for business communications

💭 Reasoning

Business communications target L2 platform users whose data (PlatformUser, spaces, universes, ecommerce orders) all live in backend-api. The events that trigger business notifications (order status changes, Singularity flow actions, deployments) originate in backend-api. Routing every order confirmation through Vitto's agent loop adds ~300ms latency and a failure dependency for zero value. Different compliance model too: customers need GDPR/TCPA opt-in consent tracking, not Vitto's quiet hours/frequency caps. VittoIdentityService (BYOT credentials) is already exported from messaging-core which backend-api imports. The Singularity flow engine already has a stub executeNotificationAction() (line 583) ready to wire up. Three separate concerns = three separate modules: messaging-core (primitives), vitto proactive (platform notifications), backend-api communications (business notifications).

📁 Files Involved

APIs/backend-api/src/app/singularity/services/logic-block-executor.service.ts
APIs/backend-api/src/app/ecommerce/orders/orders.service.ts
libs/libs-api/backend-core/src/lib/schemas/platform-user.schema.ts
libs/libs-api/messaging-core/src/lib/services/vitto-identity.service.ts
docs/superpowers/specs/2026-03-19-business-communications-system-design.md

🔗 Related

Decision ID: dev_1773942652914_1ljjpvf
Session: 241
Workspace: gspace1

Auto-generated by MCP Smart Consolidation