juanfer93/passive_crm_nestjs

1. This repo is a NestJS backend that sits between inbound messaging channels and the VIVA OS. Its core job is conversational intake: receive lead messages, maintain conversational memory, qualify the lead, extract structured fields, and publish events outward. It does not own operational execution such as calls, tasks, appointments, or follow-up execution; that boundary belongs to VIVA.

2. The application is split into three feature modules under src/features: meta-messaging-webhook, sofia-engine, and whatsapp-web. The first is the main conversational pipeline, the second is the internal event/decision bridge to VIVA, and the third is a transport adapter for WhatsApp Web that feeds the same conversation engine.

3. In meta-messaging-webhook, the architecture follows Nest’s controller → use case → domain service → infrastructure adapter layering. The presentation layer exposes the webhook controller and signature guard; the application layer contains the orchestration use cases such as accepting the webhook, verifying it, processing incoming messages, ensuring user profiles, and running due follow-ups; the domain layer holds entities, ports, and pure services; the infrastructure layer implements adapters for Mongo, Meta, OpenAI, GHL, VIVA, and background execution.

4. The inbound message flow starts at a Meta webhook request, passes through MetaSignatureGuard, then the controller hands it to accept-meta-webhook / verify-meta-webhook and the message-processing use case. Before any conversational logic runs, the system checks idempotency using a Mongo-backed message receipt store so duplicate platform deliveries do not create duplicate side effects.

5. Conversation state is persisted in MongoDB and treated as the source of truth for conversational memory. The repository includes schemas for conversation state and message receipts, plus domain entities for customer profile, dealer profile, assistant context, follow-up state, incoming messages, media content, and lead custom fields. This is the main data boundary where raw channel events become durable lead memory.

6. The AI/conversation subsystem is centered on extracting structured lead data from unstructured chat. OpenAI adapters are used for assistant replies, media analysis, and likely transcript/image understanding, while domain services normalize and derive fields such as vehicle interest, down payment, language, appointment date, and lead temperature. Dealer-specific prompts shape the conversational behavior and qualification flow.

7. The system also has a clear media-handling branch: audio is transcribed, images are analyzed, and unsupported media is marked as non-textual while the conversation continues. That keeps the qualification flow resilient across Messenger, Instagram, and WhatsApp without making media processing a hard dependency for every incoming message.

8. Qualification and profile enrichment are separated from transport concerns. Services such as dealer profile resolution, lead custom field normalization, courtesy reply generation, and reactivation/follow-up logic encapsulate business rules for turning message history into actionable lead state. The application layer coordinates these rules rather than embedding them in controllers.

9. External CRM and business-event integrations are adapters behind ports. The repo includes sinks for GHL and a composite CRM sink, plus a Viva Sofia event publisher. This means the conversation engine can sync lead updates outward without knowing whether the target is GHL, VIVA, or both.

10. The VIVA boundary is explicit and important: NestJS emits Sofia events like lead.created, lead.updated, buyer_dna_updated, appointment.created, and document.received to POST /api/sofia/event. The sofia-engine module is the inbound side of that contract on the VIVA-facing boundary, with its own controller, access guard, application services, and Mongo persistence for Sofia actions, activities, and recommendations.

11. Background work is isolated from request handling. The background infrastructure contains a Node task runner and a follow-up worker, and there is a process-due-follow-ups use case in the application layer. This separation lets the webhook path stay low-latency while scheduled or deferred actions run asynchronously.

12. WhatsApp is treated as an additional transport, not a separate brain. The whatsapp-web module provides a client service and controller so WhatsApp Web messages enter the same conversational architecture, reusing the same memory, extraction, and event-emission patterns as Meta messaging.

13. The repository is organized as a classic Nest monolith with strong internal boundaries rather than microservices. AppModule composes the feature modules, while the surrounding scripts support simulation of chat and media flows for local testing. The architecture diagram should therefore show one NestJS runtime with multiple channel ingress points, a shared conversation core, Mongo persistence, and outbound adapters to OpenAI, CRM systems, and VIVA.