Integration Documentation

Overview

Marcus AI uses a hybrid architecture that keeps your customer data on your infrastructure while leveraging our AI engine. This guide walks you through integrating the Marcus connector into your environment.

Architecture Overview

The integration consists of three main components:

• Marcus Connector - Runs on your server, connects to your database
• Your Database - Stores customer data and conversation history
• Ventra AI Engine - Our cloud service that provides AI responses

Communication flow:

1. Customer sends message through your website/app
2. Marcus Connector receives message and queries your database
3. Connector sends anonymized query to Ventra AI Engine
4. AI Engine returns response template
5. Connector fills template with customer data
6. Response sent to customer

Prerequisites

Before starting the integration, ensure you have:

Technical Requirements

• Server Access - Root or sudo access to your Linux server
• Database Access - Read credentials for your customer database
• Domain/SSL - Domain name with valid SSL certificate (for web widget)
• API Key - Ventra Systems API key (provided after signup)
• License Key - Marcus license key (provided after signup)

Knowledge Requirements

• Basic Linux command line navigation
• Understanding of your database schema
• Familiarity with environment variables and configuration files
• Basic networking concepts (ports, firewalls, reverse proxy)

Database Setup

Marcus Connector needs read access to your customer database. We support MySQL, PostgreSQL, and SQLite.

Required Database Schema

Your database should have tables containing:

• Customers/Users - Customer identification, contact info
• Accounts/Balances - Account balances, transaction history
• Preferences - Customer settings, VIP tiers, etc.

Create Read-Only User

For security, create a read-only database user for Marcus:

MySQL Example:

-- Create read-only user
CREATE USER 'marcus_readonly'@'localhost' IDENTIFIED BY 'secure_password';

-- Grant SELECT on specific tables
GRANT SELECT ON your_database.customers TO 'marcus_readonly'@'localhost';
GRANT SELECT ON your_database.accounts TO 'marcus_readonly'@'localhost';
GRANT SELECT ON your_database.transactions TO 'marcus_readonly'@'localhost';

-- Apply changes
FLUSH PRIVILEGES;

PostgreSQL Example:

-- Create read-only user
CREATE USER marcus_readonly WITH PASSWORD 'secure_password';

-- Grant connection
GRANT CONNECT ON DATABASE your_database TO marcus_readonly;

-- Grant SELECT on schema
GRANT USAGE ON SCHEMA public TO marcus_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO marcus_readonly;

Server Requirements

Marcus Connector can run on most modern Linux distributions.

Minimum Specifications

Component	Minimum	Recommended
OS	Ubuntu 20.04+, CentOS 8+, Debian 10+	Ubuntu 22.04 LTS
CPU	2 vCPU	4 vCPU
RAM	2 GB	4 GB
Storage	10 GB	20 GB SSD
Network	1 Gbps	1 Gbps+

Required Software

• Node.js - Version 18.x or higher
• npm - Version 9.x or higher
• PM2 - Process manager for Node.js (optional but recommended)
• Nginx - Reverse proxy (if serving web widget)

Firewall Configuration

Ensure these ports are accessible:

• Port 3000 - Marcus Connector (internal)
• Port 443 - HTTPS (if serving web widget)
• Outbound 443 - Connection to Ventra AI Engine

Installation Steps

Follow these steps to install Marcus Connector on your server.

Step 1: Install Node.js

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# Verify installation
node --version
npm --version

Step 2: Download Marcus Connector

You'll receive a secure download link after signing up. Download and extract:

# Download (link provided by Ventra Systems)
wget https://download.ventrasystems.com/marcus-connector-v1.tar.gz

# Extract
tar -xzf marcus-connector-v1.tar.gz
cd marcus-connector

# Install dependencies
npm install --production

Step 3: Configure Environment

Create a .env file with your configuration:

# Ventra API Configuration
VENTRA_API_KEY=your_api_key_here
MARCUS_LICENSE_KEY=your_license_key_here
VENTRA_AI_ENDPOINT=https://ai.ventrasystems.com/api/v1

# Database Configuration
DB_TYPE=mysql
DB_HOST=localhost
DB_PORT=3306
DB_NAME=your_database
DB_USER=marcus_readonly
DB_PASSWORD=secure_password

# Server Configuration
PORT=3000
NODE_ENV=production

# Optional: Telegram/WhatsApp Integration
TELEGRAM_BOT_TOKEN=your_telegram_token
WHATSAPP_API_KEY=your_whatsapp_key

Step 4: Start Marcus Connector

# Using Node directly (testing only)
node server.js

# Using PM2 (recommended for production)
npm install -g pm2
pm2 start server.js --name marcus-connector
pm2 save
pm2 startup

Step 5: Verify Installation

# Check if Marcus is running
pm2 status

