jbourdon/social-media
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: redefine approval workflow

Browse Source
This commit is contained in:
Jonathan Bourdon
2026-05-01 00:58:47 -04:00
parent 1722d65d22
commit 5077f557f4
8 changed files with 387 additions and 279 deletions
Download Patch File Download Diff File Expand all files Collapse all files

245
docs/FEATURES/approval-workflow.md Normal file
View File

@@ -0,0 +1,245 @@
# Approval Workflow
## Status
Draft
## Goal
Define how a workspace decides whether a `ContentItem` is approved.
Approval workflow is one part of the normal `ContentItem` lifecycle:
```txt
Production -> Approval -> Publication
```
Approval workflow is separate from production workflow. Production covers how content is planned, created, revised, and prepared before approval. Publication may later become its own workflow for scheduling, publishing, and post-publish corrections.
## User Stories
- As a workspace owner, I want to configure the approval mode for my brand workspace so that approval fits the way my organization works.
- As a manager, I want to require approval before content can be scheduled or published so that unapproved content does not go out.
- As a manager, I want optional approval for simpler workflows so that teams can collect sign-off without blocking publication.
- As a manager, I want multi-level approval steps so that different people or groups can approve content in sequence.
- As an approver, I want to review the content, discuss changes, and approve when ready so that the approval decision is clear.
- As a collaborator, I want approval discussions with mentions so that I can involve the right people without changing the approval state.
- As an internal team member, I want team-only comments so that internal discussion can happen without exposing it to client users.
- As a publisher, I want to be notified when final approval is complete so that I can schedule or publish the content.
- As a workspace owner or admin, I want to reopen approval after changes so that approval history remains intact while edge cases can still be handled.
- As an external approver, I want to review and approve a specific content item through a secure magic link so that I do not need a full workspace account.
## Reviewable Object
The object being approved is a `ContentItem`.
Approval decisions, comments, mentions, notifications, timestamps, audit history, and approved content snapshots must remain traceable to the `ContentItem`.
A `ContentItem` can have only one active approval workflow instance at a time.
When approval completes, the approval workflow instance remains attached to the `ContentItem` as history. If an admin reopens approval later, a special approval step is appended to the same history instead of deleting prior approval history or restarting the workflow.
Approval workflow history is visible to all users who can view the `ContentItem`. Approval actions remain permission-gated.
## Lifecycle States
`ContentItem` uses a fixed set of lifecycle states:
- `Draft`
- `In production`
- `In approval`
- `Approved`
- `Scheduled`
- `Published`
Lifecycle state meanings:
- `Draft`: the content item exists after a client or team orders, requests, or creates the publication.
- `In production`: the content item is in production workflow. This applies when authored media or preparation work is required, such as video, photos, copywriting, design, or other production tasks.
- `In approval`: the content item is in approval workflow.
- `Approved`: the approval workflow is complete.
- `Scheduled`: the content item is on the calendar and ready to be published at its scheduled date and time.
- `Published`: the content item was successfully published to all intended channels.
Production workflow is optional for a `ContentItem`. Simple content can move from `Draft` directly to `In approval` when no full production workflow is needed.
## Workspace Configuration
Approval behavior is configured per workspace.
A workspace is the brand boundary. The approval workflow configuration is workspace-wide in v1.
Configuration changes apply to new content and to existing content currently in approval workflow. Content that is already `Approved`, `Scheduled`, or `Published` is not recalculated.
When configuration changes affect existing content in approval:
- previous approval decisions are preserved in history
- current required approval steps are recalculated from the new configuration
- if preserved approvals already satisfy the new requirements, the workflow completes and the `ContentItem` becomes `Approved`
- if recalculation creates a new pending current step, that step's approvers are notified immediately
## Approval Modes
Each workspace supports these approval modes in v1:
- `None`: no approval workflow is used. Content skips only the approval workflow and can become `Approved` without approval actions. This does not bypass production workflow when production work is required.
- `Optional`: a basic one-step approval workflow is created automatically. Approval actions are available, but approval is not required before publication workflow.
- `Required`: a basic one-step approval workflow is created automatically. At least one approval is required from any workspace member with approve content permission before the item can become `Approved` or `Scheduled`.
- `Multi-level`: approval is split into one or more ordered steps, and each step defines who can approve that step.
`Optional` and `Required` use one approval step. More flexible approver targeting only applies to `Multi-level`. If a workspace needs custom approver targeting, it should use `Multi-level` with one or more steps.
## Approval Steps
Approval steps have their own status:
- `Pending`
- `Approved`
`Multi-level` is step-based and sequential. Later steps cannot be approved until earlier steps are complete.
Each multi-level step can target:
- `Role`: a named workspace role with a set of permissions, such as Writer, Contributor, or Approver.
- `Membership`: a workspace membership category, such as Team or Client.
- `Member`: one specific workspace user.
For `Role` and `Membership` targets, the user must match the step target and have approve permission. Membership alone does not grant approval permission; for example, a Client member may be a contributor or an approver depending on their permissions.
For `Member` targets, the selected user can approve that step because they were explicitly assigned.
By default, one matching approver can complete a step. When a step targets a role or membership group, the workspace can optionally configure how many matching approvers are required for that step.
Admins can approve any approval step.
## Approval Decisions
Approval workflow supports one formal decision in v1:
- `Approve`
`Reject` and explicit `Request changes` decisions are not part of v1. Approvers should use comments, discussions, and mentions to coordinate changes until the current step can be approved.
Approval decisions must record:
- actor
- decision
- timestamp
- related `ContentItem`
- approval-controlled content version or snapshot that was approved
A pending step must not be treated as approved.
## Approval-Controlled Content
Approval-controlled content includes:
- caption, copy, and text
- attached media and assets
- selected channels and networks
- content title or name
- production output and revisions
Approval-controlled content excludes:
- scheduling date and time
- internal comments and discussions
If approval-controlled content is edited while the item is `In approval` or `Approved`, the approved status is removed from the current approval step and the step becomes pending again. If the item was `Approved`, it moves back to `In approval`.
When an edit invalidates approval, the current step's approvers are notified immediately.
If content is `Scheduled`, only an admin or workspace owner can change approval-controlled content. This scheduled-content edit policy needs validation with SaaS customers.
If content is `Published`, approval-controlled content is read-only except for admin or workspace owner corrections. Corrections to published content likely require an immediate force or push update through publication workflow.
## Approval Options
Each workspace can configure these approval options:
- schedule posts automatically on approval
- lock content after approval
- send automatic reminders for pending approvals
If schedule posts automatically on approval is enabled, final approval moves the `ContentItem` to `Scheduled` when it already has a planned publish date and time. If no planned publish date and time exists, the item remains `Approved`.
If lock content after approval is enabled, approval-controlled content is locked after final approval. Scheduling fields remain editable.
If automatic reminders for pending approvals is enabled, the current step's approvers are reminded daily while the step is pending. Daily reminders start after the original approval notification.
## Reopening Approval
Users with admin permission can reopen approved content for approval.
Reopening approval appends a special approval step to the existing workflow history. The special reopen step is approved by an admin. Admins can use comments and mentions to coordinate with the needed people before closing the approval workflow again.
## Discussions And Mentions
Approval comments and discussions are attached to the overall approval workflow instance, not to a specific step.
Any workspace user with access to the `ContentItem` can participate in approval discussions. Approval actions remain limited to the current step's approvers and admins.
Approval comments can be visible to everyone with access to the `ContentItem` or marked as team-only. Team-only comments are visible only to users with Team membership and are hidden from Client membership users.
Approval comments should support direct mentions, such as mentioning a person or group with `@`, to notify them directly.
Mentions must respect comment visibility. A comment cannot mention a user or group that cannot see that comment.
## Notifications
Notification rules:
- when a `ContentItem` enters `In approval`, the current approval step's approvers are notified immediately
- when an approval step is approved and another step remains, the next step's approvers are notified
- when the final approval step is approved, users with publish permission for the workflow are notified
- when configuration recalculation creates a new pending current step, that step's approvers are notified immediately
- when an edit invalidates approval, the current step's approvers are notified immediately
- when automatic reminders are enabled, the current step's approvers are reminded daily while the step is pending
- when a comment mentions a user or group, mentioned users are notified if they can see the comment
## Magic Approval Links
Approval workflow supports magic approval links for external approvers.
Magic links are intended for `Optional` and `Required` approval modes. They act on the current approval step when the link is opened.
A magic approval link:
- grants access only to the specific `ContentItem` for which the link was created
- does not grant broader workspace access
- allows the recipient to approve and comment on that approval workflow
- is created for a specific recipient email address
- is sent automatically by the app
- expires after 3 days
- expires immediately after it is used to approve
- is not consumed by commenting
- can be revoked by admins or workspace owners before it expires or is used to approve
Possession of a valid, unexpired magic approval link is sufficient to access the linked approval page. The recipient does not need to create an account.
For comment visibility, magic link recipients are treated as Client membership users. They cannot see or create team-only comments.
Magic link activity must record at least the recipient email for audit history.
Magic approval link events are recorded in approval workflow history, including created, sent, revoked, expired, and used events.
Magic approval links can be created or sent by users with publish permission, workspace owners, or admins.
## Business Rules
- `Approved` must come from explicit workflow rules, not optimistic UI state.
- Approval requirements are scoped to the workspace.
- A `ContentItem` has at most one active approval workflow instance.
- Approval mode `None` creates no approval workflow instance.
- Approval mode `Optional` creates a basic approval workflow instance but does not block publication workflow.
- Approval mode `Required` blocks approval and scheduling until its single approval step is approved.
- Approval mode `Multi-level` blocks approval and scheduling until every configured step is approved.
- Approval history must remain visible after revision, approval, scheduling, or publishing.
- Approval-controlled content changes must invalidate affected approval while the item is `In approval` or `Approved`.
## Open Questions
- Should publishing behavior become a separate `PublishingWorkflow` feature?
- What is the exact data model for approval step configuration?
- How should scheduled-content edit policy work after validation with SaaS customers?
- What publication-system behavior is required for correcting already published content?

