GTM Schedule Engine: Design Document¶

Philosophy: Portability Over UI¶

The Dropbox Lesson¶

Dropbox built a beautiful file sync UI, then watched as cloud storage became commoditized. Google Drive, iCloud, OneDrive - all free, all integrated into workflows people already use. The container became worthless; only the data mattered.

Calendars are the same commodity. Google Calendar, Outlook, Apple Calendar - they're free, they're integrated into corporate workflows, and they're already the source of truth. Building another calendar UI is building another Dropbox folder viewer.

What Actually Has Value¶

The AI-generated GTM schedule - Vellocity's unique capability to orchestrate multi-channel go-to-market timelines
Data portability - Getting that schedule into the tools users already live in
Format flexibility - .ics for calendars, API for marketing tools, visual exports for presentations

Design Principle¶

The calendar UI is the least important part. It's a reference view, not the product. The product is the GTM data and its portability.

Architecture Overview¶

┌─────────────────────────────────────────────────────────────────┐
│                     GTM SCHEDULE ENGINE                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                    DATA LAYER                            │   │
│  │         (Vellocity as GTM Orchestration Source)          │   │
│  ├─────────────────────────────────────────────────────────┤   │
│  │  • Social Media Posts      • Campaign Milestones        │   │
│  │  • Content Deliverables    • Partner Outreach Events    │   │
│  │  • Case Study Launches     • Webinar/Event Dates        │   │
│  │  • Email Sequences         • Custom GTM Events          │   │
│  └─────────────────────────────────────────────────────────┘   │
│                              │                                  │
│                              ▼                                  │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                   EXPORT LAYER                           │   │
│  │              (Portability is the Product)                │   │
│  ├─────────────────────────────────────────────────────────┤   │
│  │                                                         │   │
│  │  CALENDAR SYNC          MARKETING TOOLS                 │   │
│  │  ├── .ics (bulk)        ├── HubSpot                     │   │
│  │  ├── Google Calendar    ├── Marketo                     │   │
│  │  ├── Outlook/365        ├── Salesforce                  │   │
│  │  └── Apple Calendar     ├── Hootsuite                   │   │
│  │                         ├── Buffer                      │   │
│  │  VISUAL EXPORTS         └── Metricool                   │   │
│  │  ├── PowerPoint                                         │   │
│  │  ├── Canva              DEVELOPER                       │   │
│  │  ├── PDF Timeline       ├── REST API                    │   │
│  │  ├── Word/Google Docs   ├── Webhooks                    │   │
│  │  └── CSV                └── Zapier/Make                 │   │
│  │                                                         │   │
│  └─────────────────────────────────────────────────────────┘   │
│                              │                                  │
│                              ▼                                  │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                    VIEW LAYER                            │   │
│  │            (Lightweight Reference UI Only)               │   │
│  ├─────────────────────────────────────────────────────────┤   │
│  │  Simple calendar view for quick reference                │   │
│  │  Primary CTA: "Export to..." not "Manage here"          │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Unified GTM Event Data Model¶

Core Schema: `GtmEvent`¶

Every schedulable GTM activity normalizes to this schema:

// Conceptual schema - not Laravel migration syntax
GtmEvent {
    // Identity
    id: uuid
    user_id: foreign_key
    company_id: foreign_key

    // Source tracking (polymorphic)
    eventable_type: string    // 'SocialMediaPost', 'CampaignMilestone', etc.
    eventable_id: uuid        // Reference to source record

    // Core scheduling
    title: string             // Human-readable title
    description: text         // Rich description/content
    scheduled_at: datetime    // When it happens
    end_at: datetime|null     // For duration-based events
    all_day: boolean          // All-day event flag
    timezone: string          // User's timezone

    // Categorization
    event_type: enum [
        'social_post',
        'email_sequence',
        'campaign_milestone',
        'case_study_launch',
        'partner_outreach',
        'webinar',
        'content_publish',
        'custom'
    ]

    // GTM Context
    campaign_id: foreign_key|null
    channel: string|null      // 'linkedin', 'email', 'blog', etc.

    // Visual
    color: string|null        // Hex color for calendar display
    icon: string|null         // Icon identifier

    // Metadata (flexible JSON for source-specific data)
    metadata: json {
        // For social posts:
        platform: 'linkedin',
        post_content: '...',
        media_urls: [...],

        // For email sequences:
        sequence_step: 3,
        subject_line: '...',

        // For campaigns:
        milestone_type: 'launch',
        deliverables: [...]
    }

    // Export tracking
    exported_to: json         // Track where this event has been exported
    external_ids: json        // IDs in external systems (HubSpot, etc.)

    // Timestamps
    created_at: datetime
    updated_at: datetime
}

