social-media/docs/FEATURES/content-approval-workflow.md

Content Approval Workflow

Status

Active

Goal

Support the primary workflow from draft preparation through review, revision, approval decision, and readiness for publishing handoff.

Actors

• Content contributor
• Provider
• Internal reviewer
• Manager
• Client approver

Preconditions

• user is authenticated when acting as an internal team member
• work is scoped to a workspace
• content item exists inside a workspace context

Trigger

A team member wants to send a content item through review and approval.

Main Flow

1. A team member creates or updates a content item.
2. Assets are linked to the content item, including Google Drive references when appropriate.
3. The content item includes the relevant metadata:
   • title
   • publication message or caption
   • networks
   • channels
   • due date
   • notes
4. The item enters internal review or client review.
5. Reviewers leave comments and record decisions.
6. If changes are requested, the team links a new revision and continues the workflow.
7. Once required review is complete, the item can move to Ready to publish.

Alternate Flows

• If a reviewer requests changes, the item should not be treated as approved.
• If the actor lacks required workspace access, the workflow action must be denied.
• If assets are missing, the item may still exist, but review readiness should remain explicit.

Business Rules

• approvals and comments must remain attached to the content item context
• workflow state changes must be traceable
• revisions must not overwrite history invisibly
• “Ready to publish” must correspond to explicit workflow completion, not optimistic UI state

Data / Entities

• Workspace
• ContentItem
• Asset
• AssetRevision
• CommentThread
• ApprovalRequest
• ApprovalDecision
• NotificationEvent

API / UI Surface

Frontend

• /app/content
• /app/content/:id
• /app/reviews

Backend

• content item handlers
• asset linkage / revision handlers
• approval handlers
• comment handlers
• notification handlers

Acceptance Criteria

• a content item can carry the metadata needed for review
• assets and revisions are visible in the item history
• reviewers can leave comments and decisions in one place
• the audit trail makes status transitions understandable
• the approved state is distinguishable from changes-requested and rejected states
• the workflow supports internal review before client approval

Open Questions

• Should external review be account-based, magic-link-based, or both in version 1?
• Which approval states are mandatory before transition to Ready to publish?
• Should required approvers be modeled in version 1 or phase 2?