98
docs/FEATURES/content-approval-workflow.md
View File

@@ -1,98 +0,0 @@
# 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?

54
docs/FEATURES/production-workflow.md Normal file
View File

@@ -0,0 +1,54 @@
# Production Workflow
## Status
Draft
## Goal
Define how a `ContentItem` is planned, created, revised, and prepared before or during approval.
This feature is intentionally separate from approval workflow. Approval workflow decides whether content is approved for publishing handoff. Production workflow describes how content gets made.
## Reviewable Object
Production work happens around a `ContentItem`.
Assets, revisions, comments, assignments, due dates, channels, notes, and content metadata are part of the production context.
## Initial Scope
Production workflow may eventually cover:
- draft creation
- copy/caption preparation
- media production
- asset linking
- revision history
- internal comments
- assignments and ownership
- due dates
- readiness for review
## Relationship To Approval Workflow
Production workflow can prepare a `ContentItem` for approval, but it does not define who must approve it.
A `ContentItem` may require production work before it can enter review, especially for content formats such as video where work includes planning, filming, editing, revisions, and asset delivery.
## Initial Business Rules
- Production history must remain attached to the `ContentItem`.
- Revisions must not overwrite prior work invisibly.
- The latest asset or revision must be clear.
- Production collaboration should support both simple posts and more involved media work.
- Approval decisions should remain distinguishable from production comments or internal readiness signals.
## Open Questions
- Which production states are needed beyond the fixed `ContentItem` lifecycle states?
- Should production have assignments or owners in v1?
- Should production readiness be required before approval can start?
- How should asset revisions be compared or marked as current?
- Should different content types have different production requirements?

