Lunelo

A production-ready multi-agent AI customer support system for e-commerce, built with NestJS microservices architecture. Features WhatsApp integration, intelligent conversation management, and multi-tenant support.

🏗️ Architecture

┌─────────────┐    HTTP/REST
│   Client    │ ──────────► ┌──────────────┐
│ (WhatsApp)  │             │   Gateway    │
└─────────────┘             │  (Port 3000) │
                            └──────┬───────┘
                                   │ RPC via Consul
                                   ▼
                            ┌──────────────┐
                            │ Orchestrator │
                            │ (Port 3002)  │
                            │  WhatsApp    │
                            │  AI Agents   │
                            └──────┬───────┘
                                   │
                    ┌──────────────┼──────────────┐
                    │              │              │
                    ▼              ▼              ▼
            ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
            │   Tenants   │ │Conversations│ │   Agent     │
            │ (Port 3001) │ │ (Port 3004) │ │  Package    │
            │ Multi-tenant│ │  Messaging  │ │  (VoltAI)   │
            │  Management │ │  pgvector   │ │             │
            └─────────────┘ └─────────────┘ └─────────────┘

Core Components

API Gateway: HTTP entry point with Swagger documentation and health monitoring
Orchestrator Service: Processes WhatsApp webhooks, manages conversations, and orchestrates multi-agent AI interactions
Tenants Service: Multi-tenant management with store configuration, channels, and commerce backend integration
Conversations Service: Chat and messaging management with semantic search capabilities using pgvector
Agent Package: Multi-agent AI system powered by VoltAI with specialized agents (Shopping, Logistics, Customer Support, Linguist)

Infrastructure Services

Consul: Service discovery and health monitoring
PostgreSQL: Two databases (Tenants and Conversations)
Redis: Caching and queue management
Bull Board: Queue monitoring dashboard

🚀 Quick Start

Prerequisites

Node.js >= 18
pnpm package manager
Docker and Docker Compose (for infrastructure services)

Automated Setup

# Clone the repository
git clone <repository>
cd lunelo

# Run setup script
./setup.sh

Manual Setup

Option 1: Full Docker Environment

# Install dependencies
pnpm install

# Build all packages
pnpm run build

# Start complete environment (all services + infrastructure)
docker-compose --profile full up --build

Option 2: Local Development

# Install dependencies
pnpm install

# Build all packages
pnpm run build

# Terminal 1: Start infrastructure services
docker-compose --profile consul --profile databases up

# Terminal 2: Start all microservices
pnpm run dev

# Or start individual services:
pnpm run dev --filter=@lunelo/gateway
pnpm run dev --filter=@lunelo/orchestrator
pnpm run dev --filter=@lunelo/tenants
pnpm run dev --filter=@lunelo/conversations

📊 Services Overview

API Gateway (Port 3000)

Role: HTTP entry point and routing hub

Features:

Swagger API documentation (/api)
Aggregated health checks (/health)
Bull Board queue monitoring
CORS configuration
Request validation

Endpoints:

GET /health - Service health check
GET /api - Swagger documentation
GET /webhook/health - Gateway health

Orchestrator Service (Port 3002)

Role: Business logic coordinator and AI agent orchestrator

Features:

WhatsApp webhook processing (Twilio integration)
Multi-agent AI system orchestration
Queue-based message processing
Conversation management
Event-driven architecture

Key Components:

WhatsApp webhook handler
Multi-agent AI supervisor (VoltAI)
Queue listeners for async processing
RPC client for service communication

Tenants Service (Port 3001)

Role: Multi-tenant management

Features:

Tenant/store configuration
Channel management (WhatsApp, Instagram, Telegram, SMS, Webchat)
Commerce backend integration (WooCommerce, Shopify, Medusa, Spree, Custom)
User and role management
Store metadata and persona configuration

Database: PostgreSQL with Prisma ORM

Conversations Service (Port 3004)

Role: Chat and messaging management

Features:

Conversation lifecycle management
Message storage and retrieval
Semantic search with pgvector
Customer management
Agent action tracking
Semantic memory storage