Event Type Definitions¶

Type	Source	Typical Duration	Channel
`social_post`	SocialMediaPost model	Point-in-time	LinkedIn, X, FB, IG, TikTok
`email_sequence`	AI Agent output	Point-in-time	Email
`campaign_milestone`	Campaign model	Point-in-time or range	Multi-channel
`case_study_launch`	PartnerCentral	Point-in-time	Partner Central
`partner_outreach`	Co-Sell Agent	Point-in-time	Email, LinkedIn
`webinar`	Manual/Integration	Duration (1-2 hrs)	Video
`content_publish`	AI Agent output	Point-in-time	Blog, PR
`custom`	User-created	Flexible	Any

Export Capabilities Matrix¶

Priority Tiers¶

Tier 1: Essential (MVP) - .ics file export (single + bulk) - CSV export - REST API

Tier 2: High Value (Phase 2) - Google Calendar sync - HubSpot integration - PowerPoint/PDF timeline export

Tier 3: Extended (Phase 3) - Outlook/365 sync - Hootsuite, Buffer, Metricool - Salesforce, Marketo - Canva integration - Zapier/Make connectors

Export Format Specifications¶

1. iCalendar (.ics) Export¶

Why it matters: Universal calendar format. Works with Google Calendar, Outlook, Apple Calendar, and virtually every calendar app.

BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Vellocity//GTM Schedule Engine//EN
CALSCALE:GREGORIAN
METHOD:PUBLISH
X-WR-CALNAME:Vellocity GTM Schedule
X-WR-TIMEZONE:America/New_York

BEGIN:VEVENT
UID:gtm-event-{uuid}@vellocity.io
DTSTAMP:20260115T120000Z
DTSTART:20260120T140000Z
DTEND:20260120T143000Z
SUMMARY:LinkedIn Post: AWS re:Invent Recap
DESCRIPTION:Post content here...\n\nChannel: LinkedIn\nCampaign: Q1 Launch
CATEGORIES:SOCIAL_POST,LINKEDIN
URL:https://app.vellocity.io/dashboard/user/social-media/post/{id}
STATUS:CONFIRMED
X-VELLOCITY-EVENT-TYPE:social_post
X-VELLOCITY-CHANNEL:linkedin
X-VELLOCITY-CAMPAIGN-ID:{campaign_uuid}
END:VEVENT

END:VCALENDAR

Export Options: - Single event download - Bulk export (date range) - Filtered export (by type, channel, campaign) - Subscription URL (live-updating .ics feed)

2. CSV Export¶

Why it matters: Universal data format. Import into Excel, Google Sheets, any tool.

event_id,title,description,scheduled_at,end_at,event_type,channel,campaign,status,url
gtm-123,LinkedIn Post: AWS Launch,Full post content...,2026-01-20T14:00:00Z,,social_post,linkedin,Q1 Campaign,scheduled,https://...
gtm-124,Email Sequence Step 1,Subject: Welcome to...,2026-01-21T09:00:00Z,,email_sequence,email,Q1 Campaign,scheduled,https://...

3. PowerPoint Timeline Export¶

Why it matters: GTM timelines are frequently presented to leadership, partners, and stakeholders.

Output: .pptx file with: - Title slide with date range and campaign name - Timeline visualization (horizontal swimlane by channel) - Event detail slides (optional) - Vellocity branding (subtle)

Visual Format:

┌─────────────────────────────────────────────────────────────┐
│  Q1 2026 GTM Timeline: Product Launch Campaign              │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Jan 15    Jan 22    Jan 29    Feb 5     Feb 12    Feb 19  │
│  ──────────────────────────────────────────────────────────│
│                                                             │
│  LinkedIn  ●─────────●─────────●─────────●                 │
│                                                             │
│  Email     ────●─────────●─────────●─────────●             │
│                                                             │
│  Blog      ──────────●───────────────────●                 │
│                                                             │
│  Webinar   ────────────────────●                           │
│                                                             │
└─────────────────────────────────────────────────────────────┘

4. PDF Timeline Export¶

Similar to PowerPoint but as a static, shareable PDF. Useful for: - Email attachments - Partner sharing - Print-ready format

5. JSON API Response¶

