Architecture & Loops

Social Automation describes what the pipeline does. This page describes who talks to whom, in which direction, and which of the three loops a given post actually travels. If you are wiring a new channel, adding a cron, or wondering why a draft did not publish, start here.

The five actors

The asymmetry that shapes everything

Vercel can never call into Hermes. Hermes listens on localhost behind a home connection — there is no public route to it. Two consequences that explain most of the surprising behaviour:

• The Hermes row in the Hub's status dialog is red in production and green only on Abdout's machine. That is correct, not a bug.
• SOCIAL_DRAFT_SOURCE=hermes (the default) is a half-loop on Vercel — the cron can hand a drafting request out, but the reply never comes back in-band.

Loop C below exists precisely to invert that arrow.

                    ┌──────────────── writes copy ─────────────────┐
                    │                                              │
              Claude Code                                    Marketing team
             (/social skill)                            Abdout · Samia · Ali
                    │                                         │        ▲
                    │ paste                          approves │        │ reviews
                    ▼                                         ▼        │
   ┌────────────────────────────────────────────────────────────────────────┐
   │                        kun  ·  Vercel  ·  public                       │
   │   /social Hub    /api/social/cron    /api/social/publish   /relay      │
   │                        holds every platform token                      │
   └───────────┬──────────────────────────────────────────────▲────────────┘
               │ direct API (Graph, Bot)                      │ POST + CRON_SECRET
               ▼                                              │
      ┌─────────────────┐                          ┌──────────────────────┐
      │   Platforms     │◄──── Slack adapter ──────│  Hermes · localhost  │
      │ Facebook·Telegram│                         │  (outbound only)     │
      └─────────────────┘                          └──────────────────────┘

The three loops

They differ in one thing: where the human sits, and who holds the tokens.

Loop A — Hub (human-composed)

The everyday lane. Nothing scheduled, nothing autonomous.

Claude Code (/social) ──► human pastes into the Hub's Publish tab ──► brand + channels
   └─ drafts AR/EN copy          └─ optional media URL from /higgs
                                       │
   ── or, without a session ──►  Hub's Draft tab ──► SocialDraftRequest (pending)
                                       │                      ▲        │
                                       │        answers ──────┘        │ polls
                                       │   Claude Code, Max pool       │
                                       │   (`draft` queue mode)        │
                                       │◄─────────────────────────────-┘
                                       │   "Use Arabic" → Publish tab, copy in the editor
                                       ▼
                            publishPostDirect (Server Action)
                            contributor re-check → Zod → deliverPost
                                       │
                    ┌──────────────────┼──────────────────┐
                    ▼                  ▼                  ▼
              Telegram Bot API   Facebook Graph API   Hermes /webhook
                                                       (Slack, …)

The second path is Loop C's inverted arrow again, for the same reason: Vercel holds no funded Anthropic key (D-20260730 shipped, then 401'd), so the machine that writes reaches in rather than being called. Asynchronous — minutes, and only while some session is draining the queue.

• Human sits: at the editor, before Publish.
• Guard: session + contributor allowlist re-checked inside the action (JWT sessions outlive removal from the allowlist).
• Result: per-channel — a fan-out that half-lands reports exactly which channel failed and why.

Loop B — Cron (draft-and-approve)

The only scheduled lane today. Drafts unattended; never publishes unattended.

Vercel Cron 06:00 UTC ──► GET /api/social/cron   (Bearer CRON_SECRET, timing-safe)
                               │
                               ▼
                     for each SOCIAL_AUTOPOST_PRODUCTS
                               │
                          draftPost()  ── SOCIAL_DRAFT_SOURCE
                               │          ├─ "hermes"    → hands the ask out (half-loop on Vercel)
                               │          └─ "anthropic" → drafts server-side (opt-in, costs money)
                               ▼
                     sendReview() → PRIVATE review channel
                     message carries a signed 12h one-click link
                               │
                     ┌─────────┴─────────┐
                     │   human clicks    │  ◄── the gate
                     └─────────┬─────────┘
                               ▼
                  GET /api/social/publish?token=…
                  verify HMAC → deliverPost → echo outcome back to review channel

