Hootsuite Reference Architecture

Architecture

┌──────────────────────────────────────┐
│         Your Application              │
├──────────────────────────────────────┤
│  Content Manager → Scheduler → Publisher │
├──────────────────────────────────────┤
│      Hootsuite API Client             │
│  (OAuth, Token Refresh, Rate Limit)   │
├──────────────────────────────────────┤
│      Hootsuite REST API v1            │
│  platform.hootsuite.com/v1/           │
└──────────────────────────────────────┘

Project Structure

hootsuite-integration/
├── src/
│   ├── hootsuite/
│   │   ├── client.ts        # API client with token management
│   │   ├── auth.ts          # OAuth 2.0 flow
│   │   ├── publishing.ts    # Message scheduling + media
│   │   ├── analytics.ts     # Metrics + URL shortening
│   │   └── types.ts         # TypeScript interfaces
│   ├── services/
│   │   ├── scheduler.ts     # Content calendar logic
│   │   ├── content.ts       # Post formatting per platform
│   │   └── media.ts         # Media processing + upload
│   ├── api/
│   │   └── schedule.ts      # REST endpoint
│   └── store/
│       └── tokens.ts        # Persistent token storage
├── tests/
│   ├── unit/
│   └── fixtures/
└── .env.example

Key Decisions

Decision	Recommendation	Why
Token storage	Database/KV, not env vars	Refresh tokens change each use
Scheduling	Queue-based, not direct API	Rate limit compliance
Media upload	Pre-process images	Reduce REJECTED media states
Multi-profile	Batch schedule per profile	Separate errors per profile

Overview

This architecture separates draft creation, approval, audience validation, scoped scheduling, aggregate observability, and cancellation/rollback. Post copy and media stay inside approved publishing boundaries and never become telemetry.

Prerequisites

A profile/account owner, audience policy, approval authority, destination allowlist, and owner for every publish edge.
Separate sandbox/staging/production configuration and documented rollback for client, scheduler, queue, and credential controls.

Instructions

Map every trigger-to-profile path with owner, audience, approval state, allowed operation, idempotency, observability, and rollback.
Begin with draft-only sandbox fixtures and fail closed on unknown profile, audience, destination, or approval state.
Make scheduling idempotent and bounded; quarantine uncertainty rather than posting, resubmitting, or exporting copy for debugging.
Canary one draft-only profile with aggregate signals before promotion and retain the previous revision.
Re-evaluate controls after changes to accounts, audiences, credentials, schedules, or approval policy.

Output

Produce an architecture record with owners, opaque profile IDs, policy revisions, idempotency/retry behavior, observability, test evidence, and rollback revision. Exclude copy, media, handles, tokens, and identities.

Error Handling

Stop on unknown profile/audience, failed approval assertion, public-post path in a canary, or non-idempotent retry. Quarantine the event and restore the prior controlled path.

Examples

source=ci-synthetic; profile=sandbox-brand; audience=r4; approval=required; action=draft-only; probe=pass; rollback=arch-r17 is a reviewable architecture receipt.

Resources

Next Steps

Start with hootsuite-install-auth to set up OAuth.

hootsuite-reference-architecture