{
  "data": [
    {
      "id": "gtm-event-uuid",
      "type": "gtm_event",
      "attributes": {
        "title": "LinkedIn Post: AWS re:Invent Recap",
        "description": "Post content...",
        "scheduled_at": "2026-01-20T14:00:00Z",
        "end_at": null,
        "event_type": "social_post",
        "channel": "linkedin",
        "all_day": false,
        "timezone": "America/New_York",
        "color": "#0077B5",
        "metadata": {
          "platform": "linkedin",
          "post_content": "...",
          "media_urls": []
        }
      },
      "relationships": {
        "campaign": { "data": { "type": "campaign", "id": "..." } },
        "source": { "data": { "type": "social_media_post", "id": "..." } }
      },
      "links": {
        "self": "/api/v1/gtm-events/gtm-event-uuid",
        "source": "/api/v1/social-media-posts/..."
      }
    }
  ],
  "meta": {
    "total": 47,
    "filtered_by": {
      "date_range": ["2026-01-01", "2026-03-31"],
      "event_types": ["social_post", "email_sequence"]
    }
  },
  "links": {
    "ics_download": "/api/v1/gtm-events/export.ics?...",
    "csv_download": "/api/v1/gtm-events/export.csv?..."
  }
}

API Design¶

Base URL¶

https://app.vellocity.io/api/v1/gtm-schedule

Authentication¶

Bearer token (existing API key system)
OAuth 2.0 for third-party integrations

Endpoints¶

List GTM Events¶

GET /api/v1/gtm-schedule/events

Query Parameters:
  - start_date: ISO 8601 date (required)
  - end_date: ISO 8601 date (required)
  - event_types[]: Filter by type (optional, array)
  - channels[]: Filter by channel (optional, array)
  - campaign_id: Filter by campaign (optional)
  - page: Pagination (optional)
  - per_page: Items per page (optional, max 100)

Response: JSON array of GtmEvent objects

Get Single Event¶

GET /api/v1/gtm-schedule/events/{id}

Response: Single GtmEvent object with full metadata

Export Events¶

GET /api/v1/gtm-schedule/export

Query Parameters:
  - format: 'ics' | 'csv' | 'json' (required)
  - start_date: ISO 8601 date (required)
  - end_date: ISO 8601 date (required)
  - event_types[]: Filter by type (optional)
  - channels[]: Filter by channel (optional)
  - campaign_id: Filter by campaign (optional)

Response: File download or JSON based on format

ICS Subscription Feed¶

GET /api/v1/gtm-schedule/feed.ics

Query Parameters:
  - token: User's feed token (required, for authentication)
  - event_types[]: Filter (optional)
  - lookahead_days: How many days ahead (default: 90)

Response: Live .ics feed (subscribe from Google Calendar, Outlook)

Visual Export (Timeline)¶

POST /api/v1/gtm-schedule/export/visual

Body:
{
  "format": "pptx" | "pdf",
  "start_date": "2026-01-01",
  "end_date": "2026-03-31",
  "title": "Q1 2026 GTM Timeline",
  "group_by": "channel" | "campaign" | "week",
  "include_details": true,
  "branding": "minimal" | "full"
}

Response: File download URL (async generation for large exports)

Webhooks¶

Allow users to receive real-time notifications when GTM events are created, updated, or completed.

POST /api/v1/webhooks

Body:
{
  "url": "https://customer-system.com/webhooks/vellocity",
  "events": ["gtm_event.created", "gtm_event.updated", "gtm_event.completed"],
  "filters": {
    "event_types": ["social_post", "email_sequence"]
  }
}

Webhook Payload:

{
  "event": "gtm_event.created",
  "timestamp": "2026-01-15T10:30:00Z",
  "data": {
    "id": "gtm-event-uuid",
    "title": "LinkedIn Post: ...",
    "scheduled_at": "2026-01-20T14:00:00Z",
    "event_type": "social_post",
    "channel": "linkedin"
  }
}

Integration Specifications¶

Google Calendar Sync¶

Approach: OAuth 2.0 + Google Calendar API v3

Sync Behavior: - One-way sync: Vellocity → Google Calendar - Creates a dedicated "Vellocity GTM" calendar in user's account - Events include links back to Vellocity for editing - Color-coded by event type

User Flow: 1. User clicks "Connect Google Calendar" 2. OAuth consent screen 3. Vellocity creates "Vellocity GTM" calendar 4. Initial sync of existing events 5. Ongoing sync as events are created/modified

HubSpot Integration¶

Approach: HubSpot API v3 + OAuth 2.0

Capabilities: - Sync social posts to HubSpot Social - Sync email sequences to HubSpot Marketing Email - Sync campaign milestones to HubSpot Campaigns - Create tasks in HubSpot CRM for partner outreach

Data Mapping: | Vellocity | HubSpot | |-----------|---------| | social_post | Social Post (scheduled) | | email_sequence | Marketing Email | | campaign_milestone | Campaign | | partner_outreach | Task + Contact activity |

Hootsuite Integration¶

Approach: Hootsuite API

Capabilities: - Export social posts directly to Hootsuite scheduler - Maintain scheduling in either system - Bulk export for migration

