# Cadence PRD

Oct 8, 2026 · @Donna

## Overview

Cadence is a team workspace for social media. A team writes posts together, schedules them for a time, and Cadence publishes them automatically through background jobs that retry when a platform fails. Every attempt is logged, and the dashboard shows each post's status live.

The system is a TypeScript monorepo: a Next.js dashboard, a NestJS API, and a separate publish worker, backed by MongoDB and a Redis + BullMQ job queue. Social platforms are mocked in the MVP.

## Problem

Small teams that post to social media usually work out of a shared doc and someone's phone. That breaks down in a few predictable ways:

- **No shared workflow.** Drafts live in different places, and there's no clear rule for who can edit or publish.
- **Unreliable publishing.** If a platform is down or rate-limits a request at the scheduled time, the post silently doesn't go out.
- **No visibility.** Nobody can see what is scheduled, what failed, or why, without checking each platform by hand.

## Goals and non-goals

The MVP proves that a team can schedule posts and trust that they will publish, or see exactly why they didn't.

**Goals**

- Let a team share one workspace with clear Owner, Editor, and Viewer roles.
- Schedule a post for a future time and publish it from a background worker, not the API.
- Retry failed publishes with backoff, and stop after a limit with a clear failed state.
- Record every publish attempt in an audit log.
- Show post status changes on the dashboard live, without a page refresh.

**Non-goals**

- Real social platform integrations (X, Instagram, LinkedIn). Platforms are mock services that can be told to fail.
- Analytics on post performance (likes, reach).
- AI-written posts.
- Billing or multiple pricing plans.

## Users and user stories

The primary user is a content editor on a small marketing team. Secondary users are the workspace owner, who manages people and accounts, and viewers such as a manager or client who only need to see the plan.

| As a… | I want to… | So that… |
| --- | --- | --- |
| Owner | Invite teammates and set their role | Only the right people can publish |
| Owner | Connect social accounts to the workspace | The team posts from one place |
| Editor | Write a post with text and media, and pick accounts | I can prepare content ahead of time |
| Editor | Schedule a post for a specific time | It goes out without me being online |
| Editor | See when a post failed and why, and retry it | Nothing silently doesn't publish |
| Viewer | See the schedule and post statuses | I know what is going out and when |

## Functional requirements

P0 items are required for the MVP; P1 items follow once the core publish loop works.

| ID | Requirement | Priority |
| --- | --- | --- |
| FR-1 | Users sign up and log in; the API issues a short-lived JWT access token and a rotating refresh token | P0 |
| FR-2 | A reused refresh token revokes the whole token family | P0 |
| FR-3 | A user can create a workspace and invite members as Owner, Editor, or Viewer | P0 |
| FR-4 | Every API route checks the caller's role in the target workspace | P0 |
| FR-5 | Owners can connect mock social accounts to a workspace | P0 |
| FR-6 | Editors can create, edit, and delete draft posts targeting one or more accounts | P0 |
| FR-7 | Scheduling a post adds a delayed BullMQ job; rescheduling or cancelling updates or removes it | P0 |
| FR-8 | The worker loads the post, calls the platform, and moves the post to `published` or `failed` | P0 |
| FR-9 | Failed publishes retry with exponential backoff up to a set attempt limit | P0 |
| FR-10 | Every publish attempt is written to an audit log with time, attempt number, and error | P0 |
| FR-11 | Publishing is idempotent: a retried job never posts the same content twice | P0 |
| FR-12 | The dashboard receives post status changes over WebSocket | P0 |
| FR-13 | `GET /api/health` reports MongoDB, Redis, and queue status | P0 (done) |
| FR-14 | Editors can attach images to posts, stored outside the database | P1 |
| FR-15 | The API rate-limits requests per user and per workspace | P1 |
| FR-16 | An editor can manually retry a post in the `failed` state | P1 |

## System architecture

```mermaid
flowchart LR
  W[Next.js dashboard] -->|REST + JWT| A[NestJS API]
  W <-->|WebSocket status| A
  A --> M[(MongoDB)]
  A -->|add delayed job| Q[(Redis + BullMQ<br/>publish queue)]
  Q --> K[Publish worker]
  K --> M
  K -->|publish| S[Mock social platforms]
  K -->|status event| A
```

The API and the worker are two processes built from one codebase. They share models and config, but scale and restart independently, so a slow platform never blocks API requests. Redis runs with append-only persistence so queued jobs survive a restart.

## Post lifecycle

```mermaid
stateDiagram-v2
  [*] --> draft
  draft --> scheduled: schedule
  scheduled --> draft: cancel
  scheduled --> publishing: job runs
  publishing --> published: platform OK
  publishing --> retrying: platform error
  retrying --> publishing: backoff elapsed
  retrying --> failed: attempts exhausted
  failed --> scheduled: manual retry (P1)
  published --> [*]
```

Rules:

- Only the worker moves a post out of `scheduled`. The API never publishes directly.
- Each attempt writes an audit entry before the status changes, so the log is never behind the post.
- A post that is edited while `scheduled` keeps its job; the worker always loads the latest version at run time.

## Success metrics

The MVP succeeds if scheduled posts publish on time and every failure is visible and explained. Targets are proposed starting points to confirm.

| Metric | Target | How it's measured |
| --- | --- | --- |
| On-time publish | 99% of posts start publishing within 5 seconds of their scheduled time | Scheduled time vs first attempt in audit log |
| Recovery from transient failure | 100% of posts publish when the mock platform fails fewer times than the retry limit | Fault-injection test |
| No duplicate posts | 0 duplicate publishes across retries and worker restarts | Mock platform call count per post |
| Live status latency | Dashboard reflects a status change in under 2 seconds | WebSocket event time vs DB update time |
| Access control | Viewers and non-members get `403` on every write route | API tests per role |

## Milestones

| # | Milestone | Status |
| --- | --- | --- |
| 1 | Foundation: monorepo, Docker, API, worker process, web app | Done |
| 2 | Auth: signup, login, JWT, refresh token rotation | Next |
| 3 | Workspaces and Owner/Editor/Viewer roles | Planned |
| 4 | Mock social accounts and post editing | Planned |
| 5 | Scheduling, publish worker, retries, audit log | Planned |
| 6 | Live dashboard with WebSocket status updates | Planned |
| 7 | Media uploads and rate limiting | Planned |
| 8 | Tests, docs, deploy | Planned |

## Risks and open questions

The biggest risk is a post that publishes twice or not at all without anyone noticing.

| Risk | Mitigation |
| --- | --- |
| A worker crashes after the platform call but before saving status, causing a duplicate on retry | Store a per-attempt idempotency key and check it with the platform before re-posting |
| Delayed jobs drift from the post's schedule after edits | Use the post id as the job id, so rescheduling replaces the job instead of adding one |
| Redis loses queued jobs | Run Redis with append-only persistence; add a sweeper that re-queues overdue `scheduled` posts |
| WebSocket messages leak across workspaces | Join sockets to a per-workspace room only after a role check |
| Mock platforms hide real-world rate limits | Make the mock configurable for latency, error rate, and `429` responses |

**Open questions**

- How many retry attempts, and over what total window, before a post is marked `failed`?
- Should one post to several accounts be one job or one job per account?
- Do Editors need an approval step from an Owner before a post can be scheduled?
- What time zone does the schedule use: the workspace's or each user's?
- Where are media files stored in deploy (S3-compatible bucket or local disk)?
