wip

backend/src/Socialize.Api/Data/AppDbContext.cs

@@ -26,8 +26,10 @@ public class AppDbContext(
     public DbSet<Asset> Assets => Set<Asset>();
     public DbSet<AssetRevision> AssetRevisions => Set<AssetRevision>();
     public DbSet<Comment> Comments => Set<Comment>();
+    public DbSet<ApprovalWorkflowInstance> ApprovalWorkflowInstances => Set<ApprovalWorkflowInstance>();
     public DbSet<ApprovalRequest> ApprovalRequests => Set<ApprovalRequest>();
     public DbSet<ApprovalDecision> ApprovalDecisions => Set<ApprovalDecision>();
+    public DbSet<WorkspaceApprovalStepConfiguration> WorkspaceApprovalStepConfigurations => Set<WorkspaceApprovalStepConfiguration>();
     public DbSet<NotificationEvent> NotificationEvents => Set<NotificationEvent>();
     public DbSet<FeedbackReport> FeedbackReports => Set<FeedbackReport>();
     public DbSet<FeedbackTag> FeedbackTags => Set<FeedbackTag>();

backend/src/Socialize.Api/Infrastructure/Development/DevelopmentSeedExtensions.cs

@@ -307,7 +307,7 @@ public static class DevelopmentSeedExtensions
             "Spring launch hero video",
             "Fresh seasonal menu launch across Instagram and TikTok.",
             "Instagram Reel, TikTok",
-            "In client review",
+            "In approval",
             DateTimeOffset.UtcNow.AddDays(3),
             "v3",
             3,

backend/src/Socialize.Api/Migrations/20260501170646_AddWorkspaceApprovalConfiguration.cs

@@ -0,0 +1,63 @@
+using Microsoft.EntityFrameworkCore.Migrations;
+
+#nullable disable
+
+namespace Socialize.Api.Migrations
+{
+    /// <inheritdoc />
+    public partial class AddWorkspaceApprovalConfiguration : Migration
+    {
+        /// <inheritdoc />
+        protected override void Up(MigrationBuilder migrationBuilder)
+        {
+            migrationBuilder.AddColumn<string>(
+                name: "ApprovalMode",
+                table: "Workspaces",
+                type: "character varying(32)",
+                maxLength: 32,
+                nullable: false,
+                defaultValue: "Required");
+
+            migrationBuilder.AddColumn<bool>(
+                name: "LockContentAfterApproval",
+                table: "Workspaces",
+                type: "boolean",
+                nullable: false,
+                defaultValue: false);
+
+            migrationBuilder.AddColumn<bool>(
+                name: "SchedulePostsAutomaticallyOnApproval",
+                table: "Workspaces",
+                type: "boolean",
+                nullable: false,
+                defaultValue: false);
+
+            migrationBuilder.AddColumn<bool>(
+                name: "SendAutomaticApprovalReminders",
+                table: "Workspaces",
+                type: "boolean",
+                nullable: false,
+                defaultValue: false);
+        }
+
+        /// <inheritdoc />
+        protected override void Down(MigrationBuilder migrationBuilder)
+        {
+            migrationBuilder.DropColumn(
+                name: "ApprovalMode",
+                table: "Workspaces");
+
+            migrationBuilder.DropColumn(
+                name: "LockContentAfterApproval",
+                table: "Workspaces");
+
+            migrationBuilder.DropColumn(
+                name: "SchedulePostsAutomaticallyOnApproval",
+                table: "Workspaces");
+
+            migrationBuilder.DropColumn(
+                name: "SendAutomaticApprovalReminders",
+                table: "Workspaces");
+        }
+    }
+}

backend/src/Socialize.Api/Migrations/20260501173710_AddWorkspaceApprovalStepConfiguration.cs

@@ -0,0 +1,51 @@
+using System;
+using Microsoft.EntityFrameworkCore.Migrations;
+
+#nullable disable
+
+namespace Socialize.Api.Migrations
+{
+    /// <inheritdoc />
+    public partial class AddWorkspaceApprovalStepConfiguration : Migration
+    {
+        /// <inheritdoc />
+        protected override void Up(MigrationBuilder migrationBuilder)
+        {
+            migrationBuilder.CreateTable(
+                name: "WorkspaceApprovalStepConfigurations",
+                columns: table => new
+                {
+                    Id = table.Column<Guid>(type: "uuid", nullable: false),
+                    WorkspaceId = table.Column<Guid>(type: "uuid", nullable: false),
+                    Name = table.Column<string>(type: "character varying(128)", maxLength: 128, nullable: false),
+                    SortOrder = table.Column<int>(type: "integer", nullable: false),
+                    TargetType = table.Column<string>(type: "character varying(32)", maxLength: 32, nullable: false),
+                    TargetValue = table.Column<string>(type: "character varying(128)", maxLength: 128, nullable: false),
+                    RequiredApproverCount = table.Column<int>(type: "integer", nullable: false, defaultValue: 1),
+                    CreatedAt = table.Column<DateTimeOffset>(type: "timestamp with time zone", nullable: false, defaultValueSql: "CURRENT_TIMESTAMP")
+                },
+                constraints: table =>
+                {
+                    table.PrimaryKey("PK_WorkspaceApprovalStepConfigurations", x => x.Id);
+                });
+
+            migrationBuilder.CreateIndex(
+                name: "IX_WorkspaceApprovalStepConfigurations_WorkspaceId",
+                table: "WorkspaceApprovalStepConfigurations",
+                column: "WorkspaceId");
+
+            migrationBuilder.CreateIndex(
+                name: "IX_WorkspaceApprovalStepConfigurations_WorkspaceId_SortOrder",
+                table: "WorkspaceApprovalStepConfigurations",
+                columns: new[] { "WorkspaceId", "SortOrder" },
+                unique: true);
+        }
+
+        /// <inheritdoc />
+        protected override void Down(MigrationBuilder migrationBuilder)
+        {
+            migrationBuilder.DropTable(
+                name: "WorkspaceApprovalStepConfigurations");
+        }
+    }
+}

backend/src/Socialize.Api/Migrations/20260501175648_AddApprovalWorkflowRuntime.cs

@@ -0,0 +1,117 @@
+using System;
+using Microsoft.EntityFrameworkCore.Migrations;
+
+#nullable disable
+
+namespace Socialize.Api.Migrations
+{
+    /// <inheritdoc />
+    public partial class AddApprovalWorkflowRuntime : Migration
+    {
+        /// <inheritdoc />
+        protected override void Up(MigrationBuilder migrationBuilder)
+        {
+            migrationBuilder.AddColumn<Guid>(
+                name: "WorkflowInstanceId",
+                table: "ApprovalRequests",
+                type: "uuid",
+                nullable: true);
+
+            migrationBuilder.AddColumn<int>(
+                name: "WorkflowStepRequiredApproverCount",
+                table: "ApprovalRequests",
+                type: "integer",
+                nullable: true);
+
+            migrationBuilder.AddColumn<int>(
+                name: "WorkflowStepSortOrder",
+                table: "ApprovalRequests",
+                type: "integer",
+                nullable: true);
+
+            migrationBuilder.AddColumn<string>(
+                name: "WorkflowStepTargetType",
+                table: "ApprovalRequests",
+                type: "character varying(32)",
+                maxLength: 32,
+                nullable: true);
+
+            migrationBuilder.AddColumn<string>(
+                name: "WorkflowStepTargetValue",
+                table: "ApprovalRequests",
+                type: "character varying(128)",
+                maxLength: 128,
+                nullable: true);
+
+            migrationBuilder.CreateTable(
+                name: "ApprovalWorkflowInstances",
+                columns: table => new
+                {
+                    Id = table.Column<Guid>(type: "uuid", nullable: false),
+                    WorkspaceId = table.Column<Guid>(type: "uuid", nullable: false),
+                    ContentItemId = table.Column<Guid>(type: "uuid", nullable: false),
+                    State = table.Column<string>(type: "character varying(64)", maxLength: 64, nullable: false),
+                    ApprovalMode = table.Column<string>(type: "character varying(64)", maxLength: 64, nullable: false),
+                    StartedAt = table.Column<DateTimeOffset>(type: "timestamp with time zone", nullable: false, defaultValueSql: "CURRENT_TIMESTAMP"),
+                    CompletedAt = table.Column<DateTimeOffset>(type: "timestamp with time zone", nullable: true)
+                },
+                constraints: table =>
+                {
+                    table.PrimaryKey("PK_ApprovalWorkflowInstances", x => x.Id);
+                });
+
+            migrationBuilder.CreateIndex(
+                name: "IX_ApprovalRequests_WorkflowInstanceId",
+                table: "ApprovalRequests",
+                column: "WorkflowInstanceId");
+
+            migrationBuilder.CreateIndex(
+                name: "IX_ApprovalWorkflowInstances_ContentItemId",
+                table: "ApprovalWorkflowInstances",
+                column: "ContentItemId");
+
+            migrationBuilder.CreateIndex(
+                name: "IX_ApprovalWorkflowInstances_ContentItemId_State",
+                table: "ApprovalWorkflowInstances",
+                columns: new[] { "ContentItemId", "State" },
+                unique: true,
+                filter: "\"State\" = 'Pending'");
+
+            migrationBuilder.CreateIndex(
+                name: "IX_ApprovalWorkflowInstances_WorkspaceId",
+                table: "ApprovalWorkflowInstances",
+                column: "WorkspaceId");
+        }
+
+        /// <inheritdoc />
+        protected override void Down(MigrationBuilder migrationBuilder)
+        {
+            migrationBuilder.DropTable(
+                name: "ApprovalWorkflowInstances");
+
+            migrationBuilder.DropIndex(
+                name: "IX_ApprovalRequests_WorkflowInstanceId",
+                table: "ApprovalRequests");
+
+            migrationBuilder.DropColumn(
+                name: "WorkflowInstanceId",
+                table: "ApprovalRequests");
+
+            migrationBuilder.DropColumn(
+                name: "WorkflowStepRequiredApproverCount",
+                table: "ApprovalRequests");
+
+            migrationBuilder.DropColumn(
+                name: "WorkflowStepSortOrder",
+                table: "ApprovalRequests");
+
+            migrationBuilder.DropColumn(
+                name: "WorkflowStepTargetType",
+                table: "ApprovalRequests");
+
+            migrationBuilder.DropColumn(
+                name: "WorkflowStepTargetValue",
+                table: "ApprovalRequests");
+        }
+    }
+}

backend/src/Socialize.Api/Migrations/AppDbContextModelSnapshot.cs

@@ -216,6 +216,23 @@ namespace Socialize.Api.Migrations
                         .HasMaxLength(64)
                         .HasColumnType("character varying(64)");
 
+                    b.Property<Guid?>("WorkflowInstanceId")
+                        .HasColumnType("uuid");
+
+                    b.Property<int?>("WorkflowStepRequiredApproverCount")
+                        .HasColumnType("integer");
+
+                    b.Property<int?>("WorkflowStepSortOrder")
+                        .HasColumnType("integer");
+
+                    b.Property<string>("WorkflowStepTargetType")
+                        .HasMaxLength(32)
+                        .HasColumnType("character varying(32)");
+
+                    b.Property<string>("WorkflowStepTargetValue")
+                        .HasMaxLength(128)
+                        .HasColumnType("character varying(128)");
+
                     b.Property<Guid>("WorkspaceId")
                         .HasColumnType("uuid");
 
@@ -225,11 +242,103 @@ namespace Socialize.Api.Migrations
 
                     b.HasIndex("ReviewerEmail");
 
+                    b.HasIndex("WorkflowInstanceId");
+
                     b.HasIndex("WorkspaceId");
 
                     b.ToTable("ApprovalRequests", (string)null);
                 });
 