Zapier Integration¶

Approach: Zapier Developer Platform

Triggers: - New GTM Event Created - GTM Event Updated - GTM Event Completed - Campaign Milestone Reached

Actions: - Create GTM Event - Update GTM Event - Export Events to File

UI Recommendations¶

Calendar View: Minimal, Export-Focused¶

The existing calendar view should be simplified and reframed:

Current Mental Model: "This is where you manage your schedule" New Mental Model: "This is a preview. Export to where you actually work."

UI Changes: 1. Prominent Export Button - Top right, dropdown with all export options 2. Subscription URL - Easy copy for calendar app subscription 3. "Add to Calendar" on each event - One-click .ics download 4. Reduced edit functionality - Link to source (social post, campaign) for editing 5. Integration status badges - Show where events are synced

Visual Hierarchy:

┌─────────────────────────────────────────────────────────────┐
│  GTM Schedule                    [Sync Status] [Export ▼]  │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  📅 Subscribe to this calendar:                      │   │
│  │  [https://app.vellocity.io/api/v1/...] [Copy]       │   │
│  │                                                      │   │
│  │  Connected: Google Calendar ✓  HubSpot ✓            │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  [Calendar Grid - Read-mostly view]                        │
│                                                             │
│  ┌─────┬─────┬─────┬─────┬─────┬─────┬─────┐              │
│  │ Sun │ Mon │ Tue │ Wed │ Thu │ Fri │ Sat │              │
│  ├─────┼─────┼─────┼─────┼─────┼─────┼─────┤              │
│  │     │ 📱  │     │ 📧  │ 📱  │     │     │              │
│  │     │ LI  │     │ Seq │ X   │     │     │              │
│  └─────┴─────┴─────┴─────┴─────┴─────┴─────┘              │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Implementation Roadmap¶

Phase 1: Foundation (MVP)¶

Goal: Establish data model and basic exports

Create GtmEvent model and migration
Polymorphic relationship to source models
All fields from schema above
Build GtmEventAggregator service
Collects events from SocialMediaPost, Campaign, etc.
Normalizes to GtmEvent schema
Caches for performance
Implement export endpoints
.ics export (single + bulk)
CSV export
JSON API
Add ICS subscription feed
Unique URL per user
Filterable by event type
Update calendar UI
Add export dropdown
Add subscription URL display
Simplify editing (link to source)

Phase 2: Integrations¶

Goal: Connect to tools users actually use

Google Calendar sync
OAuth flow
Two-way awareness (not two-way sync)
Dedicated calendar creation
HubSpot integration
OAuth flow
Social post sync
Campaign sync
Visual exports
PowerPoint timeline generation
PDF timeline generation

Phase 3: Extended Ecosystem¶

Goal: Become the GTM orchestration hub

Additional calendar providers
Microsoft 365/Outlook
Apple Calendar (CalDAV)
Marketing tool integrations
Hootsuite, Buffer, Metricool
Marketo, Salesforce
Zapier/Make connectors
Published apps on both platforms
Canva integration
Timeline templates
Campaign visual generation

Success Metrics¶

Adoption¶

% of users who export at least once
% of users with active calendar subscription
Number of connected integrations per user

Engagement¶

Export frequency
Most popular export formats
Integration usage by type

Value¶

Time saved (survey-based)
Reduction in "calendar context switching"
GTM execution velocity improvement

Open Questions¶

Two-way sync: Should we support editing events in Google Calendar and syncing back? Or is one-way (Vellocity → Calendar) sufficient?
Recommendation: Start with one-way. Two-way introduces conflict resolution complexity.
Event ownership: When a social post is exported to Hootsuite, who owns scheduling?
Recommendation: Vellocity is the planning source. Execution tools (Hootsuite) are the execution layer. Export is a handoff.
Real-time vs batch sync: Should Google Calendar sync be real-time or periodic?
Recommendation: Near real-time for Google Calendar (webhook-triggered), batch for file exports.
Multi-user calendars: Should teams see a shared GTM calendar?
Recommendation: Yes, company-level calendar in addition to personal. Phase 2.

Appendix: Competitive Analysis¶

What others do¶

Tool	Calendar Approach
HubSpot	Built-in calendar, limited export
Hootsuite	Social-only calendar, .ics not prominent
Monday.com	Good timeline views, weak export
Notion	Calendar views, no .ics
Asana	Timeline view, limited export

Vellocity Differentiation¶

GTM-specific: Not a generic project calendar
AI-generated schedules: The content comes from AI agents
Export-first: Portability is a feature, not an afterthought
Multi-channel unified view: Social + Email + Content + Events in one timeline

Document Version: 1.0 Created: 2026-01-14 Author: Vellocity Engineering