AI Marketing Platform — Implementation Guide

This document outlines the architectural blueprint for building a "set it and forget it" marketing automation SaaS using GoClaw multi-agent orchestration, Telegram as the conversational UI, and a Node.js/TypeScript API backend.

Current Implementation Status (April 2025)

✅ Phase 0-3 Complete:

Four-agent team (liaison, creator, critic, briefing)
MCP server with 28 tools
Full Telegram integration with pairing
Brand voice management
Post approval workflow
Automated cron jobs (morning briefing, approval reminders)
Publishing adapters for Twitter, LinkedIn, Facebook, Mailchimp, Ghost
OAuth flows for platform integrations
Email tracking and analytics

🚧 Phase 4 In Progress:

Marketing calendar integration (marketing_calendar table exists)
Website monitoring for content triggers
Analytics-driven content optimization

1. The Architectural Overview

Think of your system in three distinct layers:

The Orchestrator (GoClaw in Docker): This is the "General Manager." It talks to Telegram, orchestrates the agent teams, maintains conversational memory, and decides when to call your backend.
The State (Supabase): The source of truth. GoClaw uses Supabase for user isolation, long-term memory (via pgvector), and storing draft records and client data.
The Muscles (Node.js API): GoClaw calls the API via MCP server. The API handles the deterministic, heavy-lifting tasks (web scraping, content generation, publishing to platforms, fetching analytics).

2. Setting Up GoClaw Properly

GoClaw's superpower is Multi-Agent Orchestration. You don't want one massive prompt trying to do everything. You want a team.

A. The Agent Team (Implemented)

Four agents work together using GoClaw's Delegation and Evaluate Loop features:

liaison-agent (The Frontline): Connected directly to the Telegram channel. Chats with clients, ingests media/requests, presents drafts for approval.
creator-agent (The Writer): Hidden from the user. Takes client context, pulls news/website data, drafts content.
critic-agent (The Quality Gate): Hidden. Evaluates drafts against brand voice stored in Supabase before presentation to client.
briefing-agent (The Reporter): Runs daily cron jobs to send morning status snapshots to all active clients.

B. Skills (Tools for the Agents)

The MCP server at POST /mcp exposes 28 tools to the agents (see api/src/mcp/tools.ts):

Client Management:

search-customers, list-user-customers, fetch-client-context, client-dashboard, daily-briefing-summary

Post Operations:

create-post, save-platform-content, generate-content, list-posts, list-pending-posts
get-post-status, approve-post, pending-reminders, get-post-link
schedule-post, unschedule-post, schedule-multiple-posts, list-scheduled-posts, update-post-status

Content Tools:

scrape-url, search-images, publish-content

Telegram Integration:

get-telegram-user, pair-telegram, add-brand-voice

Navigation:

get-site-links, send-link-button

C. The Cron / Trigger System (Implemented)

GoClaw config.json defines three cron jobs:

Morning Briefing (daily at 9 AM): briefing-agent sends status snapshots to all paired clients
Approval Reminders (daily at 10 AM): liaison-agent reminds clients with posts pending >24h
Weekly Summary (Mondays at 9 AM): liaison-agent sends weekly performance summaries

3. Managing the Telegram Conversation (UX & Media)

Telegram is the primary client interface. GoClaw natively handles the webhook bridging.

Media Input: When a user sends an image (e.g., new menu photo), the liaison-agent can analyze it (via vision-capable LLM) and save it as a "Content Asset" in Supabase for the creator-agent to use later.
Approvals: The liaison-agent presents drafts with action buttons or natural language responses:
"I've drafted 3 posts. Here is post 1: [Text + Image preview]. Reply 'Approve' or tell me what to change."
Edits: If the user replies "Make it less formal", GoClaw's session memory understands the context. It delegates back to the creator-agent to rewrite that specific draft, then presents it again.

Pairing Flow (Implemented)

Users pair their Telegram account via the front-end dashboard (Settings → Messaging Connections), not through the bot. This ensures proper authentication and prevents unauthorized pairing.

4. The "Brain" (Context, News, and Analytics)

To make the AI actually good (and not just an automated generic spam bot), you need a feedback loop.

Ingestion (The Proactive Brain)

Website Changes (Phase 4): Cloudflare Browser Rendering API monitors client websites for new content (sitemap changes, blog posts). When detected, GoClaw receives a notification to generate a social campaign.
Holidays/Events (Phase 4): Marketing calendar integration. The creator-agent checks upcoming events (holidays, industry dates) before generating content to ensure timely, relevant posts.

Analytics (The Reactive Brain) (Implemented)

The API tracks open rates (Email via Resend webhooks) and engagement (Socials via platform APIs).
Metrics are stored in post_analytics table with per-platform granularity.
client-dashboard MCP tool aggregates analytics for briefings.
(Phase 4): Feed analytics into agent memory for content optimization.

5. Output Channels Flexibility (Implemented)

Platform adapters are implemented in api/src/integrations/

The API exposes a unified publishing endpoint: POST /publish

{
  "customer_id": 1,
  "platform_post_id": 42,
  "channels": ["twitter", "linkedin", "facebook"]
}

The API routes to the appropriate adapter (TwitterAdapter, LinkedInAdapter, etc.). Adding a new platform (like Bluesky) requires only implementing the PublishAdapter interface and adding it to the adapter registry in api/src/routes/content.ts.

Implementation Checklist

Phase 0-3 (Complete)

[x] Supabase database schema
[x] Four-agent team (liaison, creator, critic, briefing)
[x] MCP server with 28 tools
[x] Telegram integration with pairing
[x] Brand voice management
[x] Post approval workflow
[x] Cron jobs (briefing, reminders, summaries)
[x] Publishing adapters (Twitter, LinkedIn, Facebook, Mailchimp, Ghost)
[x] OAuth flows
[x] Email tracking

Phase 4 (In Progress)

[ ] Marketing calendar integration (marketing_calendar table exists)
[ ] Website monitoring cron job
[ ] Analytics-driven content optimization
[ ] Agent memory integration for learning from analytics

Phase 5-6 (Planned)

[ ] Dashboard evolution (see docs/migration/phase-5-dashboard-evolution.md)
[ ] Production hardening (see docs/migration/phase-6-production-hardening.md)

Quick Start

See docs/QUICK_REFERENCE.md for commands and environment variables.

Minimal setup:

# 1. Start the stack
docker compose -f docker-compose.dev.yml up -d --build

# 2. Seed agents and register MCP server
bash scripts/seed-goclaw-tools.sh      # Remove legacy tools
bash scripts/seed-goclaw-agents.sh     # Create agents, skills, team
bash scripts/register-mcp-server.sh    # Register MCP server

# 3. Restart GoClaw
docker compose -f docker-compose.dev.yml restart goclaw

# 4. Link Telegram via dashboard
# Go to Settings → Messaging Connections, paste Telegram chat ID

# 5. Send /start to the bot