logicspike/docs

Content Engine

Content Engine: Scope Definition

Last Updated: 2026-03-15

"The Content Orchestrator"

The Content Engine is a fully independent, standalone scheduling and distribution service. It takes any ready content (text posts, images, videos, links, stories — anything) and ensures it reaches the right social media platform, at the right time, reliably.

IMPORTANT

This service has zero dependency on the Blog Engine or any other LogicSpike service. A tenant can use the Content Engine without ever activating the Blog Engine. The Blog Engine integration (listening for blog.published events) is an optional cross-service enhancement, not a core feature.

✅ IN SCOPE (What Lives Inside apps/content-engine)

1. Content Calendar System

  • CRUD operations for Content Slots (the atomic unit of scheduled content)
  • Calendar queries: by day, week, month, date range
  • Drag-and-drop reordering via API (position/time updates)
  • Recurring schedule pattern engine (cron-like definitions)
  • Timezone conversion and normalization per workspace

2. Social Platform Connectors

  • OAuth 2.0 Flow Management — Handle token acquisition, refresh, and revocation for:
    • Twitter/X API v2
    • Meta Graph API (Instagram, Facebook Pages)
    • LinkedIn API
  • Token Vault — Encrypted storage of access/refresh tokens per tenant per platform
  • Connection Health Monitoring — Detect expired tokens and notify the tenant

3. Publishing Engine

  • Scheduler — Cron-based job that polls for due content slots and dispatches them
  • Publisher Workers — Per-platform adapters that translate a content slot into a platform-native API call
  • Media Upload Pipeline — Upload attached media to each platform before publishing
  • Status Tracking — Update slot status through its lifecycle: draft → scheduled → publishing → published → failed
  • Retry Queue — Failed publishes enter a retry queue with configurable backoff

4. Approval Workflow

  • State machine: draft → pending_review → approved → scheduled → publishing → published
  • Permission-based transitions (e.g., only content:slots.approve can move from pending_review → approved)
  • Audit trail of state transitions

5. Labels & Campaigns

  • Tag content with labels (e.g., #ProductLaunch, #WeeklyTips)
  • Group content into Campaigns for organized planning
  • Filter calendar view by campaign or label

6. MCP Server (Agent Control Layer)

  • MCP Protocol Endpoint — Expose all Content Engine capabilities as MCP tools
  • 15+ MCP Tools — schedule_content, get_calendar, bulk_schedule, list_connections, etc.
  • MCP Resources — Read-only context: content://calendar/week, content://stats/overview
  • Agent Authentication — Via API Keys with PBAC permission scoping
  • Rate Limiting & Safety — Agent-specific rate limits, dryRun mode, autoApprove defaults off
  • Audit Trail — Every agent action logged with agentId

❌ OUT OF SCOPE (What Does NOT Live Here)

1. Content Creation / AI Generation

  • The Content Engine does NOT write copy, generate images, or design creatives
  • All content (text + media) is provided by the user, an AI agent, or any upstream source
  • Optional: The Blog Engine integration may auto-populate social copy from blog posts, but this is an opt-in feature

2. Social Media Analytics / Insights

  • The Content Engine does NOT track likes, impressions, or engagement metrics
  • That is a future Analytics Service concern
  • Only tracking: did the post succeed or fail?

3. Community Management

  • No DM inbox, no comment moderation, no follower management
  • This is a publishing tool, not a listening tool

4. Notification Delivery

  • The Content Engine does NOT send emails or SMS directly
  • It emits events (e.g., content.failed), and the Communication Service handles delivery

5. Media Storage

  • Media files are stored and served via the Media Service (apps/media-service)
  • The Content Engine only holds mediaId references

Interface Contract

Direction What Details
Inbound REST API Dashboard or SDK creates, schedules, and manages content slots
Inbound MCP Protocol AI agents control scheduling, publishing, and management via MCP tools
Inbound Event Bus (optional) Listens to blog.published to auto-create social slots
Outbound Social Platform APIs Publishes content to Twitter, Instagram, LinkedIn, Facebook
Outbound Event Bus Emits content.scheduled, content.published, content.failed
Outbound Media Service Fetches media assets for upload to social platforms

Dependency Map

┌──────────────────┐     ┌──────────────────┐
│  Seller Dashboard│     │   AI Agents      │
│  (UI — Calendar) │     │  (Claude, Gemini)│
└───────┬──────────┘     └────────┬─────────┘
        │ REST API                │ MCP Protocol
        ▼                         ▼
┌─────────────────────────────────────────┐
│          Content Engine                 │
│     ┌──────────┐  ┌──────────────┐      │
│     │ REST API │  │  MCP Server  │      │────▶ Social Platform APIs
│     └──────────┘  └──────────────┘      │
└──┬───────┬──────────────────────────────┘
   │       │
   │       │ Events
   │       ▼
   │  ┌────────────────┐
   │  │  Event Bus     │
   │  └────────────────┘
   │
   │ mediaId references
   ▼
┌──────────────────┐
│  Media Service   │
└──────────────────┘

Why This Boundary?

By keeping the Content Engine focused on scheduling and distribution, it:

  • Stays testable — no external content generation dependencies
  • Stays replaceable — any upstream can feed content into it
  • Follows the LogicSpike pattern — the Communication Service is a "stateless execution engine"; the Content Engine is a "stateful scheduling engine"
Content Engine