conversation-layer/README.md

conversation-layer

Conversation Layer System

This repository contains the services for the conversation layer, managed by Docker Compose. It includes:

• OpenWA: Handles WhatsApp communication.
• Chat UI: Provides a user interface for conversations.
• WhatsApp Router: Connects OpenWA to the Chat UI and an LLM agent.

Prerequisites

• Docker (https://www.docker.com/get-started)
• Docker Compose (usually included with Docker Desktop)

Setup and Running

1. Clone the repository:

   git clone <your-repo-url>
   cd <your-repo-directory>
   

2. Configure OpenWA:

   • Open the docker-compose.yml file.
   • Crucial: Locate the openwa service definition. You may need to replace the placeholder image image: devlikeapro/open-wa-api:latest with the specific OpenWA Docker image you intend to use.
   • Consult the documentation for your chosen OpenWA image to set necessary environment variables under services.openwa.environment. For example, you'll likely need to configure the WEBHOOK_URL that OpenWA should call. The whatsapp-router service expects this webhook at http://whatsapp-router:3001/webhook. So, an example for OpenWA's configuration might be WEBHOOK_URL=http://whatsapp-router:3001/webhook.
   • Adjust port mappings for openwa if your image uses different ports than the defaults provided (API 8080, Webhook 3000).

3. Configure Service Endpoints (if necessary):

   • Chat UI (chat-ui service): If the Chat UI needs to know the endpoint of your LLM agent, set the LLM_AGENT_URL (or similar) environment variable in docker-compose.yml under services.chat-ui.environment.
   • WhatsApp Router (whatsapp-router service): This service is pre-configured to look for OpenWA at http://openwa:8080. If your LLM agent is called by the router, set its URL via an environment variable like LLM_AGENT_URL under services.whatsapp-router.environment.

4. Build and run the services:

   docker-compose up --build
   

   • The --build flag ensures images are built if they don't exist or if Dockerfiles/contexts have changed.
   • To run in detached mode (in the background), use docker-compose up -d --build.

5. Accessing Services:

   • OpenWA API: Typically http://localhost:8080 (or the host port you mapped).
   • WhatsApp Router: http://localhost:3001 (its webhook is at http://localhost:3001/webhook, but this is for OpenWA to call internally).
   • Chat UI: http://localhost:3002.

6. Initial OpenWA Setup:

   • After starting, OpenWA will likely require you to scan a QR code with your WhatsApp mobile app to link it. Check the logs of the openwa service for the QR code or instructions:

     docker-compose logs openwa
     

   • Session data for OpenWA is stored in a Docker volume named openwa_data to persist the session across restarts.

7. Stopping the services:

   docker-compose down
   

   • To remove volumes (like openwa_data, which will clear the session), use docker-compose down -v.

Project Structure

• docker-compose.yml: Defines and configures all the services.
• chat-ui/: Contains the Dockerfile and source code for the Chat UI service.
  • Dockerfile: Instructions to build the Chat UI Docker image.
  • server.js: Placeholder Node.js/Express application.
  • package.json: Node.js project manifest.
• whatsapp-router/: Contains the Dockerfile and source code for the WhatsApp Router service.
  • Dockerfile: Instructions to build the WhatsApp Router Docker image.
  • router.js: Placeholder Node.js/Express application with a webhook.
  • package.json: Node.js project manifest.
• .gitignore: Specifies intentionally untracked files that Git should ignore.
• README.md: This file.