Database: PostgreSQL with pgvector extension

🤖 Multi-Agent AI System

The system uses a sophisticated multi-agent architecture powered by VoltAI:

Agent Hierarchy

Supervisor Agent: Orchestrates all interactions and delegates to specialized agents
Linguist Agent: Humanizes all user-facing responses (mandatory for all outputs)
Shopping Agent: Handles product search, cart management, and order creation
Logistics Agent: Manages order tracking, shipping, and delivery status
Customer Support Agent: Handles returns, refunds, and post-purchase support

Agent Capabilities

Natural Language Understanding: Context-aware conversation handling
Tool Integration: Access to store backends, product catalogs, and order systems
Memory Management: Persistent conversation context
Parallel Execution: Simultaneous agent calls for faster responses
Threaded Replies: Understanding of message threading and context

🔧 Service Discovery with Consul

Key Features

Dynamic Service Registration: Services auto-register on startup
Health Monitoring: TTL-based health checks (30s intervals)
Load Balancing: Round-robin across healthy instances
Auto Scaling: Start multiple instances without code changes
Service Constants: Type-safe service names prevent errors

Consul UI

Access the Consul dashboard at: http://localhost:8500

View all registered services, health status, and service instances.

🐳 Docker Commands

# Full stack (all services + infrastructure)
docker-compose --profile full up --build

# Infrastructure only (Consul + databases + Redis)
docker-compose --profile consul --profile databases up

# Only Consul
docker-compose --profile consul up

# Only databases
docker-compose --profile databases up

# View logs
docker-compose logs -f [service-name]

# Stop all services
docker-compose down

# Clean rebuild
docker-compose build --no-cache

🗄️ Database Setup

The project uses two PostgreSQL databases:

Tenants Database (Port 5432)

Purpose: Multi-tenant management
Schema: Stores tenants, channels, commerce backends, and users

Conversations Database (Port 5433)

Purpose: Chat and messaging with semantic search
Schema: Stores conversations, messages, customers, and semantic memory
Extension: pgvector for vector similarity search

Database Commands

# Generate Prisma clients
cd apps/tenants && pnpm db:generate
cd apps/conversations && pnpm db:generate

# Push schemas to databases
cd apps/tenants && pnpm db:push
cd apps/conversations && pnpm db:push

# Run migrations
cd apps/tenants && pnpm db:migrate
cd apps/conversations && pnpm db:migrate

# Open Prisma Studio
cd apps/tenants && pnpm db:studio      # Tenants DB GUI
cd apps/conversations && pnpm db:studio # Conversations DB GUI

⚙️ Configuration

Environment Files

Each service has environment files for different deployment scenarios:

apps/[service]/
├── .env          # Local development (CONSUL_HOST=localhost)
└── .env.docker   # Docker environment (CONSUL_HOST=consul)

Environment Variables

Common Configuration (All Services)

NODE_ENV=development
HOST=localhost          # Local: localhost, Docker: 0.0.0.0
PORT=3001              # Unique per service
LOG_LEVEL=info
CONSUL_HOST=localhost  # Local: localhost, Docker: consul
CONSUL_PORT=8500

Gateway Specific

CORS_ENABLED=true
CORS_ORIGINS=*
SWAGGER_ENABLED=true
SWAGGER_PATH=api

Database URLs

# Tenants Service
DATABASE_URL=postgresql://tenants_user:tenants_password@localhost:5432/tenants_db

# Conversations Service
DATABASE_URL=postgresql://conversations_user:conversations_password@localhost:5433/conversations_db

# Orchestrator/Agent Service (requires pgvector)
AGENT_DATABASE_URL=postgresql://agent_user:agent_password@localhost:5436/agent_db

Redis

REDIS_HOST=localhost
REDIS_PORT=6379

Auth Service (Supabase)

# Supabase Configuration
SUPABASE_URL=https://your-project-id.supabase.co
SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

# Password Reset Redirect URL
AUTH_REDIRECT_URL=http://localhost:3005

# Optional JWT Configuration
JWT_SECRET=your-jwt-secret
JWT_EXPIRES_IN=24h

