Skip to main content

Approval Workflow Design

Version: 2.0 Status: Draft

1. Overview​

This document outlines the design for the multi-step approval workflow within ChainAlign. The primary goal is to provide a flexible, auditable, and secure process for teams to approve scenarios and commit to a plan. The system supports sequential and parallel approvals, and allows for automated guardrails to interrupt non-compliant or high-risk decisions.

2. State Machine​

The workflow is governed by a strict state machine to ensure process integrity.

States​

  • DRAFT: The initial state of any new scenario. It is being actively edited.
  • PENDING_REVIEW: The scenario has been submitted for review.
  • NEEDS_REVISION: A reviewer has requested changes.
  • APPROVED: The scenario has been approved by all required reviewers in a given step.
  • REJECTED: The scenario has been definitively rejected. A terminal state.
  • COMMITTED: The approved scenario has been locked in as the official plan of record. A terminal state.

3. Approval Routing & Sequencing​

Approval flows are defined by configurable routes that specify the roles, sequence, and requirements for approval.

  • Sequence (order): Approvals are grouped by an order number. All required approvals at a lower order (e.g., 1) must be completed before the workflow can proceed to the next order (e.g., 2).
  • Parallelism: All approvers at the same order can approve in parallel.
  • Requirement (required): If a required approver rejects a scenario, the entire scenario is rejected.

4. Guardrail Interruption Mechanism​

Guardrails are automated checks that run at key state transitions (e.g., on an approval attempt) to enforce business and regulatory rules.

  • Trigger: Automatically runs when a user attempts to approve a scenario.
  • Logic: Executes a series of validation functions based on the scenario's type and data.
  • Severity: Violations can be blocking (prevents the state change), warning (allows the change but logs a warning), or info.
  • Audit: All triggered guardrail checks, especially blocking violations, are logged to the guardrail_checks table for full auditability.
  • Override: A blocking violation can be overridden by a user with a specific override_guardrail permission. The override action, reason, and approver are fully audited.

5. Database Schema​

scenarios table​

  • An status column will be added: ALTER TABLE scenarios ADD COLUMN status VARCHAR(50) DEFAULT 'DRAFT';

approval_requirements (New Table)​

To track the status of each individual approval needed for a scenario.

CREATE TABLE approval_requirements (
    id SERIAL PRIMARY KEY,
    scenario_id INTEGER REFERENCES scenarios(id),
    role VARCHAR(100),
    approval_order INTEGER, -- 1, 2, 3 for sequential; same number for parallel
    required BOOLEAN DEFAULT true,
    approval_status VARCHAR(50) DEFAULT 'pending', -- 'pending', 'approved', 'rejected'
    approved_by_user_id INTEGER REFERENCES users(id),
    approved_at TIMESTAMPTZ,
    comment TEXT
);

guardrail_checks (New Table)​

To log every time a guardrail is triggered, providing a full audit trail of compliance checks.

CREATE TABLE guardrail_checks (
    id SERIAL PRIMARY KEY,
    scenario_id INTEGER REFERENCES scenarios(id),
    check_type VARCHAR(100), -- 'regulatory_compliance', 'budget_constraint'
    rule_violated VARCHAR(255),
    severity VARCHAR(50), -- 'blocking', 'warning', 'info'
    violation_details JSONB, -- Store calculated risks, thresholds, etc.
    triggered_by_user_id INTEGER REFERENCES users(id),
    triggered_at TIMESTAMPTZ DEFAULT NOW(),
    resolution_action VARCHAR(100), -- 'blocked', 'override_approved', 'scenario_modified'
    resolution_by_user_id INTEGER REFERENCES users(id),
    resolution_at TIMESTAMPTZ
);

scenario_approvals table (Enhancement)​

To support the override capability.

-- Add to existing scenario_approvals table
ALTER TABLE scenario_approvals ADD COLUMN override_reason TEXT;
ALTER TABLE scenario_approvals ADD COLUMN override_approved_by INTEGER REFERENCES users(id);

6. API Endpoints​

  • POST /api/scenarios/{id}/submit: Change state from DRAFT to PENDING_REVIEW.
  • POST /api/scenarios/{id}/approve: Attempts to approve a scenario for the current user's role. Triggers Guardrail validation.
  • POST /api/scenarios/{id}/reject: Rejects a scenario for the current user's role.
  • POST /api/scenarios/{id}/request-changes: Change state to NEEDS_REVISION.
  • POST /api/scenarios/{id}/commit: Change state from APPROVED to COMMITTED.
  • POST /api/scenarios/{id}/override-guardrail: Allows a privileged user to override a blocking guardrail violation, with an audited reason.

7. Notification System​

  • A notification service will be designed to inform users of required actions (e.g., when it's their turn to approve) or state changes (e.g., when a scenario they own is rejected).