Moderation & Approval Commits
Relevant source files
The following files were used as context for generating this wiki page:
- src/components/approvals/ApprovalPanel.tsx
- src/app/api/approval-commit/route.ts
- src/lib/events/approval-commit-schema.ts
- src/components/host/event-publish-approval-panel.tsx
- src/lib/events/resolve-approval-commit.ts
- src/components/host/host-event-copilot-bridge.tsx
- src/lib/supabase/database.types.ts
The Moderation & Approval Commits system provides a Human-In-The-Loop (HITL) framework for reviewing and finalizing AI-generated actions. Its primary purpose is to gate sensitive operations—such as publishing events or altering database records—behind a manual review process where a user or moderator must approve, edit, or reject the proposed changes before they are committed to the system of record.
This module bridges the gap between AI agent suggestions (generated via Mastra and CopilotKit) and the final Supabase data layer. It ensures that data integrity and quality standards are maintained by requiring explicit user intent for significant state transitions. Sources: README.md:1-10, src/components/approvals/ApprovalPanel.tsx:21-25
System Architecture
The system follows a multi-tier architecture involving frontend UI components, a Next.js API route for validation, and Supabase Edge Functions for the final database commit.
The diagram shows the data flow from user interaction to final database commitment.
Sources: src/app/api/approval-commit/route.ts:10-50, src/components/host/event-publish-approval-panel.tsx:45-75
Key Components
Approval Panels
The system utilizes two primary UI components for handling decisions:
- Generic ApprovalPanel: A shell providing standard "Approve", "Edit", and "Reject" buttons for any HITL task.
- EventPublishApprovalPanel: A specialized component for the "Roberto" host event flow that renders an event preview card alongside the decision actions.
Sources: src/components/approvals/ApprovalPanel.tsx:21-50, src/components/host/event-publish-approval-panel.tsx:32-40
Decision Logic
Decisions are categorized into three distinct states defined in the ApprovalDecisionSchema:
| Decision | System Action |
|---|---|
approved | Triggers the final commit logic (e.g., publishing the event to the public). |
edit | Reverts the state to a draft, allowing the user or AI to make further changes. |
rejected | Cancels the operation and marks the request as rejected. |
Sources: src/lib/events/approval-commit-schema.ts:4, src/components/host/host-event-copilot-bridge.tsx:112-120
Data Structures & Validation
All commit requests must adhere to the ApprovalCommitInputSchema. This ensures that the frontend provides the necessary draft state and request identifiers.
export const ApprovalCommitInputSchema = z.object({
decision: ApprovalDecisionSchema,
draft: EventDraftStateSchema,
approvalRequestId: z.string().uuid().optional(),
reason: z.string().max(500).optional(),
});
Sources: src/lib/events/approval-commit-schema.ts:6-11
Database Schema
The backend persists these interactions in two main tables within Supabase:
| Table | Purpose |
|---|---|
approval_requests | Tracks the initial request, action type, risk level, and payload. |
approval_decisions | Records the final outcome, who decided it, and the reasoning. |
Sources: src/lib/supabase/database.types.ts:public.Tables.approval_requests, src/lib/supabase/database.types.ts:public.Tables.approval_decisions
Decision Processing Flow
When a user interacts with an approval panel, the following sequence occurs:
- Frontend fetch: The UI sends the decision and the current draft to
/api/approval-commit. - Auth Check: The API route verifies the user's session and retrieves an access token.
- Edge Function Proxy: The request is forwarded to a Supabase Edge Function (
/approval-commit). - Resolution: The
resolveApprovalCommitutility processes the server response to determine the next UI state.
This sequence details the synchronous flow of an approval commit from the client to the backend.
Sources: src/app/api/approval-commit/route.ts:35-60, src/lib/events/resolve-approval-commit.ts:1-10
Specialized Flow: Event Publishing (Roberto Agent)
In the event host wizard, the moderation system is used for the preview_and_publish action. This flow specifically requires that an approved decision returns both an eventId and a slug. If these are missing despite a success flag, the system treats it as an error to prevent silent failures in publication.
Resolution Outcomes:
- published: Validated approval with event references.
- decided: Standard resolution for
editorrejected. - error: Validation failures or server-side issues.
Sources: src/lib/events/resolve-approval-commit.ts:15-40, src/components/host/host-event-copilot-bridge.tsx:100-110
Summary
The Moderation & Approval Commits module is a critical safety and quality control layer. It formalizes the interaction between AI suggestions and database updates by providing structured UI components, strict Zod-based validation, and a secure pathway through authenticated API routes and Edge Functions. This ensures that every high-impact change is tracked, validated, and explicitly authorized by a human user.