Skip to content

Every analytics tool wants a subscription. And your data. I built Twiligent instead. YouTube stats. Instagram stats. One dashboard. Runs locally on your machine.

6.4 KB
Raw Blame

Data Flow - Instagram Publishing

Immediate Publishing

User selects account + uploads media + fills caption
        │
        ▼
1. Frontend: Upload media to Cloudinary
   api.getCloudinaryConfig() -> GET /api/cloudinary-config
   -> returns { cloudName, uploadPreset }, or 503 when the Worker has no Cloudinary settings
   
   Browser uploads directly to Cloudinary using unsigned preset (api.uploadToCloudinary)
   -> Cloudinary returns public URL (e.g., https://res.cloudinary.com/cloud/image/upload/...)
        │
        ▼
2. Frontend: Create media container
   api.createIGContainer(accountId, { mediaUrl, caption, mediaType, ... })
   -> POST /api/accounts/:id/ig-publish
   -> Backend: publishing.createContainer() -> buildMediaParams() and createMediaContainer()
       POST https://graph.instagram.com/v25.0/{igUserId}/media
       params: { image_url|video_url, caption, media_type, access_token }
   -> 404 when the account is not an Instagram account of this user, 400 when it has no stored token
   -> Returns { containerId }
        │
        ▼
3. For REELS or STORIES: poll container status (images skip this step)
   api.getIGContainerStatus(containerId, accountId)
   -> GET /api/ig-container/:containerId/status?accountId=:id
   -> Backend: GET https://graph.instagram.com/v25.0/{containerId}?fields=status_code,status
   -> accountId is required (400 without it); the account must be an Instagram account with a token
   -> Poll every 3 seconds, up to 30 times (about 90 seconds); after that the post fails
      with a "took too long" message, in single and bulk publishing alike, because
      publishing an unfinished container fails anyway
   -> Wait for status_code = 'FINISHED'; while waiting the page shows the seconds waited
      against the usual minute, and a single post offers Stop waiting (an AbortSignal that
      ends the wait; the container is left unpublished)
   -> ERROR -> ContainerFailedError with a plain message (try a shorter H.264 MP4), mark as failed
   -> EXPIRED -> ContainerFailedError: publish again
        │
        ▼
4. Frontend: Publish the container
   api.publishIGContainer(accountId, containerId)
   -> POST /api/accounts/:id/ig-media-publish
   -> Backend: POST https://graph.instagram.com/v25.0/{igUserId}/media_publish
       body: { creation_id: containerId, access_token }
   -> Returns { mediaId }
        │
        ▼
5. Frontend: Show the result screen (Published, Post scheduled or the failure with Try again,
   which keeps the file and fields); its heading takes focus. Problems found before upload
   (account, type, file, schedule) are shown under their field, not in a toast

Scheduled Publishing

User creates a scheduled post
        │
        ▼
1. Frontend: api.createScheduledPost({ accountId, scheduledAt, mediaUrl, caption, ... })
   -> POST /api/scheduled-posts
   -> Backend: scheduledPosts.create(userId, request) -> posts.create(post, userId)
       (400 unless scheduledAt is a future date)
       INSERT INTO scheduled_posts (id, user_id, account_id, status='pending', scheduled_at, data)
        │
        ▼
2. A scheduler run starts:
   A. Cloudflare Worker cron, every 15 minutes -> runScheduledJob() -> scheduledPublisher.publishDue()
   B. GitHub Actions, asked for at minutes 7, 22, 37 and 52 but often started hours late
      -> node scripts/publish-scheduled.ts -> direct Supabase REST calls
        │
        ▼
3. Scheduler queries due posts and stale claims:
   SELECT * FROM scheduled_posts WHERE status='pending' AND scheduled_at <= now()
   SELECT * FROM scheduled_posts WHERE status='publishing' AND claimed_at < now() - 20 minutes
        │
        ▼
4. For each candidate:
   a. UPDATE scheduled_posts SET status='publishing', claimed_at=now(), attempts=attempts+1
      WHERE id=:id AND attempts=:attempts AND (status='pending' OR claimed_at=:expiredClaim)
      (Only one run gets the row; a stale claim is taken over by the next run)

   b. SELECT account WHERE id=:accountId
      (Gets the accessToken from accounts.data; a missing account, an account on another
      platform or a missing token fails the post with a message that says which)

   c. If data.containerId is saved, read its status_code first: PUBLISHED marks the post
      published, FINISHED publishes that container, EXPIRED creates a new one, ERROR fails it

   d. Execute the publish pipeline (same as immediate publishing, steps 2-4 above), saving
      data.containerId right after the container is created; the schedulers poll a Reel or
      Story up to 60 times (3 minutes)

   e. On success: UPDATE SET status='published', data.publishedMediaId=:id, data.publishedAt=:ts

   f. On failure: read the container status if there is one. PUBLISHED marks the post
      published; an unreadable status leaves it publishing for a run after the lease.
      A temporary failure sets status='pending' with data.error, up to 3 attempts;
      a definite failure or the third attempt sets status='failed', data.error=:message

The full failure table is in docs/architecture/data-flows/SCHEDULING.md.

Media Type Differences

Type Container params Status polling Notes
IMAGE image_url, optional alt_text, location_id, user_tags No Publishes immediately
REELS video_url, media_type=REELS, optional share_to_feed, cover_url, audio_name, thumb_offset, collaborators Yes Requires FINISHED before publish; the form takes the thumbnail time in seconds and sends thumb_offset in milliseconds
STORIES video_url or image_url, media_type=STORIES, optional user_tags Yes (for video) Images publish immediately

Error States

Error Cause Recovery
Container ERROR Instagram processing failed (bad codec, too long, etc.) User must re-upload
Container EXPIRED >24 hours since container was created User must re-create container
media_publish rejected Usually quota exceeded or invalid containerId; the Worker answers 502 (UPSTREAM_ERROR) with Instagram's message Check publishing limit
Processing timeout The container was still processing after the last poll A scheduled post is retried on the next run, up to 3 attempts; otherwise try again later, or use a shorter or smaller video
status=failed in scheduled post Any of the above, plus accessToken expired, or a temporary failure on the third attempt Re-connect the account if needed, then schedule the post again