# 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?