Technical Specification

Complete implementation reference for the Ready1Go WhatsApp AI Agent platform — packages, architecture, data models, API surface, and module wiring.

Architecture Overview

Technology Stack

Core Framework

Runtime Environment

Deployment Topology

# Public internet → ready1go.com → Apache 2.4 (SSL, port 443)
#
#  Apache VirtualHost: ready1go.com
#  DocumentRoot: /var/www/ready1go.com/public_html
#
#  .htaccess rule (mod_proxy + mod_rewrite):
#    /whatsapp_agent/api/*  →  ProxyPass  http://127.0.0.1:8787/api/*
#
#  Laravel (php artisan serve) running at 127.0.0.1:8787
#  Process: nohup php artisan serve --host=0.0.0.0 --port=8787
#  Working dir: /var/www/ready1go.com/public_html/whatsapp_agent/backend
#
#  Static HTML/JS/CSS served directly by Apache from:
#    /var/www/ready1go.com/public_html/whatsapp_agent/
#
#  Database: MariaDB 10.11 — r1g_whatsapp (user: sandbox)
#  PostgreSQL + pgvector: pending installation

File Structure

whatsapp_agent/
├── index.html                   # Portal selector
├── assets/
│   └── api.js                   # Shared JWT API client
├── admin/                       # Client Admin portal (35 pages)
├── super/                       # Super Admin portal (14 pages)
├── agent/                       # Agent portal (5 pages)
├── docs/                        # This page + user guide
└── backend/                     # Laravel 12 application
    ├── app/
    │   ├── Http/
    │   │   ├── Controllers/Api/V1/
    │   │   │   ├── Admin/       # Auth, KB, Conversation, Campaign, Analytics
    │   │   │   ├── Super/       # TenantController
    │   │   │   └── Webhook/     # WhatsAppWebhookController
    │   │   └── Middleware/      # TenantAuth, SuperAdminAuth, AuditLogger, VerifyMetaSig
    │   ├── Models/              # 30+ Eloquent models
    │   ├── Modules/
    │   │   ├── Core/            # WebhookRouter, SessionManager, LanguageDetector, MessageDispatcher
    │   │   ├── RAG/             # RagEngine, LlmRouter, EmbeddingService, TextChunker, TextExtractor, DocumentIngestionPipeline
    │   │   ├── Flow/            # FlowEngine
    │   │   ├── LiveAgent/       # AgentQueue
    │   │   ├── Broadcast/       # CampaignDispatcher, AudienceResolver
    │   │   └── WhatsApp/        # CloudApiClient
    │   ├── Jobs/                # ProcessInboundMessage, IngestDocument, DispatchCampaign, ProcessStatusUpdate
    │   ├── Events/              # ConversationQueued, AgentMessageReceived
    │   └── Services/            # EncryptionService (AES-256-GCM)
    ├── database/
    │   ├── migrations/
    │   │   ├── platform/        # resellers, plans, tenants, platform_users
    │   │   ├── tenant/          # all per-tenant tables (9 migration files)
    │   │   └── pgvector/        # kb_chunks with vector column
    │   └── seeders/DatabaseSeeder.php
    └── routes/api.php

Authentication & Auth Guards

User Models & Guards

Login Flow

Token Usage Pattern

# All protected endpoints:
Authorization: Bearer <jwt>

# Middleware resolves user:
$user = JWTAuth::parseToken()->toUser();
# Injected into request:
$request->merge(['_tenant_id' => $user->tenant_id, '_auth_user' => $user]);

API Routes

Base path: /whatsapp_agent/api/v1 (proxied via Apache to Laravel at localhost:8787/api/v1)

Middleware

Inbound Message Processing Pipeline

Every WhatsApp message from a user triggers this pipeline. The process is intentionally async — the webhook controller responds 200 OK immediately and offloads processing to a queue job.

RAG Engine

Document Ingestion Pipeline (IngestDocument job)

Query-time Retrieval

# RagEngine::answer($query, $tenantId, $kbId)
1. EmbeddingService::embed($query)           # → 1536-dim vector
2. pgvector cosine similarity search         # top-K chunks (K=5)
   SELECT *, 1 - (embedding <=> $vec) AS sim
   FROM kb_chunks WHERE kb_id = $kbId
   ORDER BY embedding <=> $vec LIMIT 5;
3. LlmRouter::complete($prompt, $context)    # inject retrieved chunks
4. Store MessageCitation records             # chunk_id → message_id
5. Return response + confidence score

LLM Router

