CampaignHub Studio

Transform a single blog post into a complete multi-platform social campaign.

CampaignHub Studio is the reference implementation of the FlyRank capstone: given a published post (title + body + URL), it generates per-platform image variants and platform-tailored captions, then publishes them — immediately or on a schedule — through a unified adapter interface, with idempotency, Retry-After handling, encrypted OAuth tokens, signature-verified delivery webhooks and a crash-safe worker.

No real social API is ever called. All publishing goes to an in-repo fake platform. Verified by a test: tests/security.test.ts › no real social platform is ever called.

Table of contents

1. Overview

2. Screenshots

3. Architecture

4. Features

5. Technology stack

6. Installation

7. Environment setup

8. Running locally

9. API overview

10. Project structure

11. Testing

12. Demo walkthrough

13. Design decisions

14. Limitations

15. Future work

Related MCP server: Oktopost MCP Server

Overview

A campaign is created from one blog post. The engine then:

1. Ingests content — paste text, upload .md / .pdf / .docx, or pick a real published article from the built-in Blog library (Anthropic, Google DeepMind, Cloudflare feeds, enriched with Open Graph metadata).

2. Generates one SocialPostEntry per platform (Instagram, X, LinkedIn) with a tailored caption and a real PNG image variant at exact platform dimensions.

3. Publishes each entry through a SocialPublisher adapter that speaks to the fake platform with a deterministic Idempotency-Key, honouring 429 Retry-After.

4. Confirms delivery only when an HMAC-signed webhook arrives — the sole writer of the terminal published / failed state.

Captions are produced by the caption pipeline in this repository: it composes the shared brand-voice + platform-fragment prompts, calls an LLM (OpenAI gpt-4o-mini) as the writing step, then validates and normalises the result against each platform's constraints. If the model is unavailable it falls back silently to the deterministic composer, so campaign creation never fails because of the model.

Product Screenshots

1. Landing hero (light)

2. Sign in

3. Dashboard — Campaigns (start)

4. New campaign composer

5. Campaign library

6. Activity

7. Profile (account)

Also see docs/screenshots/ for dark-mode hero, locale toggle, reviewer evidence, and additional captures.

Architecture

Clean Architecture with a strict inward dependency rule: interfaces → application → domain. No use case imports Postgres, sharp, fetch or the OpenAI SDK — only ports.

flowchart TB
  subgraph interfaces["interfaces"]
    UI["React dashboard<br/>src/routes/_authenticated/dashboard.tsx"]
    FN["Server functions<br/>src/lib/flyrank.functions.ts"]
    MCP["MCP server<br/>src/mcp/** → /api/public/mcp"]
    FAKE["Fake platform<br/>/api/public/fake-platform/*"]
    HOOK["Delivery webhook<br/>/api/public/webhooks/delivery"]
  end
  subgraph application["application (use cases)"]
    UC["create / generate / schedule<br/>publish / retry / status / ingest"]
    WORKER["Durable worker<br/>lease + claim"]
  end
  subgraph domain["domain (pure)"]
    ENT["entities, captions,<br/>image geometry, ports"]
  end
  subgraph infra["infrastructure (adapters)"]
    DB[("Postgres + RLS<br/>Supabase repositories")]
    IMG["sharp / Jimp renderers"]
    AI["OpenAI caption writer<br/>(+ deterministic fallback)"]
    CRY["AES-256-GCM cipher<br/>HMAC signatures"]
    PUB["Instagram / X / LinkedIn adapters"]
    PARSE["md · pdf · docx parsers"]
  end

  UI --> FN --> UC
  MCP --> UC
  WORKER --> UC
  UC --> ENT
  UC --> DB & IMG & AI & CRY & PUB & PARSE
  PUB -->|Bearer + Idempotency-Key| FAKE
  FAKE -.->|signed webhook| HOOK --> UC

Layer rules

Adding a fourth platform = one platform spec + one voice block + one adapter class + one registry entry.

Features