# Check logs
pm2 logs marcus-connector

# Test health endpoint
curl http://localhost:3000/health

Configuration

Customize Marcus to fit your business needs.

Database Mapping

Tell Marcus where to find customer data in your database:

{
  "database_mapping": {
    "customers": {
      "table": "users",
      "fields": {
        "id": "user_id",
        "name": "full_name",
        "email": "email_address",
        "created_at": "registration_date"
      }
    },
    "accounts": {
      "table": "player_accounts",
      "fields": {
        "balance": "current_balance",
        "currency": "currency_code",
        "vip_tier": "vip_level"
      }
    }
  }
}

Personality & Behavior

Customize Marcus's personality in config/personality.json:

{
  "name": "Marcus",
  "tone": "friendly",
  "formality": "casual",
  "emoji_usage": "moderate",
  "response_length": "concise",
  "greeting_message": "Hey there! 👋 I'm Marcus, your AI assistant. How can I help?",
  "business_hours": {
    "enabled": false,
    "timezone": "UTC",
    "message": "We're currently closed, but I'm here 24/7!"
  }
}

Response Templates

Customize common responses:

{
  "balance_inquiry": "You've got {balance} {currency} in your account right now 👍",
  "deposit_confirmation": "Your {amount} {currency} deposit is being processed 🚀",
  "withdrawal_request": "Withdrawal request received! We'll process your {amount} {currency} shortly",
  "vip_status": "You're a {vip_tier} member - nice! 🌟"
}

Testing Your Integration

Verify everything works before going live.

1. Test Database Connection

# Run the database test script
npm run test:database

# Expected output:
# ✓ Database connection successful
# ✓ Can read customers table
# ✓ Can read accounts table

2. Test AI Connection

# Test AI endpoint connectivity
npm run test:ai

# Expected output:
# ✓ Connected to Ventra AI Engine
# ✓ License validated
# ✓ API key authenticated

3. Send Test Message

# Send a test message via API
curl -X POST http://localhost:3000/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "test_user_123",
    "message": "What is my balance?",
    "platform": "web"
  }'

4. Load Testing

Use the provided load test script to simulate traffic:

# Install load testing tool
npm install -g loadtest

# Run load test (100 requests, 10 concurrent)
loadtest -c 10 -n 100 http://localhost:3000/api/chat

API Reference

Marcus Connector exposes these REST API endpoints.

Authentication

All requests require authentication via API key:

Authorization: Bearer YOUR_API_KEY

POST /api/chat

Send a message to Marcus.

Request Body:

{
  "user_id": "string",      // Customer ID from your database
  "message": "string",      // Customer's message
  "platform": "web|telegram|whatsapp",
  "metadata": {            // Optional
    "session_id": "string",
    "language": "en"
  }
}

Response:

{
  "success": true,
  "data": {
    "response": "You've got $1,250 in your account right now 👍",
    "conversation_id": "conv_abc123",
    "timestamp": "2026-02-26T14:30:00Z"
  }
}

GET /api/health

Check system health and status.

Response:

{
  "status": "ok",
  "version": "1.2.0",
  "uptime": 86400,
  "database": "connected",
  "ai_engine": "connected",
  "license": "valid"
}

GET /api/conversations/:user_id

Retrieve conversation history for a user.

Response:

{
  "success": true,
  "data": {
    "user_id": "12345",
    "conversations": [
      {
        "id": "conv_abc123",
        "timestamp": "2026-02-26T14:30:00Z",
        "messages": [
          {
            "role": "user",
            "content": "What's my balance?",
            "timestamp": "2026-02-26T14:30:00Z"
          },
          {
            "role": "assistant",
            "content": "You've got $1,250 in your account right now 👍",
            "timestamp": "2026-02-26T14:30:02Z"
          }
        ]
      }
    ]
  }
}

Troubleshooting

Common issues and solutions.

Database Connection Fails

AI Engine Not Responding

License Validation Failed

High Memory Usage

Getting More Help

If you're still stuck:

• Check logs: pm2 logs marcus-connector --lines 100
• Enable debug mode: DEBUG=* pm2 restart marcus-connector
• Contact support: support@ventrasystems.com
• Join our Telegram: @ventrabots

Support & Resources

Get help from our team and community.

Contact Support

• Email: support@ventrasystems.com
• Telegram: @ventrabots
• Emergency: urgent@ventrasystems.com (24/7)

Additional Resources

• Security Documentation
• Blog & Tutorials
• Schedule Onboarding Call

Changelog

Stay updated with the latest Marcus releases:

• v1.2.0 (Feb 2026) - WhatsApp integration, improved NLP
• v1.1.0 (Jan 2026) - Multi-language support, analytics dashboard
• v1.0.0 (Dec 2025) - Initial release