The LlmRouter selects the LLM provider per request based on the tenant's tenant_llm_routing configuration. Supported providers: OpenAI (gpt-4o, gpt-4o-mini), Azure OpenAI, Anthropic Claude. Credentials per tenant are stored AES-256-GCM encrypted in tenant_llm_credentials.

Flow Engine

Flows are visual conversation scripts stored in flows → flow_versions → flow_nodes. Each node has a type (message, question, condition, api_call, transfer, end) and a config JSON blob. The FlowEngine evaluates the current node, dispatches the output via MessageDispatcher, then advances the session pointer to the next node based on user input matching.

Node Types

Live Agent Queue

When a conversation is escalated (escalation keyword, out-of-hours, low RAG confidence, or user request), AgentQueue::escalate() sets conversations.status = 'agent_queue' and fires the ConversationQueued event. Agents see this appear in real-time via Pusher WebSocket. When an agent claims the conversation, AgentQueue::assign() sets assigned_agent_id and status to agent_active. The AgentMessageReceived event notifies all supervisors of agent replies.

Availability States

Each agent has a row in agent_availability: online (takes new conversations), away (visible but not auto-assigned), offline (hidden from queue). The supervisor view shows all agent statuses in real-time.

Broadcast & Campaigns

The CampaignDispatcher resolves the target audience via AudienceResolver (applies tag filters, opt-in status, last active date), then splits into batches and dispatches DispatchCampaign jobs. Each job calls CloudApiClient::sendTemplate() and records a campaign_sends row. Delivery status callbacks from Meta's webhook update campaign_sends.status (sent → delivered → read / failed).

A/B testing: campaigns can have multiple CampaignAbVariant records. The audience is split evenly and each variant's template sent to its share. Open/read rates are compared after 24h.

Drip sequences: DripSequence + DripSequenceStep define timed message series. DripSequenceEnrollment tracks each user's position. The scheduler's DispatchScheduledCampaigns command runs every minute and dispatches any step whose send_at has passed.

WhatsApp Cloud API Client

CloudApiClient wraps the Meta Cloud API v20. It is instantiated with the tenant's phone number ID and access token (stored encrypted). All messages route through MessageDispatcher which picks the correct client per tenant.

Queue Jobs

Scheduled Commands

Run via php artisan schedule:run in crontab (* * * * *).

Events & WebSocket Broadcasts

Database Schema

All tables reside in the r1g_whatsapp MariaDB database. UUIDs (v4) are used as primary keys throughout. Tenant isolation is via tenant_id column — no row-level security, enforced in application code. pgvector tables live in a separate PostgreSQL database.

Encryption

Sensitive secrets (TOTP seeds, WhatsApp access tokens, LLM API keys) are stored encrypted in the database. The EncryptionService uses AES-256-GCM with a 256-bit key stored in .env as hex (CREDENTIAL_ENCRYPTION_KEY). Each encryption call generates a unique 12-byte random nonce prepended to the ciphertext. Key loading is lazy — the key is only read from config when encrypt() or decrypt() is first called, preventing artisan command boot failures if the key is not configured.

# Ciphertext format (base64-encoded):
[ 12-byte nonce ][ N-byte ciphertext ][ 16-byte GCM auth tag ]

# Key: 32 bytes loaded from 64-char hex string in .env
CREDENTIAL_ENCRYPTION_KEY=387975dfc840dfbb... # 64 hex chars = 32 bytes

Security

Frontend Architecture

The frontend is intentionally server-free: plain HTML + CSS + vanilla JavaScript served directly by Apache as static files. There is no build step, no bundler, and no framework. All dynamic data is fetched via the shared api.js client module.

Shared API Client (api.js)

Located at /whatsapp_agent/assets/api.js and included via <script> tag on every page. Exposes a global API object.

// Token management
API.getToken()          // reads from localStorage 'r1g_token'
API.setToken(jwt)       // stores token
API.getUser()           // parses JWT payload (no verify — frontend only)
API.requireAuth()       // redirect to login if no token
API.logout()            // POST /auth/logout then clear localStorage

// Namespaced API methods
API.admin.login(email, pass, totpCode)
API.admin.analytics(days)          // GET /admin/analytics/dashboard
API.admin.ragStats(days)           // GET /admin/analytics/rag
API.admin.conversations(filters)   // GET /admin/conversations
API.admin.campaigns()              // GET /admin/campaigns
API.admin.kb()                     // GET /admin/kb

API.super.tenants()                // GET /super/tenants
API.super.analytics()              // GET /super/analytics
API.super.auditLog(filters)        // GET /super/audit-log

API.agent.queue()                  // GET /agent/queue
API.agent.setAvailability(status)  // POST /agent/availability
API.agent.claim(convId)            // POST /agent/conversations/:id/claim