+            modelBuilder.Entity("Socialize.Api.Modules.Approvals.Data.ApprovalWorkflowInstance", b =>
+                {
+                    b.Property<Guid>("Id")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("uuid");
+
+                    b.Property<string>("ApprovalMode")
+                        .IsRequired()
+                        .HasMaxLength(64)
+                        .HasColumnType("character varying(64)");
+
+                    b.Property<DateTimeOffset?>("CompletedAt")
+                        .HasColumnType("timestamp with time zone");
+
+                    b.Property<Guid>("ContentItemId")
+                        .HasColumnType("uuid");
+
+                    b.Property<DateTimeOffset>("StartedAt")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("timestamp with time zone")
+                        .HasDefaultValueSql("CURRENT_TIMESTAMP");
+
+                    b.Property<string>("State")
+                        .IsRequired()
+                        .HasMaxLength(64)
+                        .HasColumnType("character varying(64)");
+
+                    b.Property<Guid>("WorkspaceId")
+                        .HasColumnType("uuid");
+
+                    b.HasKey("Id");
+
+                    b.HasIndex("ContentItemId");
+
+                    b.HasIndex("WorkspaceId");
+
+                    b.HasIndex("ContentItemId", "State")
+                        .IsUnique()
+                        .HasFilter("\"State\" = 'Pending'");
+
+                    b.ToTable("ApprovalWorkflowInstances", (string)null);
+                });
+
+            modelBuilder.Entity("Socialize.Api.Modules.Approvals.Data.WorkspaceApprovalStepConfiguration", b =>
+                {
+                    b.Property<Guid>("Id")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("uuid");
+
+                    b.Property<DateTimeOffset>("CreatedAt")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("timestamp with time zone")
+                        .HasDefaultValueSql("CURRENT_TIMESTAMP");
+
+                    b.Property<string>("Name")
+                        .IsRequired()
+                        .HasMaxLength(128)
+                        .HasColumnType("character varying(128)");
+
+                    b.Property<int>("RequiredApproverCount")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("integer")
+                        .HasDefaultValue(1);
+
+                    b.Property<int>("SortOrder")
+                        .HasColumnType("integer");
+
+                    b.Property<string>("TargetType")
+                        .IsRequired()
+                        .HasMaxLength(32)
+                        .HasColumnType("character varying(32)");
+
+                    b.Property<string>("TargetValue")
+                        .IsRequired()
+                        .HasMaxLength(128)
+                        .HasColumnType("character varying(128)");
+
+                    b.Property<Guid>("WorkspaceId")
+                        .HasColumnType("uuid");
+
+                    b.HasKey("Id");
+
+                    b.HasIndex("WorkspaceId");
+
+                    b.HasIndex("WorkspaceId", "SortOrder")
+                        .IsUnique();
+
+                    b.ToTable("WorkspaceApprovalStepConfigurations", (string)null);
+                });
+
             modelBuilder.Entity("Socialize.Api.Modules.Assets.Data.Asset", b =>
                 {
                     b.Property<Guid>("Id")
@@ -1100,11 +1209,23 @@ namespace Socialize.Api.Migrations
                         .ValueGeneratedOnAdd()
                         .HasColumnType("uuid");
 
+                    b.Property<string>("ApprovalMode")
+                        .IsRequired()
+                        .ValueGeneratedOnAdd()
+                        .HasMaxLength(32)
+                        .HasColumnType("character varying(32)")
+                        .HasDefaultValue("Required");
+
                     b.Property<DateTimeOffset>("CreatedAt")
                         .ValueGeneratedOnAdd()
                         .HasColumnType("timestamp with time zone")
                         .HasDefaultValueSql("CURRENT_TIMESTAMP");
 
+                    b.Property<bool>("LockContentAfterApproval")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("boolean")
+                        .HasDefaultValue(false);
+
                     b.Property<string>("LogoUrl")
                         .HasMaxLength(2048)
                         .HasColumnType("character varying(2048)");
@@ -1117,6 +1238,16 @@ namespace Socialize.Api.Migrations
                     b.Property<Guid>("OwnerUserId")
                         .HasColumnType("uuid");
 
+                    b.Property<bool>("SchedulePostsAutomaticallyOnApproval")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("boolean")
+                        .HasDefaultValue(false);
+
+                    b.Property<bool>("SendAutomaticApprovalReminders")
+                        .ValueGeneratedOnAdd()
+                        .HasColumnType("boolean")
+                        .HasDefaultValue(false);
+
                     b.Property<string>("Slug")
                         .IsRequired()
                         .HasMaxLength(128)

backend/src/Socialize.Api/Modules/Approvals/Data/ApprovalModelConfiguration.cs

@@ -6,10 +6,28 @@ public static class ApprovalModelConfiguration
 {
     public static ModelBuilder ConfigureApprovalsModule(this ModelBuilder modelBuilder)
     {
+        modelBuilder.Entity<ApprovalWorkflowInstance>(workflowInstance =>
+        {
+            workflowInstance.ToTable("ApprovalWorkflowInstances");
+            workflowInstance.HasKey(x => x.Id);
+            workflowInstance.Property(x => x.State).HasMaxLength(64).IsRequired();
+            workflowInstance.Property(x => x.ApprovalMode).HasMaxLength(64).IsRequired();
+            workflowInstance.Property(x => x.StartedAt)
+                .ValueGeneratedOnAdd()
+                .HasDefaultValueSql("CURRENT_TIMESTAMP");
+            workflowInstance.HasIndex(x => x.WorkspaceId);
+            workflowInstance.HasIndex(x => x.ContentItemId);
+            workflowInstance.HasIndex(x => new { x.ContentItemId, x.State })
+                .IsUnique()
+                .HasFilter("\"State\" = 'Pending'");
+        });
+
         modelBuilder.Entity<ApprovalRequest>(approvalRequest =>
         {
             approvalRequest.ToTable("ApprovalRequests");
             approvalRequest.HasKey(x => x.Id);
+            approvalRequest.Property(x => x.WorkflowStepTargetType).HasMaxLength(32);
+            approvalRequest.Property(x => x.WorkflowStepTargetValue).HasMaxLength(128);
             approvalRequest.Property(x => x.Stage).HasMaxLength(64).IsRequired();
             approvalRequest.Property(x => x.ReviewerName).HasMaxLength(256).IsRequired();
             approvalRequest.Property(x => x.ReviewerEmail).HasMaxLength(256).IsRequired();
@@ -20,6 +38,7 @@ public static class ApprovalModelConfiguration
                 .HasDefaultValueSql("CURRENT_TIMESTAMP");
             approvalRequest.HasIndex(x => x.WorkspaceId);
             approvalRequest.HasIndex(x => x.ContentItemId);
+            approvalRequest.HasIndex(x => x.WorkflowInstanceId);
             approvalRequest.HasIndex(x => x.ReviewerEmail);
         });
 
@@ -37,6 +56,21 @@ public static class ApprovalModelConfiguration
             approvalDecision.HasIndex(x => x.ApprovalRequestId);
         });
 
+        modelBuilder.Entity<WorkspaceApprovalStepConfiguration>(approvalStep =>
+        {
+            approvalStep.ToTable("WorkspaceApprovalStepConfigurations");
+            approvalStep.HasKey(x => x.Id);
+            approvalStep.Property(x => x.Name).HasMaxLength(128).IsRequired();
+            approvalStep.Property(x => x.TargetType).HasMaxLength(32).IsRequired();
+            approvalStep.Property(x => x.TargetValue).HasMaxLength(128).IsRequired();
+            approvalStep.Property(x => x.RequiredApproverCount).HasDefaultValue(1);
+            approvalStep.Property(x => x.CreatedAt)
+                .ValueGeneratedOnAdd()
+                .HasDefaultValueSql("CURRENT_TIMESTAMP");
+            approvalStep.HasIndex(x => x.WorkspaceId);
+            approvalStep.HasIndex(x => new { x.WorkspaceId, x.SortOrder }).IsUnique();
+        });
+
         return modelBuilder;
     }
 }

backend/src/Socialize.Api/Modules/Approvals/Data/ApprovalRequest.cs

@@ -5,6 +5,11 @@ public class ApprovalRequest
     public Guid Id { get; init; }
     public Guid WorkspaceId { get; set; }
     public Guid ContentItemId { get; set; }
+    public Guid? WorkflowInstanceId { get; set; }
+    public int? WorkflowStepSortOrder { get; set; }
+    public string? WorkflowStepTargetType { get; set; }
+    public string? WorkflowStepTargetValue { get; set; }
+    public int? WorkflowStepRequiredApproverCount { get; set; }
     public required string Stage { get; set; }
     public required string ReviewerName { get; set; }
     public required string ReviewerEmail { get; set; }

backend/src/Socialize.Api/Modules/Approvals/Data/ApprovalWorkflowInstance.cs

@@ -0,0 +1,12 @@
+namespace Socialize.Api.Modules.Approvals.Data;
+
+public class ApprovalWorkflowInstance
+{
+    public Guid Id { get; init; }
+    public Guid WorkspaceId { get; set; }
+    public Guid ContentItemId { get; set; }
+    public required string State { get; set; }
+    public required string ApprovalMode { get; set; }
+    public DateTimeOffset StartedAt { get; init; }
+    public DateTimeOffset? CompletedAt { get; set; }
+}

backend/src/Socialize.Api/Modules/Approvals/Data/WorkspaceApprovalStepConfiguration.cs

@@ -0,0 +1,13 @@
+namespace Socialize.Api.Modules.Approvals.Data;
+
+public class WorkspaceApprovalStepConfiguration
+{
+    public Guid Id { get; init; }
+    public Guid WorkspaceId { get; set; }
+    public required string Name { get; set; }
+    public int SortOrder { get; set; }
+    public required string TargetType { get; set; }
+    public required string TargetValue { get; set; }
+    public int RequiredApproverCount { get; set; } = 1;
+    public DateTimeOffset CreatedAt { get; init; }
+}

backend/src/Socialize.Api/Modules/Approvals/DependencyInjection.cs

@@ -1,4 +1,4 @@
-using Socialize.Api.Modules.Approvals.Data;
+using Socialize.Api.Modules.Approvals.Services;
 
 namespace Socialize.Api.Modules.Approvals;
 
@@ -7,6 +7,8 @@ public static class DependencyInjection
     public static WebApplicationBuilder AddApprovalsModule(
         this WebApplicationBuilder builder)
     {
+        builder.Services.AddScoped<ApprovalWorkflowRuntimeService>();
+
         return builder;
     }
 }

backend/src/Socialize.Api/Modules/Approvals/Handlers/CreateApprovalRequest.cs

