Phase 1: Discovery & User Journeys

1. Context & Goal

The Content Engine is a fully independent, standalone product service offered to LogicSpike Tenants (Agencies, Creators, Business Owners). It empowers them to plan any type of content (text posts, product images, video reels, motivational quotes, promotional offers, stories — anything) on a visual calendar and automatically publish to multiple social media platforms — all from within their LogicSpike workspace.

Independence: This service does NOT require the Blog Engine or any other LogicSpike service. A tenant can activate only the Content Engine and start scheduling social media posts immediately.

2. Actors

3. Core User Journeys

Journey A: First-Time Setup — "Connect My Social Accounts"

Persona: Rahul, agency owner. Manages 3 client brands.

Goal: Connect his clients' social media accounts so he can schedule posts.

1. Trigger: Rahul navigates to Dashboard → Content Engine → Settings → Connected Accounts.
2. Action:
   • Sees a card for each supported platform: Twitter/X, Instagram, LinkedIn, Facebook.
   • Clicks "Connect" on Twitter/X.
   • Redirected to Twitter's OAuth consent screen.
   • Authorizes LogicSpike to post on behalf of @ClientBrand1.
   • Returns to dashboard — sees @ClientBrand1 listed under Twitter with status "✅ Connected".
   • Repeats for Instagram (via Meta) and LinkedIn.
3. System Logic:
   • Store access_token + refresh_token encrypted in social_connections table.
   • Validate token works by making a lightweight API call (e.g., "Get profile info").
   • Set connection status to active.
4. Outcome: Rahul's workspace now has 3 connected social accounts ready for scheduling.

Journey B: Planning Content — "My Weekly Calendar"

Persona: Priya, content manager at Rahul's agency.

Goal: Plan next week's social media content in one session.

1. Trigger: Priya opens Dashboard → Content Engine → Calendar (defaults to Week view).
2. Action:
   • Sees an empty week grid with time slots.
   • Clicks on Monday, 9:00 AM → "New Content Slot" modal opens.
   • Fills in:
     • Caption: "🚀 Our latest product update is here! Check out what's new..."
     • Media: Uploads a product image (via Media Service).
     • Platforms: Checks Twitter/X and LinkedIn.
     • Labels: Tags #ProductLaunch.
     • Status: Saves as Draft.
   • Repeats for Tuesday, Wednesday, Thursday — creating 4 more slots.
   • Drags Wednesday's post to Thursday (reschedule via drag-and-drop).
3. System Logic:
   • Each content slot is created with a scheduledAt timestamp in UTC.
   • Media is uploaded to Media Service, mediaId is stored.
   • Calendar queries fetch slots via WHERE scheduledAt BETWEEN ? AND ?.
4. Outcome: Priya sees a well-planned week with 5 diverse content slots (text, images, video) color-coded by platform.

Journey C: Approval Workflow — "Review Before Publishing"

Persona: Rahul (Owner) wants to review Priya's content before it goes live.

Goal: Ensure quality and brand voice before automated publishing.

1. Trigger: Priya finishes planning and clicks "Submit for Review" on all 5 slots.
2. Action:
   • Slots move from draft → pending_review.
   • Rahul receives an in-app notification: "5 content slots awaiting review."
   • Rahul opens the Review Queue — sees all pending slots in a list view.
   • Approves 4 slots → they move to approved → automatically to scheduled.
   • Rejects 1 slot with a comment: "Caption is too long for Twitter. Please shorten."
   • Rejected slot moves back to draft with the reviewer's comment attached.
3. System Logic:
   • State transitions enforced via permission: content:slots.approve.
   • State machine: draft → pending_review → approved → scheduled.
   • Rejected slots: pending_review → draft (with rejection reason).
4. Outcome: 4 slots are now scheduled and will auto-publish. 1 slot is returned to Priya for editing.

Journey D: Automated Publishing — "It Just Works"

Persona: The system scheduler (background worker).

Goal: Publish content at the exact scheduled moment.

1. Trigger: Cloudflare Cron Trigger fires every 1 minute.
2. Logic:
   • Query: SELECT * FROM content_slots WHERE status = 'scheduled' AND scheduledAt <= NOW().
   • For each due slot:
     • Set status → publishing.
     • For each target platform:
       • Fetch the platform's OAuth token from social_connections.
       • Upload media to the platform's API if applicable.
       • Call the platform's publish API with the caption + media.
       • If success: Update status → published, store externalPostId.
       • If failure: Increment retry count, set status → failed, enqueue for retry.
3. Retry Logic:
   • Failed posts are retried up to 3 times with exponential backoff (1min → 5min → 15min).
   • After 3 failures, the slot is permanently marked failed and the tenant is notified.
4. Outcome: Posts appear on social media accounts at the exact scheduled time without human intervention.

Journey E: Cross-Service (Optional) — "Blog Post Published → Auto-Schedule Social"

