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.
1---2name: hootsuite-reference-architecture3description: Implement Hootsuite reference architecture with best-practice project layout. Use when designing new Hootsuite integrations, reviewing project structure, or establishing architecture standards for Hootsuite applications. Trigger with phrases like "hootsuite architecture", "hootsuite best practices", "hootsuite project structure", "how to organize hootsuite", "hootsuite layout".4license: MIT5---6# Hootsuite Reference Architecture
7
8## Architecture
9
10```
11┌──────────────────────────────────────┐
12│ Your Application │
13├──────────────────────────────────────┤
14│ Content Manager → Scheduler → Publisher │
15├──────────────────────────────────────┤
16│ Hootsuite API Client │
17│ (OAuth, Token Refresh, Rate Limit) │
18├──────────────────────────────────────┤
19│ Hootsuite REST API v1 │
20│ platform.hootsuite.com/v1/ │
21└──────────────────────────────────────┘
22```
23
24## Project Structure
25
26```
27hootsuite-integration/
28├── src/
29│ ├── hootsuite/
30│ │ ├── client.ts # API client with token management
31│ │ ├── auth.ts # OAuth 2.0 flow
32│ │ ├── publishing.ts # Message scheduling + media
33│ │ ├── analytics.ts # Metrics + URL shortening
34│ │ └── types.ts # TypeScript interfaces
35│ ├── services/
36│ │ ├── scheduler.ts # Content calendar logic
37│ │ ├── content.ts # Post formatting per platform
38│ │ └── media.ts # Media processing + upload
39│ ├── api/
40│ │ └── schedule.ts # REST endpoint
41│ └── store/
42│ └── tokens.ts # Persistent token storage
43├── tests/
44│ ├── unit/
45│ └── fixtures/
46└── .env.example
47```
48
49## Key Decisions
50
51| Decision | Recommendation | Why |
52|----------|---------------|-----|
53| Token storage | Database/KV, not env vars | Refresh tokens change each use |
54| Scheduling | Queue-based, not direct API | Rate limit compliance |
55| Media upload | Pre-process images | Reduce REJECTED media states |
56| Multi-profile | Batch schedule per profile | Separate errors per profile |
57
58## Overview
59
60This 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.
61
62## Prerequisites
63
64- A profile/account owner, audience policy, approval authority, destination allowlist, and owner for every publish edge.
65- Separate sandbox/staging/production configuration and documented rollback for client, scheduler, queue, and credential controls.
66
67## Instructions
68
691. Map every trigger-to-profile path with owner, audience, approval state, allowed operation, idempotency, observability, and rollback.
702. Begin with draft-only sandbox fixtures and fail closed on unknown profile, audience, destination, or approval state.
713. Make scheduling idempotent and bounded; quarantine uncertainty rather than posting, resubmitting, or exporting copy for debugging.
724. Canary one draft-only profile with aggregate signals before promotion and retain the previous revision.
735. Re-evaluate controls after changes to accounts, audiences, credentials, schedules, or approval policy.
74
75## Output
76
77Produce 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.
78
79## Error Handling
80
81Stop 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.
82
83## Examples
84
85`source=ci-synthetic; profile=sandbox-brand; audience=r4; approval=required; action=draft-only; probe=pass; rollback=arch-r17` is a reviewable architecture receipt.
86
87## Resources
88
89- [Hootsuite Developer Platform](https://developer.hootsuite.com)
90- [API Overview](https://developer.hootsuite.com/docs/api-overview)
91
92## Next Steps
93
94Start with `hootsuite-install-auth` to set up OAuth.
gabrielmoreira