@@ -4,7 +4,9 @@ using System.Security.Cryptography;
 using Socialize.Api.Data;
 using Socialize.Api.Infrastructure.Security;
 using Socialize.Api.Modules.Approvals.Data;
+using Socialize.Api.Modules.Approvals.Services;
 using Socialize.Api.Modules.Notifications.Contracts;
+using Socialize.Api.Modules.Workspaces.Data;
 
 namespace Socialize.Api.Modules.Approvals.Handlers;
 
@@ -62,6 +64,22 @@ public class CreateApprovalRequestHandler(
             return;
         }
 
+        Workspace? workspace = await dbContext.Workspaces.SingleOrDefaultAsync(candidate => candidate.Id == contentItem.WorkspaceId, ct);
+        if (workspace is null)
+        {
+            await SendNotFoundAsync(ct);
+            return;
+        }
+
+        if (!ApprovalWorkflowRules.CanCreateSingleStepApprovalRequest(workspace.ApprovalMode))
+        {
+            AddError(request => request.WorkspaceId, workspace.ApprovalMode == ApprovalModes.None
+                ? "Approval workflow is disabled for this workspace."
+                : "Move content to In approval to start the configured multi-level approval workflow.");
+            await SendErrorsAsync(StatusCodes.Status400BadRequest, ct);
+            return;
+        }
+
         var approval = new ApprovalRequest()
         {
             Id = Guid.NewGuid(),
@@ -79,14 +97,7 @@ public class CreateApprovalRequestHandler(
 
         dbContext.ApprovalRequests.Add(approval);
 
-        if (approval.Stage == "Internal")
-        {
-            contentItem.Status = "In internal review";
-        }
-        else if (approval.Stage == "Client")
-        {
-            contentItem.Status = "In client review";
-        }
+        contentItem.Status = "In approval";
 
         await dbContext.SaveChangesAsync(ct);
 
@@ -107,6 +118,11 @@ public class CreateApprovalRequestHandler(
             approval.Id,
             approval.WorkspaceId,
             approval.ContentItemId,
+            approval.WorkflowInstanceId,
+            approval.WorkflowStepSortOrder,
+            approval.WorkflowStepTargetType,
+            approval.WorkflowStepTargetValue,
+            approval.WorkflowStepRequiredApproverCount,
             approval.Stage,
             approval.ReviewerName,
             approval.ReviewerEmail,

backend/src/Socialize.Api/Modules/Approvals/Handlers/GetApprovals.cs

@@ -24,6 +24,11 @@ public record ApprovalRequestDto(
     Guid Id,
     Guid WorkspaceId,
     Guid ContentItemId,
+    Guid? WorkflowInstanceId,
+    int? WorkflowStepSortOrder,
+    string? WorkflowStepTargetType,
+    string? WorkflowStepTargetValue,
+    int? WorkflowStepRequiredApproverCount,
     string Stage,
     string ReviewerName,
     string ReviewerEmail,
@@ -65,6 +70,7 @@ public class GetApprovalsHandler(
         List<ApprovalRequest> approvals = await dbContext.ApprovalRequests
             .Where(approval => approval.ContentItemId == request.ContentItemId)
             .OrderByDescending(approval => approval.SentAt)
+            .ThenBy(approval => approval.WorkflowStepSortOrder)
             .ToListAsync(ct);
 
         List<Guid> approvalIds = approvals
@@ -91,6 +97,11 @@ public class GetApprovalsHandler(
                 approval.Id,
                 approval.WorkspaceId,
                 approval.ContentItemId,
+                approval.WorkflowInstanceId,
+                approval.WorkflowStepSortOrder,
+                approval.WorkflowStepTargetType,
+                approval.WorkflowStepTargetValue,
+                approval.WorkflowStepRequiredApproverCount,
                 approval.Stage,
                 approval.ReviewerName,
                 approval.ReviewerEmail,

backend/src/Socialize.Api/Modules/Approvals/Handlers/SubmitApprovalDecision.cs

@@ -4,7 +4,9 @@ using Socialize.Api.Data;
 using Socialize.Api.Infrastructure.Security;
 using Socialize.Api.Modules.ContentItems.Data;
 using Socialize.Api.Modules.Approvals.Data;
+using Socialize.Api.Modules.Approvals.Services;
 using Socialize.Api.Modules.Notifications.Contracts;
+using Socialize.Api.Modules.Workspaces.Data;
 
 namespace Socialize.Api.Modules.Approvals.Handlers;
 
@@ -19,7 +21,10 @@ public class SubmitApprovalDecisionRequestValidator
 {
     public SubmitApprovalDecisionRequestValidator()
     {
-        RuleFor(x => x.Decision).NotEmpty().MaximumLength(64);
+        RuleFor(x => x.Decision)
+            .NotEmpty()
+            .Equal("Approved")
+            .WithMessage("Only approved decisions are supported.");
         RuleFor(x => x.Comment).MaximumLength(2048);
         RuleFor(x => x.ReviewerName).MaximumLength(256);
         RuleFor(x => x.ReviewerEmail).MaximumLength(256).EmailAddress().When(x => !string.IsNullOrWhiteSpace(x.ReviewerEmail));
@@ -29,6 +34,7 @@ public class SubmitApprovalDecisionRequestValidator
 public class SubmitApprovalDecisionHandler(
     AppDbContext dbContext,
     AccessScopeService accessScopeService,
+    ApprovalWorkflowRuntimeService approvalWorkflowRuntimeService,
     INotificationEventWriter notificationEventWriter)
     : Endpoint<SubmitApprovalDecisionRequest, ApprovalRequestDto>
 {
@@ -64,6 +70,13 @@ public class SubmitApprovalDecisionHandler(
             return;
         }
 
+        Workspace? workspace = await dbContext.Workspaces.SingleOrDefaultAsync(candidate => candidate.Id == contentItem.WorkspaceId, ct);
+        if (workspace is null)
+        {
+            await SendNotFoundAsync(ct);
+            return;
+        }
+
         string normalizedDecision = request.Decision.Trim();
         string decidedByName = User?.Identity?.IsAuthenticated == true
             ? User.GetAlias() ?? User.GetName()
@@ -84,45 +97,44 @@ public class SubmitApprovalDecisionHandler(
             CreatedAt = DateTimeOffset.UtcNow,
         };
 
-        approval.State = normalizedDecision;
-        approval.CompletedAt = DateTimeOffset.UtcNow;
+        ApprovalWorkflowDecisionResult workflowDecisionResult = await approvalWorkflowRuntimeService
+            .ApplyWorkflowStepDecisionAsync(approval, contentItem, workspace, User!, decision, ct);
 
-        if (approval.Stage == "Internal")
+        if (!workflowDecisionResult.Succeeded)
         {
-            contentItem.Status = normalizedDecision switch
-            {
-                "Approved" => "Ready for client review",
-                "Changes requested" => "Changes requested internally",
-                "Rejected" => "Rejected",
-                _ => contentItem.Status,
-            };
-        }
-        else if (approval.Stage == "Client")
-        {
-            contentItem.Status = normalizedDecision switch
-            {
-                "Approved" => "Approved",
-                "Changes requested" => "Changes requested by client",
-                "Rejected" => "Rejected",
-                _ => contentItem.Status,
-            };
+            AddError(request => request.Decision, workflowDecisionResult.ErrorMessage ?? "The approval decision could not be recorded.");
+            await SendErrorsAsync(workflowDecisionResult.StatusCode, ct);
+            return;
         }
 
-        dbContext.ApprovalDecisions.Add(decision);
-        await dbContext.SaveChangesAsync(ct);
+        if (!workflowDecisionResult.IsWorkflowStep)
+        {
+            approval.State = normalizedDecision;
+            approval.CompletedAt = DateTimeOffset.UtcNow;
 
-        await notificationEventWriter.WriteAsync(
-            new NotificationEventWriteModel(
-                approval.WorkspaceId,
-                approval.ContentItemId,
-                "approval.decision.recorded",
-                "ApprovalDecision",
-                decision.Id,
-                $"{decidedByName} recorded {normalizedDecision} for {contentItem.Title}.",
-                null,
-                decidedByEmail,
-                $$"""{"stage":"{{approval.Stage}}","status":"{{contentItem.Status}}"}"""),
-            ct);
+            if (normalizedDecision == "Approved")
+            {
+                contentItem.Status = ApprovalWorkflowRules.GetFinalApprovalStatus(
+                    workspace.SchedulePostsAutomaticallyOnApproval,
+                    contentItem.DueDate);
+            }
+
+            dbContext.ApprovalDecisions.Add(decision);
+            await dbContext.SaveChangesAsync(ct);
+
+            await notificationEventWriter.WriteAsync(
+                new NotificationEventWriteModel(
+                    approval.WorkspaceId,
+                    approval.ContentItemId,
+                    "approval.decision.recorded",
+                    "ApprovalDecision",
+                    decision.Id,
+                    $"{decidedByName} recorded {normalizedDecision} for {contentItem.Title}.",
+                    null,
+                    decidedByEmail,
+                    $$"""{"stage":"{{approval.Stage}}","status":"{{contentItem.Status}}"}"""),
+                ct);
+        }
 
         List<ApprovalDecision> decisions = await dbContext.ApprovalDecisions
             .Where(candidate => candidate.ApprovalRequestId == approval.Id)
@@ -158,6 +170,11 @@ public class SubmitApprovalDecisionHandler(
             approval.Id,
             approval.WorkspaceId,
             approval.ContentItemId,
+            approval.WorkflowInstanceId,
+            approval.WorkflowStepSortOrder,
+            approval.WorkflowStepTargetType,
+            approval.WorkflowStepTargetValue,
+            approval.WorkflowStepRequiredApproverCount,
             approval.Stage,
             approval.ReviewerName,
             approval.ReviewerEmail,

backend/src/Socialize.Api/Modules/Approvals/Services/ApprovalStepConfigurationRules.cs

@@ -0,0 +1,56 @@
+using Socialize.Api.Modules.Identity.Contracts;
+
+namespace Socialize.Api.Modules.Approvals.Services;
+
+public static class ApprovalStepTargetTypes
+{
+    public const string Role = "Role";
+    public const string Membership = "Membership";
+    public const string Member = "Member";
+}
+
+public static class ApprovalMembershipTargets
+{
+    public const string Team = "Team";
+    public const string Client = "Client";
+}
+
+public static class ApprovalStepConfigurationRules
+{
+    public static readonly IReadOnlySet<string> AllowedTargetTypes = new HashSet<string>(StringComparer.Ordinal)
+    {
+        ApprovalStepTargetTypes.Role,
+        ApprovalStepTargetTypes.Membership,
+        ApprovalStepTargetTypes.Member,
+    };
+
+    public static readonly IReadOnlySet<string> AllowedRoleTargets = new HashSet<string>(StringComparer.Ordinal)
+    {
+        KnownRoles.Administrator,
+        KnownRoles.Manager,
+        KnownRoles.WorkspaceMember,
+        KnownRoles.Client,
+        KnownRoles.Provider,
+    };
+
+    public static readonly IReadOnlySet<string> AllowedMembershipTargets = new HashSet<string>(StringComparer.Ordinal)
+    {
+        ApprovalMembershipTargets.Team,
+        ApprovalMembershipTargets.Client,
+    };
+
+    public static bool IsValidTargetType(string? targetType)
+    {
+        return !string.IsNullOrWhiteSpace(targetType) && AllowedTargetTypes.Contains(targetType.Trim());
+    }
+
+    public static bool IsValidRoleTarget(string? targetValue)
+    {
+        return !string.IsNullOrWhiteSpace(targetValue) && AllowedRoleTargets.Contains(targetValue.Trim());
+    }
+
+    public static bool IsValidMembershipTarget(string? targetValue)
+    {
+        return !string.IsNullOrWhiteSpace(targetValue) && AllowedMembershipTargets.Contains(targetValue.Trim());
+    }
+}

backend/src/Socialize.Api/Modules/Approvals/Services/ApprovalWorkflowRules.cs

@@ -0,0 +1,102 @@
+using Socialize.Api.Modules.Identity.Contracts;
+
+namespace Socialize.Api.Modules.Approvals.Services;
+
+public static class ApprovalModes
+{
+    public const string None = "None";
+    public const string Optional = "Optional";
+    public const string Required = "Required";
+    public const string MultiLevel = "Multi-level";
+}
+
+public static class ApprovalWorkflowRules
+{
+    public static bool CanCreateSingleStepApprovalRequest(string approvalMode)
+    {
+        return approvalMode is ApprovalModes.Optional or ApprovalModes.Required;
+    }
+
+    public static bool BlocksManualApprovedOrScheduledStatus(string approvalMode)
+    {
+        return approvalMode is ApprovalModes.Required or ApprovalModes.MultiLevel;
+    }
+
+    public static bool IsApprovalCompletionStatus(string status)
+    {
+        return status is "Approved" or "Scheduled";
+    }
+
+    public static string GetFinalApprovalStatus(bool schedulePostsAutomaticallyOnApproval, DateTimeOffset? plannedPublishDate)
+    {
+        return schedulePostsAutomaticallyOnApproval && plannedPublishDate.HasValue
+            ? "Scheduled"
+            : "Approved";
+    }
+
+    public static bool HasRequiredStepApprovals(int approvedDecisionCount, int requiredApproverCount)
+    {
+        return approvedDecisionCount >= Math.Max(1, requiredApproverCount);
+    }
+
+    public static bool CanApproveWorkflowStep(
+        bool isAdministrator,
+        bool hasWorkspaceAccess,
+        IReadOnlyCollection<string> userRoles,
+        Guid userId,
+        string? targetType,
+        string? targetValue)
+    {
+        if (isAdministrator)
+        {
+            return true;
+        }
+
+        if (!hasWorkspaceAccess ||
+            string.IsNullOrWhiteSpace(targetType) ||
+            string.IsNullOrWhiteSpace(targetValue))
+        {
+            return false;
+        }
+
+        return targetType switch
+        {
+            ApprovalStepTargetTypes.Role => userRoles.Contains(targetValue),
+            ApprovalStepTargetTypes.Membership => MatchesMembershipTarget(userRoles, targetValue),
+            ApprovalStepTargetTypes.Member => ParseMemberTargetIds(targetValue).Contains(userId),
+            _ => false,
+        };
+    }
+
+    public static IReadOnlyCollection<Guid> ParseMemberTargetIds(string? targetValue)
+    {
+        if (string.IsNullOrWhiteSpace(targetValue))
+        {
+            return [];
+        }
+
+        return targetValue
+            .Split(',', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries)
+            .Select(value => Guid.TryParse(value, out Guid memberUserId) ? memberUserId : Guid.Empty)
+            .Where(memberUserId => memberUserId != Guid.Empty)
+            .Distinct()
+            .ToArray();
+    }
+
+    public static string FormatMemberTargetValue(IEnumerable<Guid> memberUserIds)
+    {
+        return string.Join(",", memberUserIds.Distinct().OrderBy(memberUserId => memberUserId));
+    }
+
+    private static bool MatchesMembershipTarget(
+        IReadOnlyCollection<string> userRoles,
+        string targetValue)
+    {
+        return targetValue switch
+        {
+            ApprovalMembershipTargets.Client => userRoles.Contains(KnownRoles.Client),
+            ApprovalMembershipTargets.Team => !userRoles.Contains(KnownRoles.Client),
+            _ => false,
+        };
+    }
+}

backend/src/Socialize.Api/Modules/Approvals/Services/ApprovalWorkflowRuntimeService.cs

@@ -0,0 +1,401 @@
+using System.Security.Claims;
+using System.Security.Cryptography;
+using Microsoft.EntityFrameworkCore;
+using Socialize.Api.Data;
+using Socialize.Api.Infrastructure.Security;
+using Socialize.Api.Modules.Approvals.Data;
+using Socialize.Api.Modules.ContentItems.Data;
+using Socialize.Api.Modules.Identity.Contracts;
+using Socialize.Api.Modules.Notifications.Contracts;
+using Socialize.Api.Modules.Workspaces.Data;
+
+namespace Socialize.Api.Modules.Approvals.Services;
+
+public record ApprovalWorkflowStartResult(bool Succeeded, string? ErrorMessage);
+
+public record ApprovalWorkflowDecisionResult(
+    bool Succeeded,
+    string? ErrorMessage,
+    int StatusCode,
+    bool IsWorkflowStep);
+
+public class ApprovalWorkflowRuntimeService(
+    AppDbContext dbContext,
+    INotificationEventWriter notificationEventWriter)
+{
+    private const string PendingState = "Pending";
+    private const string ApprovedState = "Approved";
+
+    public async Task<ApprovalWorkflowStartResult> StartMultiLevelWorkflowAsync(
+        ContentItem contentItem,
+        Workspace workspace,
+        Guid requestedByUserId,
+        CancellationToken ct)
+    {
+        if (workspace.ApprovalMode != ApprovalModes.MultiLevel)
+        {
+            return new ApprovalWorkflowStartResult(false, "The workspace is not configured for multi-level approval.");
+        }
+
+        ApprovalWorkflowInstance? activeWorkflow = await dbContext.ApprovalWorkflowInstances
+            .SingleOrDefaultAsync(
+                workflow => workflow.ContentItemId == contentItem.Id && workflow.State == PendingState,
+                ct);
+        if (activeWorkflow is not null)
+        {
+            contentItem.Status = "In approval";
+            return new ApprovalWorkflowStartResult(true, null);
+        }
+
+        List<WorkspaceApprovalStepConfiguration> configuredSteps = await dbContext.WorkspaceApprovalStepConfigurations
+            .Where(step => step.WorkspaceId == workspace.Id)
+            .OrderBy(step => step.SortOrder)
+            .ThenBy(step => step.Name)
+            .ToListAsync(ct);
+
+        if (configuredSteps.Count == 0)
+        {
+            return new ApprovalWorkflowStartResult(false, "Multi-level approval requires at least one configured approval step.");
+        }
+
+        DateTimeOffset now = DateTimeOffset.UtcNow;
+        var workflowInstance = new ApprovalWorkflowInstance
+        {
+            Id = Guid.NewGuid(),
+            WorkspaceId = workspace.Id,
+            ContentItemId = contentItem.Id,
+            State = PendingState,
+            ApprovalMode = workspace.ApprovalMode,
+            StartedAt = now,
+        };
+
+        List<ApprovalRequest> workflowSteps = configuredSteps
+            .Select((step, index) => new ApprovalRequest
+            {
+                Id = Guid.NewGuid(),
+                WorkspaceId = workspace.Id,
+                ContentItemId = contentItem.Id,
+                WorkflowInstanceId = workflowInstance.Id,
+                WorkflowStepSortOrder = index,
+                WorkflowStepTargetType = step.TargetType,
+                WorkflowStepTargetValue = step.TargetValue,
+                WorkflowStepRequiredApproverCount = step.RequiredApproverCount,
+                Stage = step.Name,
+                ReviewerName = FormatStepTarget(step),
+                ReviewerEmail = string.Empty,
+                RequestedByUserId = requestedByUserId,
+                DueAt = contentItem.DueDate,
+                State = PendingState,
+                AccessToken = CreateAccessToken(),
+                SentAt = now,
+            })
+            .ToList();
+
+        dbContext.ApprovalWorkflowInstances.Add(workflowInstance);
+        dbContext.ApprovalRequests.AddRange(workflowSteps);
+        contentItem.Status = "In approval";
+
+        await dbContext.SaveChangesAsync(ct);
+        await NotifyCurrentStepApproversAsync(workflowSteps[0], contentItem, ct);
+
+        return new ApprovalWorkflowStartResult(true, null);
+    }
+
+    public async Task<ApprovalWorkflowDecisionResult> ApplyWorkflowStepDecisionAsync(
+        ApprovalRequest approval,
+        ContentItem contentItem,
+        Workspace workspace,
+        ClaimsPrincipal user,
+        ApprovalDecision decision,
+        CancellationToken ct)
+    {
+        if (!approval.WorkflowInstanceId.HasValue)
+        {
+            return new ApprovalWorkflowDecisionResult(true, null, StatusCodes.Status200OK, false);
+        }
+
+        if (user.Identity?.IsAuthenticated != true)
+        {
+            return new ApprovalWorkflowDecisionResult(false, "Multi-level approval steps require an authenticated approver.", StatusCodes.Status401Unauthorized, true);
+        }
+
+        if (!await CanApproveStepAsync(user, approval, workspace.Id, ct))
+        {
+            return new ApprovalWorkflowDecisionResult(false, "You cannot approve the current workflow step.", StatusCodes.Status403Forbidden, true);
+        }
+
+        ApprovalRequest? currentStep = await GetCurrentPendingStepAsync(approval.WorkflowInstanceId.Value, ct);
+        if (currentStep?.Id != approval.Id)
+        {
+            return new ApprovalWorkflowDecisionResult(false, "Only the current pending approval step can be approved.", StatusCodes.Status409Conflict, true);
+        }
+
+        Guid currentUserId = user.GetUserId();
+        bool alreadyApproved = await dbContext.ApprovalDecisions.AnyAsync(
+            candidate => candidate.ApprovalRequestId == approval.Id &&
+                         candidate.DecidedByUserId == currentUserId &&
+                         candidate.Decision == ApprovedState,
+            ct);
+
+        if (alreadyApproved)
+        {
+            return new ApprovalWorkflowDecisionResult(false, "You have already approved this workflow step.", StatusCodes.Status409Conflict, true);
+        }
+
+        dbContext.ApprovalDecisions.Add(decision);
+        await dbContext.SaveChangesAsync(ct);
+
+        int approvedCount = await dbContext.ApprovalDecisions
+            .Where(candidate => candidate.ApprovalRequestId == approval.Id && candidate.Decision == ApprovedState)
+            .Select(candidate => candidate.DecidedByUserId.HasValue
+                ? candidate.DecidedByUserId.Value.ToString()
+                : candidate.DecidedByEmail.ToLower())
+            .Distinct()
+            .CountAsync(ct);
+
+        int requiredApproverCount = approval.WorkflowStepRequiredApproverCount ?? 1;
+        if (!ApprovalWorkflowRules.HasRequiredStepApprovals(approvedCount, requiredApproverCount))
+        {
+            return new ApprovalWorkflowDecisionResult(true, null, StatusCodes.Status200OK, true);
+        }
+
+        approval.State = ApprovedState;
+        approval.CompletedAt = DateTimeOffset.UtcNow;
+
+        ApprovalRequest? nextStep = await dbContext.ApprovalRequests
+            .Where(candidate => candidate.WorkflowInstanceId == approval.WorkflowInstanceId &&
+                                candidate.State == PendingState &&
+                                candidate.Id != approval.Id)
+            .OrderBy(candidate => candidate.WorkflowStepSortOrder)
+            .ThenBy(candidate => candidate.SentAt)
+            .FirstOrDefaultAsync(ct);
+
+        if (nextStep is null)
+        {
+            ApprovalWorkflowInstance? workflowInstance = await dbContext.ApprovalWorkflowInstances
+                .SingleOrDefaultAsync(candidate => candidate.Id == approval.WorkflowInstanceId.Value, ct);
+            if (workflowInstance is null)
+            {
+                return new ApprovalWorkflowDecisionResult(false, "The approval workflow instance could not be found.", StatusCodes.Status404NotFound, true);
+            }
+
+            workflowInstance.State = ApprovedState;
+            workflowInstance.CompletedAt = DateTimeOffset.UtcNow;
+            contentItem.Status = ApprovalWorkflowRules.GetFinalApprovalStatus(
+                workspace.SchedulePostsAutomaticallyOnApproval,
+                contentItem.DueDate);
+        }
+
+        await dbContext.SaveChangesAsync(ct);
+
+        if (nextStep is null)
+        {
+            await NotifyPublishUsersAsync(approval, contentItem, ct);
+        }
+        else
+        {
+            await NotifyCurrentStepApproversAsync(nextStep, contentItem, ct);
+        }
+
+        return new ApprovalWorkflowDecisionResult(true, null, StatusCodes.Status200OK, true);
+    }
+
+    public async Task<bool> HasCompletedMultiLevelWorkflowAsync(Guid contentItemId, CancellationToken ct)
+    {
+        return await dbContext.ApprovalWorkflowInstances.AnyAsync(
+            workflow => workflow.ContentItemId == contentItemId && workflow.State == ApprovedState,
+            ct);
+    }
+
+    private async Task<ApprovalRequest?> GetCurrentPendingStepAsync(Guid workflowInstanceId, CancellationToken ct)
+    {
+        return await dbContext.ApprovalRequests
+            .Where(candidate => candidate.WorkflowInstanceId == workflowInstanceId && candidate.State == PendingState)
+            .OrderBy(candidate => candidate.WorkflowStepSortOrder)
+            .ThenBy(candidate => candidate.SentAt)
+            .FirstOrDefaultAsync(ct);
+    }
+
+    private async Task<bool> CanApproveStepAsync(
+        ClaimsPrincipal user,
+        ApprovalRequest approval,
+        Guid workspaceId,
+        CancellationToken ct)
+    {
+        Guid userId = user.GetUserId();
+        bool hasWorkspaceAccess = await UserHasWorkspaceAccessAsync(userId, workspaceId, ct);
+        string[] userRoles = ApprovalStepConfigurationRules.AllowedRoleTargets
+            .Where(user.IsInRole)
+            .ToArray();
+
+        return ApprovalWorkflowRules.CanApproveWorkflowStep(
+            user.IsInRole(KnownRoles.Administrator),
+            hasWorkspaceAccess,
+            userRoles,
+            userId,
+            approval.WorkflowStepTargetType,
+            approval.WorkflowStepTargetValue);
+    }
+
+    private async Task<bool> UserHasWorkspaceAccessAsync(Guid userId, Guid workspaceId, CancellationToken ct)
+    {
+        string workspaceClaimValue = workspaceId.ToString();
+        return await dbContext.UserClaims.AnyAsync(
+            claim => claim.UserId == userId &&
+                     claim.ClaimType == KnownClaims.WorkspaceScope &&
+                     claim.ClaimValue == workspaceClaimValue,
+            ct);
+    }
+
+    private async Task NotifyCurrentStepApproversAsync(
+        ApprovalRequest approval,
+        ContentItem contentItem,
+        CancellationToken ct)
+    {
+        List<ApprovalNotificationRecipient> recipients = await GetStepApproverRecipientsAsync(approval, ct);
+
+        foreach (ApprovalNotificationRecipient recipient in recipients)
+        {
+            await notificationEventWriter.WriteAsync(
+                new NotificationEventWriteModel(
+                    approval.WorkspaceId,
+                    approval.ContentItemId,
+                    "approval.step.current",
+                    "ApprovalRequest",
+                    approval.Id,
+                    $"{approval.Stage} approval is ready for {contentItem.Title}.",
+                    recipient.UserId,
+                    recipient.Email,
+                    $$"""{"stage":"{{approval.Stage}}","requiredApproverCount":{{approval.WorkflowStepRequiredApproverCount ?? 1}}}"""),
+                ct);
+        }
+    }
+
+    private async Task NotifyPublishUsersAsync(
+        ApprovalRequest approval,
+        ContentItem contentItem,
+        CancellationToken ct)
+    {
+        List<ApprovalNotificationRecipient> recipients = await GetPublishRecipientUsersAsync(approval.WorkspaceId, ct);
+
+        foreach (ApprovalNotificationRecipient recipient in recipients)
+        {
+            await notificationEventWriter.WriteAsync(
+                new NotificationEventWriteModel(
+                    approval.WorkspaceId,
+                    approval.ContentItemId,
+                    "approval.workflow.completed",
+                    "ApprovalWorkflowInstance",
+                    approval.WorkflowInstanceId!.Value,
+                    $"Final approval completed for {contentItem.Title}.",
+                    recipient.UserId,
+                    recipient.Email,
+                    $$"""{"status":"{{contentItem.Status}}"}"""),
+                ct);
+        }
+    }
+
+    private async Task<List<ApprovalNotificationRecipient>> GetStepApproverRecipientsAsync(
+        ApprovalRequest approval,
+        CancellationToken ct)
+    {
+        string? targetType = approval.WorkflowStepTargetType;
+        string? targetValue = approval.WorkflowStepTargetValue;
+        if (string.IsNullOrWhiteSpace(targetType) || string.IsNullOrWhiteSpace(targetValue))
+        {
+            return [];
+        }
+
+        return targetType switch
+        {
+            ApprovalStepTargetTypes.Member => await GetMemberRecipientsAsync(targetValue, ct),
+            ApprovalStepTargetTypes.Role => await GetRoleRecipientsAsync(approval.WorkspaceId, [targetValue], ct),
+            ApprovalStepTargetTypes.Membership => await GetMembershipRecipientsAsync(approval.WorkspaceId, targetValue, ct),
+            _ => [],
+        };
+    }
+
+    private async Task<List<ApprovalNotificationRecipient>> GetMemberRecipientsAsync(string targetValue, CancellationToken ct)
+    {
+        IReadOnlyCollection<Guid> userIds = ApprovalWorkflowRules.ParseMemberTargetIds(targetValue);
+        if (userIds.Count == 0)
+        {
+            return [];
+        }
+
+        return await dbContext.Users
+            .Where(user => userIds.Contains(user.Id))
+            .Select(user => new ApprovalNotificationRecipient(user.Id, user.Email))
+            .ToListAsync(ct);
+    }
+
+    private async Task<List<ApprovalNotificationRecipient>> GetMembershipRecipientsAsync(
+        Guid workspaceId,
+        string targetValue,
+        CancellationToken ct)
+    {
+        string[] roles = targetValue switch
+        {
+            ApprovalMembershipTargets.Client => [KnownRoles.Client],
+            ApprovalMembershipTargets.Team => [KnownRoles.Administrator, KnownRoles.Manager, KnownRoles.WorkspaceMember, KnownRoles.Provider],
+            _ => [],
+        };
+
+        return roles.Length == 0
+            ? []
+            : await GetRoleRecipientsAsync(workspaceId, roles, ct);
+    }
+
+    private async Task<List<ApprovalNotificationRecipient>> GetPublishRecipientUsersAsync(Guid workspaceId, CancellationToken ct)
+    {
+        return await GetRoleRecipientsAsync(workspaceId, [KnownRoles.Administrator, KnownRoles.Manager], ct);
+    }
+
+    private async Task<List<ApprovalNotificationRecipient>> GetRoleRecipientsAsync(
+        Guid workspaceId,
+        IReadOnlyCollection<string> roles,
+        CancellationToken ct)
+    {
+        string workspaceClaimValue = workspaceId.ToString();
+
+        return await dbContext.UserRoles
+            .Join(
+                dbContext.Roles,
+                userRole => userRole.RoleId,
+                role => role.Id,
+                (userRole, role) => new { userRole.UserId, RoleName = role.Name })
+            .Where(candidate => candidate.RoleName != null && roles.Contains(candidate.RoleName))
+            .Join(
+                dbContext.UserClaims.Where(claim =>
+                    claim.ClaimType == KnownClaims.WorkspaceScope &&
+                    claim.ClaimValue == workspaceClaimValue),
+                candidate => candidate.UserId,
+                claim => claim.UserId,
+                (candidate, _) => candidate.UserId)
+            .Distinct()
+            .Join(
+                dbContext.Users,
+                userId => userId,
+                user => user.Id,
+                (_, user) => new ApprovalNotificationRecipient(user.Id, user.Email))
+            .ToListAsync(ct);
+    }
+
+    private static string FormatStepTarget(WorkspaceApprovalStepConfiguration step)
+    {
+        return step.TargetType switch
+        {
+            ApprovalStepTargetTypes.Role => $"Role: {step.TargetValue}",
+            ApprovalStepTargetTypes.Membership => $"Membership: {step.TargetValue}",
+            ApprovalStepTargetTypes.Member => "Assigned members",
+            _ => step.TargetValue,
+        };
+    }
+
+    private static string CreateAccessToken()
+    {
+        return Convert.ToHexString(RandomNumberGenerator.GetBytes(16)).ToLowerInvariant();
+    }
+
+    private sealed record ApprovalNotificationRecipient(Guid UserId, string? Email);
+}

backend/src/Socialize.Api/Modules/ContentItems/Handlers/CreateContentItemRevision.cs

@@ -66,15 +66,6 @@ public class CreateContentItemRevisionHandler(
         item.CurrentRevisionNumber = revisionNumber;
         item.CurrentRevisionLabel = revisionLabel;
 
-        if (item.Status == "Changes requested internally")
-        {
-            item.Status = "Internal changes in progress";
-        }
-        else if (item.Status == "Changes requested by client")
-        {
-            item.Status = "Client changes in progress";
-        }
-
         ContentItemRevision revision = new()
         {
             Id = Guid.NewGuid(),

backend/src/Socialize.Api/Modules/ContentItems/Handlers/UpdateContentItemStatus.cs

@@ -2,8 +2,10 @@ using FastEndpoints;
 using Microsoft.EntityFrameworkCore;
 using Socialize.Api.Data;
 using Socialize.Api.Infrastructure.Security;
+using Socialize.Api.Modules.Approvals.Services;
 using Socialize.Api.Modules.ContentItems.Data;
 using Socialize.Api.Modules.Notifications.Contracts;
+using Socialize.Api.Modules.Workspaces.Data;
 
 namespace Socialize.Api.Modules.ContentItems.Handlers;
 
@@ -21,24 +23,18 @@ public class UpdateContentItemStatusRequestValidator
 public class UpdateContentItemStatusHandler(
     AppDbContext dbContext,
     AccessScopeService accessScopeService,
+    ApprovalWorkflowRuntimeService approvalWorkflowRuntimeService,
     INotificationEventWriter notificationEventWriter)
     : Endpoint<UpdateContentItemStatusRequest, ContentItemDetailDto>
 {
     private static readonly HashSet<string> AllowedStatuses =
     [
         "Draft",
-        "In internal review",
-        "Changes requested internally",
-        "Internal changes in progress",
-        "Ready for client review",
-        "In client review",
-        "Changes requested by client",
-        "Client changes in progress",
+        "In production",
+        "In approval",
         "Approved",
-        "Rejected",
-        "Ready to publish",
+        "Scheduled",
         "Published",
-        "Archived",
     ];
 
     public override void Configure()
@@ -72,7 +68,64 @@ public class UpdateContentItemStatusHandler(
             return;
         }
 
-        item.Status = normalizedStatus;
+        Workspace? workspace = await dbContext.Workspaces.SingleOrDefaultAsync(candidate => candidate.Id == item.WorkspaceId, ct);
+        if (workspace is null)
+        {
+            await SendNotFoundAsync(ct);
+            return;
+        }
+
+        if (normalizedStatus == "In approval" && workspace.ApprovalMode == ApprovalModes.MultiLevel)
+        {
+            ApprovalWorkflowStartResult startResult = await approvalWorkflowRuntimeService.StartMultiLevelWorkflowAsync(
+                item,
+                workspace,
+                User.GetUserId(),
+                ct);
+
+            if (!startResult.Succeeded)
+            {
+                AddError(request => request.Status, startResult.ErrorMessage ?? "The approval workflow could not be started.");
+                await SendErrorsAsync(StatusCodes.Status409Conflict, ct);
+                return;
+            }
+        }
+        else if (ApprovalWorkflowRules.IsApprovalCompletionStatus(normalizedStatus) &&
+            ApprovalWorkflowRules.BlocksManualApprovedOrScheduledStatus(workspace.ApprovalMode))
+        {
+            if (workspace.ApprovalMode == ApprovalModes.MultiLevel)
+            {
+                bool hasCompletedWorkflow = await approvalWorkflowRuntimeService.HasCompletedMultiLevelWorkflowAsync(item.Id, ct);
+
+                if (!hasCompletedWorkflow)
+                {
+                    AddError(request => request.Status, "This workspace requires the multi-level approval workflow to complete before content can be approved or scheduled.");
+                    await SendErrorsAsync(StatusCodes.Status409Conflict, ct);
+                    return;
+                }
+            }
+            else
+            {
+                bool hasApprovedDecision = await dbContext.ApprovalRequests.AnyAsync(
+                    approval => approval.ContentItemId == item.Id &&
+                                approval.WorkspaceId == item.WorkspaceId &&
+                                approval.State == "Approved" &&
+                                approval.CompletedAt.HasValue,
+                    ct);
+
+                if (!hasApprovedDecision)
+                {
+                    AddError(request => request.Status, "This workspace requires approval before content can be approved or scheduled.");
+                    await SendErrorsAsync(StatusCodes.Status409Conflict, ct);
+                    return;
+                }
+            }
+        }
+
+        if (item.Status != "In approval" || normalizedStatus != "In approval")
+        {
+            item.Status = normalizedStatus;
+        }
         await dbContext.SaveChangesAsync(ct);
 
         await notificationEventWriter.WriteAsync(

backend/src/Socialize.Api/Modules/Workspaces/Data/Workspace.cs

@@ -8,5 +8,9 @@ public class Workspace
     public string? LogoUrl { get; set; }
     public Guid OwnerUserId { get; set; }
     public required string TimeZone { get; set; }
+    public string ApprovalMode { get; set; } = "Required";
+    public bool SchedulePostsAutomaticallyOnApproval { get; set; }
+    public bool LockContentAfterApproval { get; set; }
+    public bool SendAutomaticApprovalReminders { get; set; }
     public DateTimeOffset CreatedAt { get; init; }
 }

backend/src/Socialize.Api/Modules/Workspaces/Data/WorkspaceModelConfiguration.cs

@@ -14,6 +14,10 @@ public static class WorkspaceModelConfiguration
             workspace.Property(x => x.Slug).HasMaxLength(128).IsRequired();
             workspace.Property(x => x.LogoUrl).HasMaxLength(2048);
             workspace.Property(x => x.TimeZone).HasMaxLength(128).IsRequired();
+            workspace.Property(x => x.ApprovalMode).HasMaxLength(32).IsRequired().HasDefaultValue("Required");
+            workspace.Property(x => x.SchedulePostsAutomaticallyOnApproval).HasDefaultValue(false);
+            workspace.Property(x => x.LockContentAfterApproval).HasDefaultValue(false);
+            workspace.Property(x => x.SendAutomaticApprovalReminders).HasDefaultValue(false);
             workspace.Property(x => x.CreatedAt)
                 .ValueGeneratedOnAdd()
                 .HasDefaultValueSql("CURRENT_TIMESTAMP");

backend/src/Socialize.Api/Modules/Workspaces/Handlers/CreateWorkspace.cs

@@ -77,6 +77,11 @@ public class CreateWorkspaceHandler(
             workspace.Slug,
             workspace.LogoUrl,
             workspace.TimeZone,
+            workspace.ApprovalMode,
+            workspace.SchedulePostsAutomaticallyOnApproval,
+            workspace.LockContentAfterApproval,
+            workspace.SendAutomaticApprovalReminders,
+            [],
             workspace.CreatedAt);
 
         await SendAsync(dto, StatusCodes.Status201Created, ct);

backend/src/Socialize.Api/Modules/Workspaces/Handlers/GetWorkspaces.cs

@@ -2,16 +2,32 @@ using FastEndpoints;
 using Microsoft.EntityFrameworkCore;
 using Socialize.Api.Data;
 using Socialize.Api.Infrastructure.Security;
+using Socialize.Api.Modules.Approvals.Data;
 using Socialize.Api.Modules.Workspaces.Data;
 
 namespace Socialize.Api.Modules.Workspaces.Handlers;
 
+public record ApprovalStepConfigurationDto(
+    Guid Id,
+    Guid WorkspaceId,
+    string Name,
+    int SortOrder,
+    string TargetType,
+    string TargetValue,
+    int RequiredApproverCount,
+    DateTimeOffset CreatedAt);
+
 public record WorkspaceDto(
     Guid Id,
     string Name,
     string Slug,
     string? LogoUrl,
     string TimeZone,
+    string ApprovalMode,
+    bool SchedulePostsAutomaticallyOnApproval,
+    bool LockContentAfterApproval,
+    bool SendAutomaticApprovalReminders,
+    IReadOnlyCollection<ApprovalStepConfigurationDto> ApprovalSteps,
     DateTimeOffset CreatedAt);
 
 internal class GetWorkspacesHandler(
@@ -35,17 +51,53 @@ internal class GetWorkspacesHandler(
             query = query.Where(workspace => workspaceScopeIds.Contains(workspace.Id));
         }
 
-        var workspaces = await query
+        var workspaceRows = await query
             .OrderBy(workspace => workspace.Name)
+            .ToListAsync(ct);
+
+        var workspaceIds = workspaceRows.Select(workspace => workspace.Id).ToList();
+        List<WorkspaceApprovalStepConfiguration> approvalStepRows = await dbContext.WorkspaceApprovalStepConfigurations
+            .Where(step => workspaceIds.Contains(step.WorkspaceId))
+            .OrderBy(step => step.SortOrder)
+            .ThenBy(step => step.Name)
+            .ToListAsync(ct);
+
+        var approvalStepsByWorkspaceId = approvalStepRows
+            .GroupBy(step => step.WorkspaceId)
+            .ToDictionary(
+                group => group.Key,
+                group => (IReadOnlyCollection<ApprovalStepConfigurationDto>)group
+                    .Select(ToApprovalStepConfigurationDto)
+                    .ToArray());
+
+        var workspaces = workspaceRows
             .Select(workspace => new WorkspaceDto(
                 workspace.Id,
                 workspace.Name,
                 workspace.Slug,
                 workspace.LogoUrl,
                 workspace.TimeZone,
+                workspace.ApprovalMode,
+                workspace.SchedulePostsAutomaticallyOnApproval,
+                workspace.LockContentAfterApproval,
+                workspace.SendAutomaticApprovalReminders,
+                approvalStepsByWorkspaceId.GetValueOrDefault(workspace.Id) ?? Array.Empty<ApprovalStepConfigurationDto>(),
                 workspace.CreatedAt))
-            .ToListAsync(ct);
+            .ToList();
 
         await SendOkAsync(workspaces, ct);
     }
+
+    public static ApprovalStepConfigurationDto ToApprovalStepConfigurationDto(WorkspaceApprovalStepConfiguration step)
+    {
+        return new ApprovalStepConfigurationDto(
+            step.Id,
+            step.WorkspaceId,
+            step.Name,
+            step.SortOrder,
+            step.TargetType,
+            step.TargetValue,
+            step.RequiredApproverCount,
+            step.CreatedAt);
+    }
 }

backend/src/Socialize.Api/Modules/Workspaces/Handlers/UpdateWorkspace.cs

@@ -2,21 +2,52 @@ using FastEndpoints;
 using Microsoft.EntityFrameworkCore;
 using Socialize.Api.Data;
 using Socialize.Api.Infrastructure.Security;
+using Socialize.Api.Modules.Approvals.Data;
+using Socialize.Api.Modules.Approvals.Services;
 using Socialize.Api.Modules.Workspaces.Data;
 
 namespace Socialize.Api.Modules.Workspaces.Handlers;
 
+public record UpdateApprovalStepConfigurationRequest(
+    string Name,
+    int SortOrder,
+    string TargetType,
+    string TargetValue,
+    int RequiredApproverCount);
+
 public record UpdateWorkspaceRequest(
     string Name,
-    string TimeZone);
+    string TimeZone,
+    string? ApprovalMode,
+    bool? SchedulePostsAutomaticallyOnApproval,
+    bool? LockContentAfterApproval,
+    bool? SendAutomaticApprovalReminders,
+    IReadOnlyCollection<UpdateApprovalStepConfigurationRequest>? ApprovalSteps);
 
 public class UpdateWorkspaceRequestValidator
     : Validator<UpdateWorkspaceRequest>
 {
+    private static readonly string[] AllowedApprovalModes = ["None", "Optional", "Required", "Multi-level"];
+
     public UpdateWorkspaceRequestValidator()
     {
         RuleFor(x => x.Name).NotEmpty().MaximumLength(256);
         RuleFor(x => x.TimeZone).NotEmpty().MaximumLength(128);
+        RuleFor(x => x.ApprovalMode)
+            .Must(mode => string.IsNullOrWhiteSpace(mode) || AllowedApprovalModes.Contains(mode.Trim()))
+            .WithMessage("A valid approval mode should be specified.");
+        RuleFor(x => x.ApprovalSteps)
+            .Must(steps => steps is null || steps.Select(step => step.SortOrder).Distinct().Count() == steps.Count)
+            .WithMessage("Approval step sort orders must be unique.");
+        RuleForEach(x => x.ApprovalSteps).ChildRules(step =>
+        {
+            step.RuleFor(x => x.Name).NotEmpty().MaximumLength(128);
+            step.RuleFor(x => x.TargetType)
+                .Must(ApprovalStepConfigurationRules.IsValidTargetType)
+                .WithMessage("A valid approval step target type should be specified.");
+            step.RuleFor(x => x.TargetValue).NotEmpty().MaximumLength(128);
+            step.RuleFor(x => x.RequiredApproverCount).GreaterThanOrEqualTo(1);
+        });
     }
 }
 
@@ -48,19 +79,162 @@ public class UpdateWorkspaceHandler(
             return;
         }
 
+        string nextApprovalMode = string.IsNullOrWhiteSpace(request.ApprovalMode)
+            ? workspace.ApprovalMode
+            : request.ApprovalMode.Trim();
+        List<UpdateApprovalStepConfigurationRequest>? requestedApprovalSteps = request.ApprovalSteps?.ToList();
+
+        if (nextApprovalMode == ApprovalModes.MultiLevel)
+        {
+            bool hasConfiguredSteps = requestedApprovalSteps is null
+                ? await dbContext.WorkspaceApprovalStepConfigurations.AnyAsync(step => step.WorkspaceId == workspace.Id, ct)
+                : requestedApprovalSteps.Count > 0;
+
+            if (!hasConfiguredSteps)
+            {
+                AddError(request => request.ApprovalSteps, "Multi-level approval requires at least one approval step.");
+                await SendErrorsAsync(StatusCodes.Status400BadRequest, ct);
+                return;
+            }
+        }
+
+        if (requestedApprovalSteps is not null &&
+            !await ValidateApprovalStepsAsync(workspace.Id, requestedApprovalSteps, ct))
+        {
+            await SendErrorsAsync(StatusCodes.Status400BadRequest, ct);
+            return;
+        }
+
         workspace.Name = request.Name.Trim();
         workspace.TimeZone = request.TimeZone.Trim();
+        workspace.ApprovalMode = nextApprovalMode;
+        workspace.SchedulePostsAutomaticallyOnApproval = request.SchedulePostsAutomaticallyOnApproval ?? workspace.SchedulePostsAutomaticallyOnApproval;
+        workspace.LockContentAfterApproval = request.LockContentAfterApproval ?? workspace.LockContentAfterApproval;
+        workspace.SendAutomaticApprovalReminders = request.SendAutomaticApprovalReminders ?? workspace.SendAutomaticApprovalReminders;
+
+        if (requestedApprovalSteps is not null)
+        {
+            List<WorkspaceApprovalStepConfiguration> existingSteps = await dbContext.WorkspaceApprovalStepConfigurations
+                .Where(step => step.WorkspaceId == workspace.Id)
+                .ToListAsync(ct);
+            dbContext.WorkspaceApprovalStepConfigurations.RemoveRange(existingSteps);
+
+            List<WorkspaceApprovalStepConfiguration> replacementSteps = requestedApprovalSteps
+                .OrderBy(step => step.SortOrder)
+                .Select(step => new WorkspaceApprovalStepConfiguration
+                {
+                    Id = Guid.NewGuid(),
+                    WorkspaceId = workspace.Id,
+                    Name = step.Name.Trim(),
+                    SortOrder = step.SortOrder,
+                    TargetType = step.TargetType.Trim(),
+                    TargetValue = NormalizeTargetValue(step),
+                    RequiredApproverCount = step.RequiredApproverCount,
+                    CreatedAt = DateTimeOffset.UtcNow,
+                })
+                .ToList();
+
+            dbContext.WorkspaceApprovalStepConfigurations.AddRange(replacementSteps);
+        }
 
         await dbContext.SaveChangesAsync(ct);
 
+        List<ApprovalStepConfigurationDto> approvalSteps = await dbContext.WorkspaceApprovalStepConfigurations
+            .Where(step => step.WorkspaceId == workspace.Id)
+            .OrderBy(step => step.SortOrder)
+            .ThenBy(step => step.Name)
+            .Select(step => new ApprovalStepConfigurationDto(
+                step.Id,
+                step.WorkspaceId,
+                step.Name,
+                step.SortOrder,
+                step.TargetType,
+                step.TargetValue,
+                step.RequiredApproverCount,
+                step.CreatedAt))
+            .ToListAsync(ct);
+
         WorkspaceDto dto = new(
             workspace.Id,
             workspace.Name,
             workspace.Slug,
             workspace.LogoUrl,
             workspace.TimeZone,
+            workspace.ApprovalMode,
+            workspace.SchedulePostsAutomaticallyOnApproval,
+            workspace.LockContentAfterApproval,
+            workspace.SendAutomaticApprovalReminders,
+            approvalSteps,
             workspace.CreatedAt);
 
         await SendOkAsync(dto, ct);
     }
+
+    private async Task<bool> ValidateApprovalStepsAsync(
+        Guid workspaceId,
+        IReadOnlyCollection<UpdateApprovalStepConfigurationRequest> steps,
+        CancellationToken ct)
+    {
+        foreach (UpdateApprovalStepConfigurationRequest step in steps)
+        {
+            string targetType = step.TargetType.Trim();
+            string targetValue = step.TargetValue.Trim();
+
+            if (targetType == ApprovalStepTargetTypes.Role &&
+                !ApprovalStepConfigurationRules.IsValidRoleTarget(targetValue))
+            {
+                AddError(request => request.ApprovalSteps, $"'{targetValue}' is not a supported approval role target.");
+                return false;
+            }
+
+            if (targetType == ApprovalStepTargetTypes.Membership &&
+                !ApprovalStepConfigurationRules.IsValidMembershipTarget(targetValue))
+            {
+                AddError(request => request.ApprovalSteps, $"'{targetValue}' is not a supported approval membership target.");
+                return false;
+            }
+
+            if (targetType == ApprovalStepTargetTypes.Member)
+            {
+                IReadOnlyCollection<Guid> memberUserIds = ApprovalWorkflowRules.ParseMemberTargetIds(targetValue);
+
+                if (memberUserIds.Count == 0)
+                {
+                    AddError(request => request.ApprovalSteps, "Member approval step targets must reference at least one valid user id.");
+                    return false;
+                }
+
+                if (memberUserIds.Count < step.RequiredApproverCount)
+                {
+                    AddError(request => request.ApprovalSteps, "Member approval step targets must include at least as many members as required approvers.");
+                    return false;
+                }
+
+                string workspaceClaimValue = workspaceId.ToString();
+                int workspaceMemberCount = await dbContext.UserClaims
+                    .Where(claim => memberUserIds.Contains(claim.UserId) &&
+                                    claim.ClaimType == KnownClaims.WorkspaceScope &&
+                                    claim.ClaimValue == workspaceClaimValue)
+                    .Select(claim => claim.UserId)
+                    .Distinct()
+                    .CountAsync(ct);
+
+                if (workspaceMemberCount != memberUserIds.Count)
+                {
+                    AddError(request => request.ApprovalSteps, "Member approval step targets must reference users with access to the workspace.");
+                    return false;
+                }
+            }
+        }
+
+        return true;
+    }
+
+    private static string NormalizeTargetValue(UpdateApprovalStepConfigurationRequest step)
+    {
+        string targetValue = step.TargetValue.Trim();
+        return step.TargetType.Trim() == ApprovalStepTargetTypes.Member
+            ? ApprovalWorkflowRules.FormatMemberTargetValue(ApprovalWorkflowRules.ParseMemberTargetIds(targetValue))
+            : targetValue;
+    }
 }

backend/tests/Socialize.Tests/Approvals/ApprovalWorkflowRulesTests.cs

@@ -0,0 +1,350 @@
+using Microsoft.EntityFrameworkCore;
+using Socialize.Api.Data;
+using Socialize.Api.Modules.Approvals.Data;
+using Socialize.Api.Modules.Approvals.Services;
+
+namespace Socialize.Tests.Approvals;
+
+public class ApprovalWorkflowRulesTests
+{
+    [Theory]
+    [InlineData(ApprovalModes.Optional, true)]
+    [InlineData(ApprovalModes.Required, true)]
+    [InlineData(ApprovalModes.None, false)]
+    [InlineData(ApprovalModes.MultiLevel, false)]
+    public void CanCreateSingleStepApprovalRequest_matches_basic_modes(string approvalMode, bool expected)
+    {
+        bool actual = ApprovalWorkflowRules.CanCreateSingleStepApprovalRequest(approvalMode);
+
+        Assert.Equal(expected, actual);
+    }
+
+    [Theory]
+    [InlineData(ApprovalModes.Required, true)]
+    [InlineData(ApprovalModes.MultiLevel, true)]
+    [InlineData(ApprovalModes.Optional, false)]
+    [InlineData(ApprovalModes.None, false)]
+    public void BlocksManualApprovedOrScheduledStatus_matches_blocking_modes(string approvalMode, bool expected)
+    {
+        bool actual = ApprovalWorkflowRules.BlocksManualApprovedOrScheduledStatus(approvalMode);
+
+        Assert.Equal(expected, actual);
+    }
+
+    [Theory]
+    [InlineData("Approved", true)]
+    [InlineData("Scheduled", true)]
+    [InlineData("In approval", false)]
+    [InlineData("Published", false)]
+    public void IsApprovalCompletionStatus_only_matches_approval_gate_destinations(string status, bool expected)
+    {
+        bool actual = ApprovalWorkflowRules.IsApprovalCompletionStatus(status);
+
+        Assert.Equal(expected, actual);
+    }
+
+    [Fact]
+    public void GetFinalApprovalStatus_schedules_when_option_enabled_and_publish_date_exists()
+    {
+        string status = ApprovalWorkflowRules.GetFinalApprovalStatus(
+            schedulePostsAutomaticallyOnApproval: true,
+            plannedPublishDate: DateTimeOffset.UtcNow.AddDays(1));
+
+        Assert.Equal("Scheduled", status);
+    }
+
+    [Theory]
+    [InlineData(false)]
+    [InlineData(true)]
+    public void GetFinalApprovalStatus_approves_when_auto_schedule_disabled_or_date_missing(bool scheduleAutomatically)
+    {
+        string status = ApprovalWorkflowRules.GetFinalApprovalStatus(
+            scheduleAutomatically,
+            plannedPublishDate: null);
+
+        Assert.Equal("Approved", status);
+    }
+
+    [Theory]
+    [InlineData(1, 1, true)]
+    [InlineData(1, 2, false)]
+    [InlineData(2, 2, true)]
+    [InlineData(1, 0, true)]
+    public void HasRequiredStepApprovals_enforces_configured_approver_count(
+        int approvedDecisionCount,
+        int requiredApproverCount,
+        bool expected)
+    {
+        bool actual = ApprovalWorkflowRules.HasRequiredStepApprovals(
+            approvedDecisionCount,
+            requiredApproverCount);
+
+        Assert.Equal(expected, actual);
+    }
+
+    [Fact]
+    public void CanApproveWorkflowStep_allows_admin_for_any_step_target()
+    {
+        bool actual = ApprovalWorkflowRules.CanApproveWorkflowStep(
+            isAdministrator: true,
+            hasWorkspaceAccess: false,
+            userRoles: [],
+            userId: Guid.NewGuid(),
+            targetType: ApprovalStepTargetTypes.Member,
+            targetValue: Guid.NewGuid().ToString());
+
+        Assert.True(actual);
+    }
+
+    [Fact]
+    public void CanApproveWorkflowStep_requires_role_target_match()
+    {
+        bool actual = ApprovalWorkflowRules.CanApproveWorkflowStep(
+            isAdministrator: false,
+            hasWorkspaceAccess: true,
+            userRoles: ["manager"],
+            userId: Guid.NewGuid(),
+            targetType: ApprovalStepTargetTypes.Role,
+            targetValue: "manager");
+
+        Assert.True(actual);
+    }
+
+    [Fact]
+    public void CanApproveWorkflowStep_rejects_later_step_actor_without_target_match()
+    {
+        bool actual = ApprovalWorkflowRules.CanApproveWorkflowStep(
+            isAdministrator: false,
+            hasWorkspaceAccess: true,
+            userRoles: ["provider"],
+            userId: Guid.NewGuid(),
+            targetType: ApprovalStepTargetTypes.Role,
+            targetValue: "client");
+
+        Assert.False(actual);
+    }
+
+    [Fact]
+    public void CanApproveWorkflowStep_requires_member_target_identity_match()
+    {
+        Guid assignedMemberId = Guid.NewGuid();
+        Guid secondAssignedMemberId = Guid.NewGuid();
+
+        bool matchingMember = ApprovalWorkflowRules.CanApproveWorkflowStep(
+            isAdministrator: false,
+            hasWorkspaceAccess: true,
+            userRoles: ["workspace-member"],
+            userId: assignedMemberId,
+            targetType: ApprovalStepTargetTypes.Member,
+            targetValue: $"{assignedMemberId},{secondAssignedMemberId}");
+
+        bool otherMember = ApprovalWorkflowRules.CanApproveWorkflowStep(
+            isAdministrator: false,
+            hasWorkspaceAccess: true,
+            userRoles: ["workspace-member"],
+            userId: Guid.NewGuid(),
+            targetType: ApprovalStepTargetTypes.Member,
+            targetValue: $"{assignedMemberId},{secondAssignedMemberId}");
+
+        Assert.True(matchingMember);
+        Assert.False(otherMember);
+    }
+
+    [Fact]
+    public void ParseMemberTargetIds_reads_distinct_comma_separated_member_ids()
+    {
+        Guid firstMemberId = Guid.NewGuid();
+        Guid secondMemberId = Guid.NewGuid();
+
+        IReadOnlyCollection<Guid> memberIds = ApprovalWorkflowRules.ParseMemberTargetIds(
+            $" {firstMemberId},not-a-guid,{secondMemberId},{firstMemberId} ");
+
+        Assert.Equal([firstMemberId, secondMemberId], memberIds);
+    }
+
+    [Fact]
+    public void FormatMemberTargetValue_stores_member_ids_stably()
+    {
+        Guid firstMemberId = Guid.Parse("aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa");
+        Guid secondMemberId = Guid.Parse("bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb");
+
+        string targetValue = ApprovalWorkflowRules.FormatMemberTargetValue(
+        [
+            secondMemberId,
+            firstMemberId,
+            secondMemberId,
+        ]);
+
+        Assert.Equal($"{firstMemberId},{secondMemberId}", targetValue);
+    }
+
+    [Fact]
+    public void CanApproveWorkflowStep_matches_membership_targets()
+    {
+        bool clientMatchesClient = ApprovalWorkflowRules.CanApproveWorkflowStep(
+            isAdministrator: false,
+            hasWorkspaceAccess: true,
+            userRoles: ["client"],
+            userId: Guid.NewGuid(),
+            targetType: ApprovalStepTargetTypes.Membership,
+            targetValue: ApprovalMembershipTargets.Client);
+
+        bool providerMatchesTeam = ApprovalWorkflowRules.CanApproveWorkflowStep(
+            isAdministrator: false,
+            hasWorkspaceAccess: true,
+            userRoles: ["provider"],
+            userId: Guid.NewGuid(),
+            targetType: ApprovalStepTargetTypes.Membership,
+            targetValue: ApprovalMembershipTargets.Team);
+
+        bool clientDoesNotMatchTeam = ApprovalWorkflowRules.CanApproveWorkflowStep(
+            isAdministrator: false,
+            hasWorkspaceAccess: true,
+            userRoles: ["client"],
+            userId: Guid.NewGuid(),
+            targetType: ApprovalStepTargetTypes.Membership,
+            targetValue: ApprovalMembershipTargets.Team);
+
+        Assert.True(clientMatchesClient);
+        Assert.True(providerMatchesTeam);
+        Assert.False(clientDoesNotMatchTeam);
+    }
+
+    [Theory]
+    [InlineData(ApprovalStepTargetTypes.Role)]
+    [InlineData(ApprovalStepTargetTypes.Membership)]
+    [InlineData(ApprovalStepTargetTypes.Member)]
+    public void IsValidTargetType_accepts_supported_target_types(string targetType)
+    {
+        bool valid = ApprovalStepConfigurationRules.IsValidTargetType(targetType);
+
+        Assert.True(valid);
+    }
+
+    [Theory]
+    [InlineData("")]
+    [InlineData("Group")]
+    [InlineData("role")]
+    public void IsValidTargetType_rejects_unsupported_target_types(string targetType)
+    {
+        bool valid = ApprovalStepConfigurationRules.IsValidTargetType(targetType);
+
+        Assert.False(valid);
+    }
+
+    [Theory]
+    [InlineData("administrator")]
+    [InlineData("manager")]
+    [InlineData("workspace-member")]
+    [InlineData("client")]
+    [InlineData("provider")]
+    public void IsValidRoleTarget_accepts_known_workspace_roles(string role)
+    {
+        bool valid = ApprovalStepConfigurationRules.IsValidRoleTarget(role);
+
+        Assert.True(valid);
+    }
+
+    [Theory]
+    [InlineData("")]
+    [InlineData("developer")]
+    [InlineData("owner")]
+    public void IsValidRoleTarget_rejects_non_workspace_approval_roles(string role)
+    {
+        bool valid = ApprovalStepConfigurationRules.IsValidRoleTarget(role);
+
+        Assert.False(valid);
+    }
+
+    [Theory]
+    [InlineData(ApprovalMembershipTargets.Team)]
+    [InlineData(ApprovalMembershipTargets.Client)]
+    public void IsValidMembershipTarget_accepts_supported_memberships(string membership)
+    {
+        bool valid = ApprovalStepConfigurationRules.IsValidMembershipTarget(membership);
+
+        Assert.True(valid);
+    }
+
+    [Theory]
+    [InlineData("")]
+    [InlineData("Provider")]
+    [InlineData("External")]
+    public void IsValidMembershipTarget_rejects_unsupported_memberships(string membership)
+    {
+        bool valid = ApprovalStepConfigurationRules.IsValidMembershipTarget(membership);
+
+        Assert.False(valid);
+    }
+
+    [Fact]
+    public void WorkspaceApprovalStepConfiguration_model_persists_workspace_ordering()
+    {
+        var options = new DbContextOptionsBuilder<AppDbContext>()
+            .UseNpgsql("Host=localhost;Database=socialize_model_test")
+            .Options;
+        using var dbContext = new AppDbContext(options);
+
+        var entity = dbContext.Model.FindEntityType(typeof(WorkspaceApprovalStepConfiguration));
+
+        Assert.NotNull(entity);
+        Assert.Equal("WorkspaceApprovalStepConfigurations", entity.GetTableName());
+        Assert.Equal(128, entity.FindProperty(nameof(WorkspaceApprovalStepConfiguration.Name))?.GetMaxLength());
+        Assert.Equal(32, entity.FindProperty(nameof(WorkspaceApprovalStepConfiguration.TargetType))?.GetMaxLength());
+        Assert.Equal(128, entity.FindProperty(nameof(WorkspaceApprovalStepConfiguration.TargetValue))?.GetMaxLength());
+        Assert.Contains(
+            entity.GetIndexes(),
+            index => index.IsUnique &&
+                     index.Properties.Select(property => property.Name).SequenceEqual(
+                     [
+                         nameof(WorkspaceApprovalStepConfiguration.WorkspaceId),
+                         nameof(WorkspaceApprovalStepConfiguration.SortOrder),
+                     ]));
+    }
+
+    [Fact]
+    public void ApprovalWorkflowInstance_model_allows_only_one_pending_workflow_per_content_item()
+    {
+        var options = new DbContextOptionsBuilder<AppDbContext>()
+            .UseNpgsql("Host=localhost;Database=socialize_model_test")
+            .Options;
+        using var dbContext = new AppDbContext(options);
+
+        var entity = dbContext.Model.FindEntityType(typeof(ApprovalWorkflowInstance));
+
+        Assert.NotNull(entity);
+        Assert.Equal("ApprovalWorkflowInstances", entity.GetTableName());
+        Assert.Equal(64, entity.FindProperty(nameof(ApprovalWorkflowInstance.State))?.GetMaxLength());
+        Assert.Equal(64, entity.FindProperty(nameof(ApprovalWorkflowInstance.ApprovalMode))?.GetMaxLength());
+        Assert.Contains(
+            entity.GetIndexes(),
+            index => index.IsUnique &&
+                     index.GetFilter() == "\"State\" = 'Pending'" &&
+                     index.Properties.Select(property => property.Name).SequenceEqual(
+                     [
+                         nameof(ApprovalWorkflowInstance.ContentItemId),
+                         nameof(ApprovalWorkflowInstance.State),
+                     ]));
+    }
+
+    [Fact]
+    public void ApprovalRequest_model_persists_runtime_step_metadata()
+    {
+        var options = new DbContextOptionsBuilder<AppDbContext>()
+            .UseNpgsql("Host=localhost;Database=socialize_model_test")
+            .Options;
+        using var dbContext = new AppDbContext(options);
+
+        var entity = dbContext.Model.FindEntityType(typeof(ApprovalRequest));
+
+        Assert.NotNull(entity);
+        Assert.Equal(32, entity.FindProperty(nameof(ApprovalRequest.WorkflowStepTargetType))?.GetMaxLength());
+        Assert.Equal(128, entity.FindProperty(nameof(ApprovalRequest.WorkflowStepTargetValue))?.GetMaxLength());
+        Assert.Contains(
+            entity.GetIndexes(),
+            index => index.Properties.Select(property => property.Name).SequenceEqual(
+            [
+                nameof(ApprovalRequest.WorkflowInstanceId),
+            ]));
+    }
+}