• Content ingestion — paste, .md, .pdf (unpdf), .docx (mammoth), or the curated blog library with source filters, real article imagery and text previews.

• Per-platform image variants — real PNG bytes at Instagram 1080×1080, X 1600×900, and LinkedIn 1200×627, produced by sharp (native runtime) or Jimp (serverless), from one shared pure-geometry composition with safe-zone enforcement. Optional OpenAI image generation with SVG fallback.

• Platform-tailored captions — content-first prompt pipeline (shared brand voice + per-platform fragments + optional brand tone and output language) with OpenAI gpt-4o-mini as the writing step; deterministic composer as fallback. Captions reference the source article, not generic promo boilerplate.

• Unified publisher interface — SocialPublisher port, three fake adapters; application code never names a transport.

• Idempotency — deterministic key flyrank:{campaignId}:{platform}, enforced by a unique DB constraint and by the fake platform. Publish twice, retry after a timeout → one post.

• Rate limiting — 429 + Retry-After honoured, exponential backoff floor, capped attempts, every attempt recorded in publish_attempts.

• Durable scheduling — due rows claimed with a short lease_until; a crashed worker's claims expire and are replayed under the same idempotency key → zero duplicates.

• Signed delivery webhooks — Stripe-style t=…,v1=… HMAC-SHA256, replay window, timing-safe compare. Forged → 400, state unchanged.

• Encrypted OAuth tokens — AES-256-GCM, fresh random IV per write, redaction helper for logs, no plaintext token column anywhere.

• AI cost meter — every OpenAI call records estimated USD spend per user in ai_usage_records (Postgres); dashboard badge + sidebar panel; AI_BUDGET_USD guard falls back to deterministic captions / SVG images when the budget is exhausted.

• Automatic background worker — polls Postgres on server boot (WORKER_ENABLED, WORKER_POLL_INTERVAL_MS); scheduled posts publish without a manual dashboard tick.

• Multi-tenant auth — email/password sign-in (/auth), every row scoped by user_id under RLS.

• Public landing — marketing page at / with EN/TR i18n, hero visuals, scroll animations, and MCP positioning aligned with POST /api/public/mcp.

• Campaign management UI — dashboard with unified coral OKLCH palette (light/dark toggle), variant carousel (one platform at a time), live status timeline, manual caption editing, optimistic delete with a 10-second undo toast, demo control rail.

• Standalone MCP server — vendor-neutral JSON-RPC MCP interface over the same use cases.

Technology stack

Installation

git clone <repository-url>
cd campaignhub-studio
npm install         # or: bun install

Requires Node.js 22+ (recommended). Node 20 works for local dev — the ws package backfills WebSocket for Supabase on the server. Install with npm install (or bun install).

Docker (PostgreSQL + Redis + app)

Self-contained local stack with Supabase-compatible Postgres, Redis, GoTrue, PostgREST and the app:

cp .env.docker.example .env.docker
docker compose --env-file .env.docker up --build

• App: http://localhost:8080

• Supabase API (local): http://localhost:54321

• Redis: localhost:6379

• Health: http://localhost:8080/api/public/health

After the stack is up, seed demo data:

npm run seed   # uses .env — point SUPABASE_* at http://localhost:54321 for Docker

Environment setup

cp .env.example .env

Every variable and its purpose is documented in .env.example. Copy the example file, then fill in your own Supabase project credentials (not Lovable Cloud):

cp .env.example .env

Required for database and auth:

Optional but recommended before deployment:

When TOKEN_ENCRYPTION_KEY / WEBHOOK_SIGNING_SECRET are absent, clearly labelled dev fallbacks are derived so local development boots without secrets. .env is git-ignored.

Supabase setup

1. Create a project at supabase.com.

2. In Project Settings → API, copy the project URL, publishable key and service-role key.