• Human sits: in the review channel, clicking the link.
• Opt-in: SOCIAL_AUTOPOST_PRODUCTS is empty by default — the cron authenticates, does nothing, and says so.
• Single use. The link names a SocialVariant, and publishing is a conditional status transition, so a second click finds the row no longer pending and gets a 409. Two people clicking at the same moment race on one UPDATE and exactly one wins. Until persistence landed (2026-07-26) the link was replayable and clicking twice genuinely posted twice.
• Still true: anyone holding a live link can publish it once. Keep the review channel private.

Loop C — Hermes inbound relay

Written because Loop B's Hermes path can't complete on Vercel. This one inverts the arrow.

Hermes (Abdout's desktop, its own cron)
   └─ drafts copy ──► shows it in Slack ──► human approves in Slack   ◄── the gate
                                                  │
                                                  ▼
                              POST /api/social/relay   (Bearer CRON_SECRET)
                              { product, text, channels? }
                                                  │
                                                  ▼
                              kun delivers with ITS OWN tokens

Why it matters: Hermes never holds a Facebook Page token. The secrets stay in Vercel env, and Hermes only ever sends approved text. The bearer secret means "a human already said yes" — so whoever holds CRON_SECRET can post to a brand page. Treat it as a publishing credential.

generate → approve → schedule → publish

The chain the whole system is built around, and where each stage actually lives:

Scheduling, persistence, and the single-use link

Scheduling is real now. The review queue's approve-mode setting (or the composer's date-time field) decides the moment, approveDraft/schedulePost writes one scheduled variant per channel, and the drain (GitHub Actions, every ~15 minutes) claims and publishes each one when its moment passes — three bounded attempts with backoff, and a reaper that recovers any row a killed function left stuck in publishing.

The persistence that unlocked it is Prisma on Neon: SocialPiece → SocialVariant (the status machine: pending → publishing → published / failed / rejected, plus scheduled for the drain lane; media as mediaUrls) → SocialMetric (append-only time series). Alongside it, SocialDraftRequest carries the draft's own lifecycle — pending → answered → consumed (approved into a piece) or dismissed (a human said no) — which is what makes the review queue a queue rather than a list. Persistence is also what made the approval link single-use — approving is a conditional row transition, so a second click refuses — and, since 2026-07-30, a two-step confirm: GET renders a read-only page and only the POSTed button publishes, so a chat client's link-preview crawler can never consume an approval.

What remains fixed: 0 6 * * * in vercel.json is when Loop B drafts, and its links still carry the 12-hour approval TTL.

Cron jobs

Running today

The fast cadences live in GitHub Actions because Vercel Hobby grants one cron slot and it is spent on drafting. That split means CRON_SECRET must exist in two places — Vercel env for the routes, and as a GitHub repo secret for the two workflows; missing the second, both lanes self-disable with a ::warning:: rather than failing red.

Candidates, and what each needs first

Still unbuilt — listed so the follow-up is turnkey.

The Weekly content nudge left this table 2026-08-07 — it runs as the Friday digest above (scripts/social-digest.mjs; pillars + the seed lane turned out to be the "calendar structure" it was waiting for).

A cron that publishes without a human is L4 and is gated behind /decide plus the guardrail layer (LLM-judge content + Arabic gate, rate limits, kill switch). Do not add one casually.

Who does what — the marketing team

The binding constraint is content capacity, not channel count — which is why the pipeline is built around one core piece → N platform-native variants rather than N independent posts.

Keywords

Say these in prose — no slash needed. The engine routes them.

Headless lanes, when you want no UI:

Copy# Publish to a distribution channel:
node scripts/post-to-telegram.mjs --text "<approved copy>"
node scripts/post-to-facebook.mjs --text "<approved copy>" --product <brand>
 
# Relay a draft into #social for review — NOT a publish; Slack is the
# communication channel, and this is the review lane, not an audience one:
node scripts/post-to-hermes.mjs   --text "<draft copy>" --channels slack
 
node scripts/generate-social-media.mjs --product <brand> --prompt "<topic>"

Reading the failure modes

See also

• Status — what is actually configured and live right now
• Channel Setup — how to configure each platform, and the traps
• Environment reference — every variable, its default, and whether production has it
• Social Automation — the pipeline overview and channel reality
• Strategy — six lenses, cadence, kill criteria
• Hermes — the gateway itself
• Brand & Voice — the rules every post obeys