🏗️ Architecture: How should the S211 unified rich messaging architecture be s...

Date: 2026-03-13
Time: 01:21:23 UTC
Session: gspace1-211.2
Agent: backend
Confidence: 92%
Status: ✅ Documented

📋 Decision Context

Question:

How should the S211 unified rich messaging architecture be structured across backend and frontend?

Task: S211.1: Unified Rich Messaging Architecture Plan

🎯 Decision Made

Chosen:

Discriminated union RichMessage types (8 types) → RichMessageComposerService (heuristic analysis of agent output) → AdapterRegistryService (channel→adapter lookup) → per-channel ChannelAdapter (WhatsApp: Twilio Content API, Web: generative-ui JSON blocks). Frontend leverages existing GenerativeUIComponentCatalog with 5 new Angular components registered in catalog-seed.ts. No parser changes needed — MessageBodyComponent already handles generative-ui blocks.

Options Considered:

1. Option A: Channel-specific formatters (no abstraction) — rejected because it makes parity impossible and duplicates logic per channel
2. Option B (chosen): Discriminated union + adapter pattern with existing infrastructure leverage
3. Option C: LLM-driven structured output (have the LLM directly emit RichMessage JSON) — deferred to T2.1 as an upgrade, heuristic-first is safer and faster

💭 Reasoning

Three factors drove this design: (1) TwilioContentApiService already supports list pickers, cards, carousels — the WhatsApp adapter just connects the dots. (2) The frontend GenerativeUIComponentCatalog + VittoRenderComponent already dynamically render registered components from JSON blocks in chat messages — the web adapter just serializes RichMessage props into that format. (3) The adapter pattern ensures each new channel (Slack Block Kit, Discord Embeds) is a single file addition without touching the composer or existing adapters. Total new code: 13 files + 3 modified, 24 tests.

📁 Files Involved

• APIs/backend-vitto-api/src/app/engine/rich-messages/rich-message.types.ts
• APIs/backend-vitto-api/src/app/engine/adapters/channel-adapter.interface.ts
• APIs/backend-vitto-api/src/app/engine/adapters/whatsapp-channel.adapter.ts
• APIs/backend-vitto-api/src/app/engine/adapters/web-chat-channel.adapter.ts
• APIs/backend-vitto-api/src/app/engine/rich-messages/rich-message-composer.service.ts
• APIs/backend-vitto-api/src/app/engine/adapters/adapter-registry.service.ts
• libs/libs-ai/vitto-chat/src/lib/generative-ui/catalog-seed.ts

🔗 Related

• Decision ID: dev_1773364883086_k0vu8ec
• Session: 211
• Workspace: gspace1

Auto-generated by MCP Smart Consolidation