90
docs/FEATURES/review-workflows.md
View File

@@ -1,90 +0,0 @@
# Review Workflows
## Status
Active
## Use Case 1: Internal Review Before Client Review
### Actors
- Content contributor
- Provider
- Internal reviewer
- Manager
### Scenario
1. A contributor or provider creates or updates a draft.
2. The team links assets and updates the content item metadata.
3. An internal reviewer leaves comments or requests changes.
4. Revisions are linked or uploaded.
5. A manager decides the content item is ready for client review.
### Outcome
- the content item has an internal review history
- revisions are traceable
- the item advances to client review only after internal readiness
## Use Case 2: Client Approval
### Actors
- Social media manager
- Client approver
### Scenario
1. The team sends a content item for client review.
2. The client reviews assets, caption/copy, dates, and notes.
3. The client records a decision:
- approve
- reject
- request changes
4. The team responds with comments or revisions when necessary.
### Outcome
- the decision is captured in the system
- the audit trail shows who decided what and when
- the team knows whether the item is approved, blocked, or requires changes
## Use Case 3: Revision Loop
### Actors
- Provider or internal contributor
- Reviewer
### Scenario
1. A reviewer requests changes.
2. The owner of the work creates a revised asset or revised copy.
3. The new revision is linked to the content item.
4. The reviewer can compare current state against prior feedback context.
### Outcome
- the latest revision is identifiable
- older revisions remain traceable
- feedback does not get detached from the work item
## Use Case 4: Ready For Publishing Handoff
### Actors
- Manager
- Publishing owner
### Scenario
1. All required review and approval work is complete.
2. The content item transitions to `Ready to publish`.
3. The downstream publishing owner uses the item as the approved handoff package.
### Outcome
- publishing handoff is based on an approved state
- the approved revision and metadata are clear
- the workflow history remains visible

52
docs/FEATURES/workspace-review-workflow.md
View File