📁 Project Structure

lunelo/                          # Monorepo root
├── apps/                        # Applications
│   ├── gateway/                # @lunelo/gateway - HTTP API Gateway
│   ├── orchestrator/           # @lunelo/orchestrator - WhatsApp & AI orchestration
│   ├── tenants/                # @lunelo/tenants - Multi-tenant management
│   └── conversations/         # @lunelo/conversations - Chat and messaging
├── packages/                   # Shared packages
│   ├── agent/                  # @lunelo/agent - Multi-agent AI system (VoltAI)
│   ├── adapters/              # @lunelo/adapters - External integrations (WooCommerce, etc.)
│   ├── cache/                 # @lunelo/cache - Caching utilities
│   ├── config/                # @lunelo/config - Configuration schemas
│   ├── events/                # @lunelo/events - Event system and queues
│   ├── shared/                # @lunelo/shared - Common utilities & Consul integration
│   └── typescript-config/     # Shared TypeScript configurations
├── docker-compose.yml          # Container orchestration
├── turbo.json                 # Turbo monorepo configuration
├── pnpm-workspace.yaml        # pnpm workspace configuration
└── README.md                  # This file

Monorepo Benefits

Shared Dependencies: Common packages used across all services
Parallel Execution: Turbo runs tasks in parallel with dependency awareness
Workspace Filtering: Run commands on specific services with --filter
Dependency Management: pnpm efficiently manages dependencies across workspaces
Type Safety: Shared TypeScript configuration ensures consistency

🔄 Data Flow

WhatsApp Message Processing

WhatsApp → Orchestrator (webhook via Twilio)
Orchestrator → Tenants Service (get channel/tenant info)
Orchestrator → Conversations Service (get/create conversation)
Orchestrator → Agent Package (process with multi-agent AI)
Agent Package → Tenants Service (get store details)
Agent Package → Conversations Service (store agent response)
Orchestrator → WhatsApp (send response via Twilio)

Service Communication

All inter-service communication uses RPC via Consul service discovery:

Services register with Consul on startup
RPC calls use service names (type-safe constants)
Automatic load balancing across healthy instances
Health checks ensure service availability

🛠️ Development Workflow

Monorepo Commands

# Install dependencies for all packages
pnpm install

# Build all packages (respects dependency order)
pnpm run build

# Start all services in development mode
pnpm run dev

# Run specific service
pnpm run dev --filter=@lunelo/gateway

# Run multiple services
pnpm run dev --filter=@lunelo/gateway --filter=@lunelo/orchestrator

# Lint all packages
pnpm run lint

# Format all code
pnpm run format

# Type check all packages
pnpm run check-types

# Build specific service
pnpm run build --filter=@lunelo/orchestrator

# Add dependency to specific workspace
pnpm --filter=@lunelo/gateway add express

🔍 Monitoring & Health

Service URLs

API Gateway: http://localhost:3000
Swagger Docs: http://localhost:3000/api
Health Check: http://localhost:3000/health
Bull Board: http://localhost:3000/admin/queues (if configured)
Consul UI: http://localhost:8500
Tenants Service: http://localhost:3001 (RPC only)
Orchestrator Service: http://localhost:3002 (RPC only)
Conversations Service: http://localhost:3004 (RPC only)

Health Monitoring

# Check gateway health
curl http://localhost:3000/health

# Check Consul services
curl http://localhost:8500/v1/catalog/services

# Check specific service health
curl "http://localhost:8500/v1/health/service/orchestrator?passing=true"

🚀 Scaling Services

Horizontal Scaling

# Start multiple instances locally (different ports)
PORT=3002 pnpm run dev --filter=@lunelo/orchestrator  # Instance 1
PORT=3003 pnpm run dev --filter=@lunelo/orchestrator  # Instance 2

# Or with Docker
docker-compose --profile full up --scale orchestrator=3

Benefits

No code changes required for scaling
Automatic load balancing across instances
Health-based routing (unhealthy instances excluded)
Zero-downtime scaling

🔧 Troubleshooting

Common Issues

Services Not Registering