Persona: Rahul has the Blog Engine active and wants to auto-promote every new blog post.

Goal: When a blog post goes live, automatically create social media content slots.

1. Trigger: Blog Engine publishes a post → emits blog.published event on the Event Bus.
2. Logic:
   • Content Engine listens for blog.published.
   • Reads the event payload: { title, summary, featuredImage, url }.
   • Auto-creates content slots for each connected platform:
     • Twitter: "{title} — Read more: {url}" (truncated to 280 chars).
     • LinkedIn: "{summary}\n\n📖 Read the full article: {url}".
   • Slots are created with status: 'draft' (requires manual review) or status: 'scheduled' (if auto-publish enabled in tenant settings).
   • scheduledAt defaults to "1 hour from now" or follows tenant's configured rules.
3. Outcome: Every blog post automatically gets social media promotion — zero manual effort.

Journey F: Recurring Content — "Motivation Mondays"

Persona: Priya wants to schedule a recurring post every Monday.

Goal: Set up a content pattern that auto-creates slots weekly.

1. Trigger: Priya clicks "New Recurring Schedule" in the Calendar.
2. Action:
   • Sets Recurrence: Weekly — Monday at 10:00 AM.
   • Sets Template: Caption = "💡 Motivation Monday: {quote}" + a placeholder image.
   • Sets Platforms: Instagram + LinkedIn.
   • Sets Auto-schedule: Yes (skips approval).
3. System Logic:
   • Stores a recurring_schedule record with the cron pattern.
   • A daily background job generates content slots 7 days in advance from recurring schedules.
   • Each generated slot is editable — Priya can customize the quote each week.
4. Outcome: Slots auto-appear on the calendar every Monday, ready to publish or customize.

4. Key Requirements

5. Emotional Design Goals

Priya opens the calendar on Monday morning. She sees the entire week laid out — color-coded slots, platform icons, status badges. She drags two posts to better time slots, approves a pending item, and closes the tab. She never touches Hootsuite, Buffer, or a spreadsheet again.

This is the experience we're building.

6. AI Agent Journeys

Journey G: AI Agent — "The Autonomous Content Strategist"

Persona: An AI agent configured by Rahul's agency to operate their content pipeline.

Goal: Autonomously plan, schedule, and manage a full week of social content via MCP.

1. Trigger: Agent is invoked on Sunday evening via a scheduled automation or by a team member via Claude Desktop.
2. Agent Flow (via MCP tools):
   • Calls list_connections → discovers @ClientBrand1 (Twitter), ClientBrand (LinkedIn), @clientbrand (Instagram) are connected.
   • Calls get_calendar(from: Monday, to: Friday) → sees 2 existing slots on Monday and Wednesday.
   • Calls list_campaigns → finds "Q1 Product Launch" campaign is active.
   • Agent decides Tuesday, Thursday, and Friday need content to maintain cadence.
   • Calls bulk_schedule with 3 slots:
     • Tuesday 9 AM: Product teaser → Twitter + LinkedIn
     • Thursday 2 PM: Customer testimonial → Instagram + LinkedIn
     • Friday 10 AM: Weekend engagement post → Twitter + Instagram
   • All slots created with autoApprove: false → status = draft (human must review).
   • Agent calls get_calendar(from: Monday, to: Friday) → confirms 5 slots across the week ✅.
3. Human-in-the-Loop:
   • Rahul receives notification: "AI agent scheduled 3 new content slots for review."
   • Rahul opens the Review Queue, reviews the AI-generated captions.
   • Approves 2, edits 1 caption before approving.
   • All 3 slots → scheduled.
4. System Logic:
   • Agent authenticated via API Key with content:slots.write + content:slots.read permissions.
   • Every action logged with agentId in the audit trail.
   • Rate limits enforced: max 50 slots per bulk call, max 200 slots/hour.
5. Outcome: The entire week's content is planned by an AI agent in under 10 seconds, with human approval as the final gate.

Journey H: AI Agent — "Reactive Publishing on Trending Topics"

Persona: An AI agent monitoring external signals (news, trends) via a custom automation.

Goal: Quickly schedule a timely post when a relevant trend is detected.

1. Trigger: The automation pipeline detects a trending topic related to Rahul's client.
2. Agent Flow (via MCP tools):
   • Calls check_connection_health for Twitter → confirms token is active.
   • Calls schedule_content with:
     • Caption: Timely, trend-relevant post copy.
     • Platforms: twitter.
     • scheduledAt: 30 minutes from now.
     • autoApprove: true (pre-approved for time-sensitive posts via agent config).
   • Slot created with status → scheduled.
3. System Logic:
   • The agent's API key has been pre-configured with autoApprove capability.
   • Post goes live 30 minutes later via the scheduler.
   • Agent calls get_publish_status to confirm → receives externalPostUrl.
4. Outcome: A time-sensitive, on-brand post goes live within 30 minutes of trend detection — no human bottleneck.