@@ -1,52 +0,0 @@
# Feature: Workspace Review Workflow
## Status
Draft
## Goal
Support workspace-scoped social media content review from content creation through comments, revision, approval, and ready-to-publish handoff.
## User Stories
- As a social media manager, I want content items grouped by workspace, client, and project so that I can manage review work for multiple accounts.
- As a client approver, I want one clear place to review content, comment, and approve or request changes.
- As an account manager, I want notifications and review queues so that work does not stall silently.
## Backend Modules
- Identity
- Workspaces
- Clients
- Projects
- ContentItems
- Assets
- Comments
- Approvals
- Notifications
## Frontend Areas
- `/app`
- `/app/workspaces/new`
- `/app/clients`
- `/app/projects`
- `/app/content`
- `/app/content/:id`
- `/app/reviews`
- `/app/settings`
## Domain Rules
- Workspace is the top-level scoping boundary.
- Content items belong to a workspace and may belong to a client or project.
- Comments, approvals, assets, and notifications must remain traceable to the workflow entity they relate to.
- Ready-to-publish state should come from explicit approval workflow transitions.
## Done When
- [ ] Workspace access is enforced consistently
- [ ] Content item lifecycle is documented as a state machine
- [ ] Approval decisions create traceable notifications/events
- [ ] Review queue behavior is covered by tasks and validation

46
docs/TASKS/approval-workflow/001-define-approval-workflow.md Normal file
View File

@@ -0,0 +1,46 @@
# Task: Define approval workflow
## Feature
`docs/FEATURES/approval-workflow.md`
## Goal
Define the v1 approval workflow behavior for `ContentItem` approval.
## Context
Approval workflow has been split from production workflow. The object being approved is a `ContentItem`, and workspaces configure approval behavior without defining a fully custom state machine.
## Scope
- Define approval modes.
- Define approval actors.
- Define approval decisions.
- Define the state transitions affected by approval.
- Define notification and audit side effects.
- Define open questions that remain outside v1.
## Constraints
- Documentation-only task.
- Do not change backend or frontend code.
- Keep production workflow details out of this task except where needed to explain boundaries.
## Done When
- [ ] approval modes are defined
- [ ] actor permissions are defined
- [ ] approval decisions are defined
- [ ] state transition behavior is defined
- [ ] workspace configuration fields are described
- [ ] notification side effects are listed
- [ ] audit requirements are listed
- [ ] out-of-scope production behavior is explicitly separated
## Validation Commands
```bash
git diff -- docs/FEATURES docs/TASKS
```

42
docs/TASKS/production-workflow/001-define-production-workflow.md Normal file
View File

@@ -0,0 +1,42 @@
# Task: Define production workflow
## Feature
`docs/FEATURES/production-workflow.md`
## Goal
Define the v1 production workflow for how a `ContentItem` is planned, created, revised, and prepared for review.
## Context
Production workflow has been split from approval workflow. This task should be picked up later after approval workflow is defined.
## Scope
- Define production states or readiness markers.
- Define production actors.
- Define asset and revision expectations.
- Define assignment and ownership expectations.
- Define how production work prepares a `ContentItem` for review.
## Constraints
- Documentation-only task.
- Do not change backend or frontend code.
- Do not redefine approval modes or approval decisions here.
## Done When
- [ ] production scope is defined
- [ ] production actors are defined
- [ ] asset and revision rules are defined
- [ ] readiness-for-review behavior is defined
- [ ] approval workflow boundaries are explicit
## Validation Commands
```bash
git diff -- docs/FEATURES docs/TASKS
```

39
docs/TASKS/workspace-review-workflow/001-document-content-state-machine.md
View File

@@ -1,39 +0,0 @@
# Task: Document content state machine
## Feature
`docs/FEATURES/workspace-review-workflow.md`
## Goal
Define the current and intended content item states, transitions, and approval side effects before further workflow implementation.
## Context
The code already contains content items, approvals, comments, assets, notifications, and review queue screens. The workflow needs one durable spec so future agents do not infer state transitions from scattered UI code.
## Files Likely To Change
- `docs/FEATURES/workspace-review-workflow.md`
- `docs/FEATURES/content-approval-workflow.md`
- optionally `docs/DECISIONS/*.md`
## Constraints
- Documentation-only task.
- Do not change backend or frontend code.
- Distinguish current behavior from proposed behavior.
## Done When
- [ ] States are listed
- [ ] Allowed transitions are listed
- [ ] Actor permissions are listed
- [ ] Notification side effects are listed
- [ ] Open questions are explicit
## Validation Commands
```bash
git diff -- docs/FEATURES docs/DECISIONS
```