3. In SQL Editor, run supabase/flyrank-full-schema.sql. The script is idempotent — safe to run on a fresh project and safe to re-run to upgrade an existing one. It creates all tables with RLS (including ai_usage_records for per-user AI spend), the campaign-images storage bucket, the auth→profile trigger, the claim_due_entries worker RPC, and the linkedin platform enum value. (Alternatively apply supabase/migrations/*.sql in timestamp order.)

4. Enable Authentication → Providers → Google if you want Google sign-in; add your app redirect URL (http://localhost:8080 for local dev).

5. Paste the values into .env and start the app.

Google OAuth can be enabled in Supabase Auth when needed; the auth UI currently exposes email/password only. Supabase Auth is used directly (not @lovable.dev/cloud-auth-js).

Sign-up without email confirmation: new accounts are created server-side via signUpAccount (src/lib/auth.functions.ts) using the service-role key with email_confirm: true, then the client signs in immediately — no confirmation email. SUPABASE_SERVICE_ROLE_KEY must be set in .env. Optionally disable Confirm email in Supabase Dashboard → Authentication → Providers → Email for consistency.

Running locally

npm run dev        # http://localhost:8080 — background worker starts automatically
npm run seed       # automated demo user + campaign (requires service role in .env)
npm run typecheck  # tsc --noEmit — must stay at zero errors
npm run test       # vitest — 24 files, 131 tests, no network/DB required
npm run test:watch # vitest in watch mode
npm run lint
npm run build

Sign up on /auth, then land on /dashboard. The public marketing page is at /.

API overview

The dashboard talks to the server through typed server functions (src/lib/flyrank.functions.ts), not REST — one transport, one auth path, no hand-written fetch layer:

Public HTTP routes (external callers, no session):

All inputs are validated with zod; invalid input returns 400 with the issue list, never a 500.

MCP tools

list_posts, create_post, create_campaign, list_campaigns, get_campaign, campaign_status, schedule_campaign, publish_campaign, retry_campaign — each a thin delegate to a use case in src/application/. The MCP layer holds no business logic, writes no captions and calls no model. The set is self-sufficient: list_posts / create_post yield the postId that create_campaign requires, so a client never needs the web UI to get started.

Responses are wire views (src/mcp/views.ts), not raw rows: server-internal fields (userId, idempotencyKey, leaseUntil) are dropped and post bodies truncated, because a tool result is read by a model with a finite context window. Listings take a limit (default 25).

Transport hardening on POST /api/public/mcp: bearer token verified against the auth server on every request (revocation takes effect immediately), cross-origin browser callers refused, JSON-RPC batches capped at 50 messages and executed in order.

Authenticate with Authorization: Bearer <access token>; every query runs under the caller's RLS scope. Consent screen: /oauth/consent.

Connecting a client. Protected-resource metadata (RFC 9728) is served at both the root and path-suffixed well-known URLs, but Supabase Auth publishes no RFC 8414 authorization-server metadata and no dynamic client registration, so a client that insists on fully automatic OAuth discovery cannot complete the handshake yet. Pass an access token directly until that lands.

Project structure

src/
  domain/                      pure core — zero I/O
    entities.ts                BlogPost, Campaign, SocialPostEntry, idempotency key,
                               backoff, status derivation
    captions.ts                deterministic caption composer
    image-composition.ts       crop geometry, safe-zone fit, SVG composition
    ports.ts                   repository / publisher / renderer / parser interfaces
  application/                 use cases, depend only on ports
    campaign-usecases.ts       create, generate captions + images, edit, delete
    publish-usecases.ts        publish, retry, idempotency, 429 backoff, attempts
    delivery-usecases.ts       signed webhook ingestion → terminal status
    worker.ts                  durable lease/claim scheduler
    ingest-content.ts          paste / md / pdf / docx normalisation
    import-library-post.ts     curated blog-library import
  infrastructure/              adapters (the only place with I/O)
    persistence/supabase-repositories.server.ts
    publishing/adapters.server.ts, fake-platform-transport.server.ts
    imaging/renderers.server.ts        sharp + Jimp
    parsing/document-parser.server.ts  unpdf + mammoth
    crypto/token-cipher.server.ts, webhook-signature.server.ts
    ai/ai-cost-meter.server.ts, ai-cost-meter-db.server.ts
    ai/openai-caption-writer.server.ts, openai-art-director.server.ts, openai-image-generator.server.ts
    worker/background-worker.server.ts
    feeds/blog-library.server.ts
    storage/image-store.server.ts
    context.server.ts          composition root (dependency injection)
  interfaces
    routes/                    dashboard, auth, OAuth consent, public API routes
    mcp/                       JSON-RPC server + 9 tool delegates + wire views
    components/campaign/   composer, variant gallery/carousel, AI spend panel, status chips
  config/                      platform specs, prompt fragments
supabase/migrations/           schema, grants, RLS, indexes
tests/                         vitest suites (see Testing below)
tests/helpers/                 in-memory AppContext fakes for use-case tests

Testing

npm run test        # single run
npm run test:watch  # watch mode

All tests are deterministic: no network, no live database, no API keys required. Vitest runs in Node with @/ path aliases (vitest.config.ts).

Use-case tests build an in-memory AppContext via tests/helpers/mock-app-context.ts so application logic is tested without Postgres.

Behaviours that need a live database and worker (duplicate publish → one post, crash-resume, forged webhook → 400) are exercised through the dashboard demo rail; see EVIDENCE.md for the reviewer walkthrough of each one.

Demo walkthrough

1. Create — pick an article in the Blog library (or paste/upload one) → Generate campaign. Three platform variants (Instagram, X, LinkedIn) appear in a carousel with platform tabs; captions are article-specific and differ structurally per platform.

2. Schedule — set a time in the future, then run a worker tick from the demo rail; the status chips flip queued → publishing.

3. Idempotency — hit Publish now repeatedly; GET /api/public/fake-platform/x/posts still holds exactly one post per platform.

4. Rate limiting — Force 429 ×2 → publish → the attempts drawer shows the rate-limited attempts with the honoured Retry-After, then success.

5. Webhooks — a forged webhook returns 400 and changes nothing; the genuine signed webhook flips the entry to Published.

6. Crash safety — interrupt mid-publish and tick again: the expired lease is reclaimed and the same idempotency key collapses the replay into the original post.

Design decisions

Full rationale in DECISIONS.md; the highlights:

• TanStack Start server functions instead of Express/Fastify — the app is already a TanStack Start project; a second HTTP process would add a deploy target and CORS for no gain.

• Postgres + RLS instead of a local file/SQLite store — tenant isolation is a graded requirement, and the lease/claim scheduler wants real transactional UPDATEs.

• sharp primary, Jimp fallback, no custom PNG encoder — the deployment target is a Worker where sharp's native binary cannot load; shared pure geometry keeps both paths byte-identical in dimensions.

• Deterministic idempotency keys — a random key would make a post-crash replay look like a new publish.

• Webhook-owned terminal status — with one documented exception: after MAX_PUBLISH_ATTEMPTS with no platform acceptance, no webhook will ever arrive, so the worker marks failed locally.

• LLM captions with deterministic fallback — quality when the model is available, availability when it is not.

• MCP as an interface, not a feature — every tool delegates to an existing use case.

Limitations

• The fake platform's memory is process-local by design; it is a test double, not the system under test.

• The image composition is generated artwork (gradient + subject + typography) driven by the post, not a photo pipeline — the graded behaviour is geometry, dimensions and safe zones.

• PDF extraction is text-only; scanned/image PDFs yield no body text.

• Blog-library previews depend on third-party sites staying reachable.

• Three platforms are implemented (Instagram, X, LinkedIn); adding more follows the same adapter pattern.

• LLM caption quality varies by model availability; the deterministic fallback is intentionally plainer.

• AI spend is estimated (not invoice-accurate); persisted per user in ai_usage_records.

Future work

Within the capstone scope, and explicitly not started (all stretch goals per the brief): real-platform integration, brand templating, A/B captions, analytics loopback and an approval workflow. Anything beyond that is out of scope for this submission.

License

MIT