Check Consul is running: curl http://localhost:8500/v1/status/leader
Verify CONSUL_HOST and CONSUL_PORT environment variables
Check service logs for registration errors

Service Discovery Failing

Verify services are registered in Consul UI
Check service health status
Ensure network connectivity between services

Database Connection Issues

# Check database is running
docker-compose ps postgres-tenants
docker-compose ps postgres-conversations

# Check database logs
docker-compose logs postgres-tenants
docker-compose logs postgres-conversations

# Verify connection strings in .env files

Docker Issues

# Clean up containers and volumes
docker-compose down -v

# Rebuild from scratch
docker-compose build --no-cache

# Check container logs
docker-compose logs [service-name]

# If Consul fails to start
docker-compose down -v  # Clears volumes
docker-compose --profile consul up  # Restart Consul

📋 Package Names

@lunelo/gateway - HTTP API Gateway
@lunelo/orchestrator - WhatsApp & AI orchestration
@lunelo/tenants - Multi-tenant management
@lunelo/conversations - Chat and messaging management
@lunelo/agent - Multi-agent AI system
@lunelo/adapters - External integrations (WooCommerce, etc.)
@lunelo/cache - Caching utilities
@lunelo/config - Configuration schemas
@lunelo/events - Event system and queues
@lunelo/shared - Common utilities & Consul integration

🎯 Production Considerations

Infrastructure

Deploy 3+ Consul nodes for high availability
Enable Consul ACLs for security
Use TLS for Consul communication
Set up database replication and backups
Configure Redis clustering for high availability

Service Security

Implement service-to-service authentication
Use environment-specific configurations
Enable request/response encryption
Secure WhatsApp webhook endpoints

Monitoring

Integrate with Prometheus/Grafana
Set up alerting for service health
Monitor Consul cluster health
Track queue metrics (Bull Board)
Monitor AI agent performance

📞 Getting Help

Consul UI: http://localhost:8500 - Service registry and health
API Docs: http://localhost:3000/api - Swagger documentation
Health Check: http://localhost:3000/health - Service status

The architecture is designed to be developer-friendly with automatic service discovery, health monitoring, and easy scaling. All services use consistent patterns for communication and configuration.

Name		Name	Last commit message	Last commit date
Latest commit History 118 Commits
.vscode		.vscode
apps		apps
packages		packages
plugins/woocommerce		plugins/woocommerce
.env.example		.env.example
.gitignore		.gitignore
.npmrc		.npmrc
README.md		README.md
biome.json		biome.json
docker-compose.yml		docker-compose.yml
init-pgvector.sql		init-pgvector.sql
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
setup.sh		setup.sh
turbo.json		turbo.json

Folders and files

Latest commit

History

Repository files navigation

Lunelo

🏗️ Architecture

Core Components

Infrastructure Services

🚀 Quick Start

Prerequisites

Automated Setup

Manual Setup

Option 1: Full Docker Environment

Option 2: Local Development

📊 Services Overview

API Gateway (Port 3000)

Orchestrator Service (Port 3002)

Tenants Service (Port 3001)

Conversations Service (Port 3004)

🤖 Multi-Agent AI System

Agent Hierarchy

Agent Capabilities

🔧 Service Discovery with Consul

Key Features

Consul UI

🐳 Docker Commands

🗄️ Database Setup

Tenants Database (Port 5432)

Conversations Database (Port 5433)

Database Commands

⚙️ Configuration

Environment Files

Environment Variables

Common Configuration (All Services)

Gateway Specific

Database URLs

Redis

Auth Service (Supabase)

📁 Project Structure

Monorepo Benefits

🔄 Data Flow

WhatsApp Message Processing

Service Communication

🛠️ Development Workflow

Monorepo Commands

🔍 Monitoring & Health

Service URLs

Health Monitoring

🚀 Scaling Services

Horizontal Scaling

Benefits

🔧 Troubleshooting

Common Issues

Services Not Registering

Service Discovery Failing

Database Connection Issues

Docker Issues

📋 Package Names

🎯 Production Considerations

Infrastructure

Service Security

Monitoring

📞 Getting Help

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages