SM-Post — Launch a Multi-Tenant Social Media Scheduler on Next.js 15 + Fastify + BullMQ

A self-hostable, multi-tenant social-media posting and scheduling platform — the core of a Buffer/Hootsuite-style product, delivered as a pnpm + Turborepo monorepo. Next.js 15 (App Router) + React 19 on the front, Fastify 5 for the API, a BullMQ worker for publishing, Prisma 6 over Postgres 17, Redis 7 and S3/MinIO. Nine real social providers ship in the box alongside a MockProvider that exercises every branch of the publish state machine. Built for founders launching a niche or vertical scheduling tool, agencies running client social calendars under one roof, and teams that want first-party control of their social tokens instead of renting a seat.

Why you need this MVP

Social scheduling looks like a CRUD app for about a week. Then reality arrives.

A post has to go out exactly once, at the right minute, to N platforms with N different rule sets — and each of those platforms will occasionally accept your request and then time out before answering. The moment your queue retries that call, you have double-posted to a customer's audience, and there is no undo. You need OAuth token refresh that survives expiry at 3 AM, per-platform character and media rules enforced before the API rejects you, an approval flow that cannot be bypassed by editing a post after it was approved, and tenant isolation that does not leak one client's calendar into another's.

SM-Post treats that as the actual product. Postgres is the source of truth for publishing and BullMQ jobs are disposable, deterministically-named triggers — flush Redis completely and one command rebuilds every schedule. BullMQ is pinned to a single attempt and the application owns retry policy in the database, because letting the queue retry is how you double-post. A maybe-sent outcome is never retried; it goes to a human in an operator inbox. A recorded success is never re-posted.

You get the hard parts finished, and you add your niche, your branding and your go-to-market.

Key benefits

• A publishing engine that will not double-post. Three independent guards: a terminal-status early return, an atomic conditional-UPDATE lock (lockedAt older than 60s is reclaimable, lockedBy = host:pid), and a prior-success guard that finalises from the recorded release id rather than calling the provider again.
• Ambiguous outcomes go to a human, never to a retry. A post-send timeout or an unrecognised transport error marks the job NEEDS_REVIEW and lands it in an operator inbox where it can be closed as published or failed. Retrying is refused with a 409 if any attempt was ambiguous or succeeded.
• Redis is disposable. Postgres holds all publishing state; queue jobs are deterministically named (publish:{postId}:{socialAccountId}) so they can be rebuilt. One command restores everything after a Redis flush, and a sweeper revives missed schedules, stale locks, overdue retries and stranded fan-outs on its own.
• Nine real providers + a MockProvider. Bluesky, Mastodon and Telegram work with no platform app at all. LinkedIn, Facebook, Instagram, X, Pinterest and TikTok register the moment you supply your own credentials. The MockProvider's content markers ([fail], [retry], [refresh], [ambiguous]) drive every state-machine branch in tests and demos.
• Rules-as-code per provider. Character limits, media counts, accepted MIME types and per-provider concurrency live in the provider contract, so the composer warns the author before the platform rejects the post.
• True multi-tenancy. Workspaces → projects, OWNER/ADMIN/MEMBER roles, project-level membership, email invitations stored as a hash only, an append-only audit stream, and a workspace predicate required on every service query.
• Approvals that cannot be bypassed. An approval is bound to a sha256 snapshot hash over the post's content, media, per-provider overrides, targets and publish time. The worker recomputes that hash immediately before fan-out — a mismatch blocks the publish entirely rather than shipping stale content.
• An append-only AES-256-GCM token vault. Refreshed tokens are inserted with rotation lineage, never updated; tokens never live on the channel row; PKCE code verifiers are encrypted at rest; and the public DTO can only ever expose an expiry timestamp.
• Stripe billing with a self-host escape hatch. Checkout, Billing Portal and a signed raw-body webhook over FREE/PRO/TEAM tiers, with four entitlement guards (members, projects, channels, scheduled posts per month). No Stripe key = self-host mode, everything unlimited, no code changes.
• Media that never transits your API. Presigned S3/MinIO uploads straight from the browser, then a sharp-based content-sniffing gate on completion — a .txt renamed .jpg dies there. Reads hand back short-lived signed URLs.
• Passwordless auth. better-auth magic link (no password to leak, no password reset flow to secure), optional Google OIDC, 7-day sliding sessions.
• Durable outbound webhooks. A Postgres outbox with HMAC-signed, at-least-once delivery, 8 attempts with exponential backoff — emitted outside the publish transaction so a webhook failure can never roll back a publish.
• Operational hygiene from day one. Liveness and readiness probes, pino structured logs with secret redaction and x-request-id propagation, opt-in Sentry, Redis-backed rate limiting that degrades open, Zod env schemas that fail fast at boot, and a production guard that refuses to start if you ship dev secrets.
• Tests where they matter. 65 unit files (Vitest), 19 integration suites against real Postgres, Redis, MinIO and Mailpit, and 5 Playwright journeys — including one that clicks Publish now and then makes zero further clicks, asserting the post reaches PUBLISHED because the worker did it.

How to make money with it

• Launch a vertical scheduler — real estate, restaurants, gyms, clinics, churches, musicians, e-commerce brands. Vertical tools out-convert generic ones and defend on workflow, not features.
• Sell to agencies — workspaces, projects, roles, approvals and an audit trail are exactly the shape of an agency running many client calendars. Charge per workspace or per seat.
• Run it as a managed service for clients who want their own branded scheduler without operating it.
• Undercut on price by self-hosting — no per-MAU auth bill, no per-seat SaaS bill; your marginal cost is a Postgres row and a Redis job.
• Charge for approvals and governance as a team tier — the approval-hash workflow is a genuine enterprise selling point.
• Bundle scheduling into an existing product (a CRM, a CMS, a booking tool) using the signed service API and webhook outbox, exactly as the included Paperonic integration does.
• Sell white-label deployments to communities, franchises or conferences that need their own posting tool.
• Add the premium tier yourself — analytics dashboards, AI caption generation, or a public API are all deliberately left as headroom rather than shipped as half-features.
• Sell the codebase as an MVP, a fork, or a whitelabel deal.

How you can use it

• Indie founders launching a niche or vertical social scheduler
• Agencies running many client calendars with approvals and role separation
• In-house marketing teams that want first-party control of their social tokens
• SaaS builders who need to bolt scheduling onto an existing product via the service API + webhooks
• Communities, franchises and multi-location brands posting from one calendar to many accounts
• Developers who want a production-shaped reference for queues, OAuth, token encryption and multi-tenancy
• Educators teaching idempotency, exactly-once delivery and the difference between a retry and a double-post

How it boosts your productivity

The obvious CRUD in a scheduler is a couple of weeks. The parts that make it safe are the other six months.

• Publishing safety done. Locking, retry ownership, the ambiguous-outcome path and the prior-success guard are the subtlest code in the repo, and they are already written and tested.
• OAuth done, nine times. Each provider is a full implementation — auth, refresh, media rules, error mapping — behind a single contract, with an operator guide per platform.
• Token encryption done. AES-256-GCM, append-only, with rotation lineage and a crypto readiness check that fails the boot rather than storing plaintext.
• Tenancy done. Workspaces, projects, roles, invites and audit, with the workspace predicate enforced across every route and asserted by an integration test that sweeps 19 workspace-scoped endpoints.
• Billing done. Stripe Checkout, Portal, signed webhooks, plan limits and a self-host mode — with all-or-nothing config validation so you cannot half-configure it into production.
• Approvals done. Including the recheck-before-fan-out that most implementations forget, which is the one that actually matters.
• Ops done. Probes, structured logs, request IDs, redaction, rate limits, fail-fast env parsing, and a guard that refuses to boot with a dev secret in production.
• CI does the work. Import-boundary check → lint → typecheck → migrate deploy → unit + integration → build → migration-drift gate, plus a separate E2E job that boots the whole stack and runs the journeys.

For a solo founder, this is the difference between shipping a scheduler this quarter and still debugging a double-post next quarter.

What is included

