Technical Documentation

Technical Requirements for Cloud

Complete pull/push specifications for the StellarClose ecosystem development. This document outlines all sources, transformations, destinations, and API integrations required.

StellarSync StellarPost StellarMail

System Architecture

The StellarClose ecosystem consists of three interconnected products that share authentication, user data, and billing infrastructure.

Core Infrastructure Requirements

  • Unified Authentication: Single sign-on across all products
  • Shared User Database: Common user profiles and preferences
  • Centralized Billing: Stripe integration for subscriptions and usage
  • Event Bus: Real-time communication between services
  • CDN: Global content delivery for media assets

Build Phases

1
Foundation
Auth, billing, core APIs
2
StellarSync
Content distribution
3
StellarPost
Video automation

StellarSync: Content Sources

StellarSync must be able to pull content from the following sources:

Source Content Type API/Method Priority
WordPress Blog posts, pages REST API v2 Critical
Squarespace Blog posts, pages Content API Critical
Wix Blog posts REST API High
Ghost Blog posts Content API Medium
Medium Articles RSS Feed Medium
Substack Newsletters RSS Feed Medium
Webflow CMS collections CMS API High
Contentful Content entries Content Delivery API Medium
Google Docs Documents Google Docs API High
Notion Pages, databases Notion API High
HubSpot Blog posts CMS API Medium
Shopify Blog posts, products Storefront API Medium

Content Transformations

Before publishing to destinations, content must be transformed according to platform requirements:

  • Text Truncation: Automatic shortening with smart sentence breaks
  • Hashtag Generation: AI-powered relevant hashtag suggestions
  • Image Optimization: Resize, compress, format conversion per platform
  • Link Shortening: Branded short links with analytics
  • Emoji Enhancement: Optional emoji insertion for engagement
  • Thread Splitting: Long-form content split into Twitter threads
  • Caption Variation: Generate 3-5 caption variants per post

Destinations (Push)

Platform Content Types API Character Limits
Facebook Posts, images, links Graph API v18.0 63,206 chars
Instagram Feed posts, stories, reels Graph API 2,200 chars
LinkedIn Posts, articles, images Marketing API 3,000 chars
X (Twitter) Tweets, threads, images API v2 280 chars
Pinterest Pins, boards API v5 500 chars
TikTok Videos (text overlay) Content API 2,200 chars
YouTube Community posts Data API v3 5,000 chars
Google Business Posts, updates Business Profile API 1,500 chars
Threads Text posts, images API (when available) 500 chars
Bluesky Posts, images AT Protocol 300 chars
Mastodon Toots, images REST API 500 chars
Buffer/Hootsuite Scheduled posts REST APIs Platform-dependent

StellarSync API Requirements

Required API endpoints for StellarSync functionality:

POST /api/sync/sources - Connect a new content source
GET /api/sync/sources/{id}/content - Fetch content from source
POST /api/sync/destinations - Connect a destination platform
POST /api/sync/publish - Publish content to destinations
GET /api/sync/analytics - Get publishing analytics

StellarPost: Video Sources

StellarPost must be able to import and process videos from these sources:

Source Import Method Priority
YouTube URL import, channel sync Critical
TikTok URL import (watermark removal) Critical
Instagram Reels URL import Critical
Vimeo API integration High
Loom API integration High
Direct Upload MP4, MOV, WebM Critical
Google Drive Drive API High
Dropbox Dropbox API Medium

Video Processing Capabilities

Required video processing features:

Viral Moment Detection

  • AI analysis of engagement patterns
  • Automatic highlight clip generation
  • Suggested clip timestamps
  • Emotion/reaction detection for engaging moments

Watermark Removal

  • TikTok watermark detection and removal
  • AI-powered inpainting for clean removal
  • Maintains video quality post-processing

Auto-Captions

  • Speech-to-text transcription (95%+ accuracy)
  • Multiple caption styles (bold, animated, minimal)
  • Word-by-word highlighting
  • Multi-language support

Platform-Specific Resizing

  • 9:16 (1080x1920): TikTok, Reels, Shorts, Stories
  • 1:1 (1080x1080): Instagram Feed, Facebook
  • 16:9 (1920x1080): YouTube, LinkedIn
  • 4:5 (1080x1350): Instagram Feed optimal
  • Smart crop with subject tracking

Video Destinations

Platform Video Types Max Length API
YouTube Shorts, regular videos 60s / 12hr Data API v3
TikTok Videos 10 minutes Content API
Instagram Reels, Stories, Feed 90s / 60s / 60min Graph API
Facebook Reels, Stories, Feed 90s / 20s / 240min Graph API
LinkedIn Native video 10 minutes Marketing API
X (Twitter) Video tweets 2:20 API v2
Pinterest Idea Pins, Video Pins 60s API v5

StellarPost API Requirements

POST /api/post/import - Import video from URL or upload
POST /api/post/process - Apply transformations (captions, resize, etc.)
GET /api/post/clips/{videoId} - Get AI-detected viral moments
POST /api/post/publish - Publish to destination platforms
GET /api/post/analytics/{videoId} - Get cross-platform analytics

StellarMail: Verification Engine

Real-time email verification to reduce bounce rates from 38% to under 2%.

Verification Checks

  1. Syntax Validation: RFC 5322 compliance check
  2. Domain Verification: MX record lookup, DNS validation
  3. Mailbox Verification: SMTP handshake without sending
  4. Disposable Detection: Check against 100k+ disposable domains
  5. Role-Based Detection: Identify info@, support@, admin@, etc.
  6. Catch-All Detection: Identify domains that accept all addresses
  7. Spam Trap Detection: Known spam trap identification
  8. Deliverability Score: 0-100 confidence rating

Response Times

  • Single verification: < 1 second
  • Bulk verification: 10,000 emails in < 5 minutes
  • Real-time API: < 200ms response

StellarMail API Requirements

POST /api/mail/verify - Verify single email address
POST /api/mail/verify/bulk - Bulk verification (up to 100k)
GET /api/mail/verify/status/{jobId} - Check bulk verification status
GET /api/mail/analytics - Verification analytics and stats 
// Example verification response
{
  "email": "john@example.com",
  "valid": true,
  "score": 95,
  "checks": {
    "syntax": "pass",
    "domain": "pass",
    "mailbox": "pass",
    "disposable": false,
    "role_based": false,
    "catch_all": false,
    "spam_trap": false
  },
  "suggestion": null,
  "verified_at": "2025-01-03T10:30:00Z"
}

Authentication

All APIs use OAuth 2.0 with JWT tokens. Unified authentication across all products.

// Authorization header
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

// Token payload includes:
{
  "sub": "user_12345",
  "products": ["sync", "post", "mail"],
  "plan": "pro",
  "exp": 1704326400
}

Webhooks

Real-time notifications for async operations:

  • sync.content.published - Content published to destination
  • sync.content.failed - Publishing failed
  • post.video.processed - Video processing complete
  • post.video.published - Video published to destination
  • mail.bulk.completed - Bulk verification job complete

Rate Limits

Plan Requests/minute Burst
Starter 60 100
Pro 300 500
Team 1,000 2,000