• pnpm + Turborepo monorepo — 4 apps, 7 packages, TypeScript end to end
• Next.js 15 App Router + React 19 web client — dashboard, posts, month-grid calendar, publishing inbox, approvals, media, channels, projects, members, notifications, settings, billing
• Post composer — threads, per-provider content overrides, tags, media picker, debounced autosave with optimistic-concurrency conflict detection, live provider rule warnings
• Fastify 5 API — 19 route modules, keyset pagination, a 12-code error envelope, Zod validation throughout
• BullMQ worker — schedule / publish / maintenance / webhook queues, per-provider concurrency, app-owned retry policy, 6 repeatable maintenance jobs
• 9 real providers + MockProvider — Bluesky, Mastodon, Telegram (no platform app needed); LinkedIn, Facebook, Instagram, X, Pinterest, TikTok (bring your own credentials)
• Multi-tenancy — workspaces, projects, OWNER/ADMIN/MEMBER, hash-only email invites, append-only audit events
• Approvals — per-project policy, sha256 content-snapshot binding, worker-side recheck before fan-out, immutable decision log
• Stripe billing — Checkout, Billing Portal, signed raw-body webhook, FREE/PRO/TEAM limits, 4 entitlement guards, self-host mode
• AES-256-GCM token vault — append-only, rotation lineage, encrypted PKCE verifiers, boot-time crypto readiness check
• Media pipeline — presigned S3/MinIO uploads, sharp content-sniffing, short-lived signed read URLs, publish-time image transforms
• Analytics — append-only metric snapshots + a latest-value cache, canonical metric keys, a 6-hour collector, an on-demand refresh, and a 30-day workspace overview
• Notifications — in-app bell + email across 6 categories, Redis dedupe, an allowlisted link path
• Durable webhook outbox — HMAC-signed, at-least-once, 8 attempts with backoff, 5 event types
• Signed service API — HMAC + timestamp + replay window, for headless provisioning from a parent product
• Auth — better-auth passwordless magic link, optional Google OIDC, 7-day sliding sessions
• Prisma 6 / Postgres 17 — 33 models, 14 hand-authored migrations, migrate deploy only, CI drift gate, idempotent demo seed
• Ops — liveness + readiness probes, pino structured logging with redaction, opt-in Sentry, Redis rate limiting, Zod env schemas, production secret guard
• Tests — 65 unit files (Vitest), 19 integration suites (real Postgres + Redis + MinIO + Mailpit), 5 Playwright journeys
• CI — GitHub Actions: boundaries → lint → typecheck → migrate → test → build → drift gate, plus a full-stack E2E job
• docker-compose for backing services (Postgres 17, Redis 7, MinIO, Mailpit) and a 9-guide operator handbook, one per provider

Tech stack at a glance

• Languages: TypeScript end to end
• Frontend: Next.js 15 (App Router) + React 19, Tailwind CSS, TanStack Query
• API: Fastify 5
• Worker / queues: BullMQ on Redis 7
• DB: PostgreSQL 17 + Prisma 6 (hand-authored migrations, migrate deploy only)
• Auth: better-auth (passwordless magic link, optional Google OIDC)
• Crypto: AES-256-GCM append-only token vault
• Payments: Stripe (Checkout, Billing Portal, signed webhooks)
• Storage: S3 / MinIO with presigned uploads, sharp for image handling
• Email: Resend in production; Nodemailer + Mailpit in dev and CI
• Validation: Zod
• Observability: pino structured logging, optional Sentry, liveness + readiness probes
• Testing: Vitest (unit + integration against real infra), Playwright (5 E2E journeys)
• Tooling: pnpm, Turborepo, Docker Compose, GitHub Actions

Good to know before you buy

Stated plainly, because the surprises matter more than the feature list:

• Bluesky, Mastodon and Telegram work immediately. The other six providers need your own platform-app credentials — Facebook and Instagram share one credential pair, and X, Pinterest and TikTok ship inert until you fill them in. Platform app review is the long pole on any social tool, and it is on you.
• Analytics come back from four providers (Bluesky, Mastodon, Instagram, Mock). The rest do not expose the data; the UI shows "Not available" rather than a misleading zero.
• The calendar is a read-only month view — no drag-to-reschedule (yet).
• There is a docker-compose for backing services, but no Dockerfile for the app itself. It deploys anywhere Node 22 runs; a container image is yours to add.
• Deliberately not in scope: a public API, AI caption generation, MFA, and websockets. They are left as headroom for your premium tier, not shipped as half-features.

Ideal for founders launching a niche or vertical social scheduler, agencies running client social calendars with approvals and role separation, product teams embedding scheduling into an existing app, and developers who want a production-shaped queue, OAuth, encryption and multi-tenancy codebase to learn from.