Governance Controls

CommunityPay's governance layer sits below the payment layer. All production financial flows pass through enforcement controls before execution. This is not optional behavior that users can disable — it is architectural.

EnforcementDecision: The Choke Point

All production financial flows in CommunityPay — journal entries, fund transfers, bill payments, invoice creation, payment receipts, and fiscal year closures — must produce an EnforcementDecision before they can proceed.

An EnforcementDecision records:

• The decision: ALLOW, BLOCK, OVERRIDE, or ERROR
• Which guards evaluated: What rules were expected to run, which actually ran, and what each concluded
• The timing: Elapsed milliseconds per guard, total evaluation time
• The context: Which HOA, which user, which flow, what amount

This creates a complete, immutable record of every financial decision and the reasoning behind it.

Two-Event Pattern

Each enforced transaction generates two events:

1. PRE_PERSIST (decision_seq=0): The enforcement evaluation happens before the database commit. If the decision is BLOCK, the transaction never touches the ledger.
2. POST_PERSIST (decision_seq=1): After a successful commit, a confirmation event is recorded with the resulting journal entry foreign key.

If a commit fails after an ALLOW decision, a PERSIST_ERROR (decision_seq=2) event captures the failure. This means you can audit not just what was allowed, but whether allowed transactions actually completed.

Enforced Flows

All six financial flows are enforced in production:

Full enforcement is active in production. There is no "permissive mode" toggle.

Approval Workflows

Financial operations above configurable thresholds require explicit human approval before execution.

How Workflows Match

Each workflow configuration defines:

• Document type: Bills, payments, fund transfers, journal entries, budget items, or payee changes
• Amount range: Minimum and maximum thresholds that trigger this workflow
• Priority: When multiple workflows match, the highest-priority workflow wins
• HOA scope: Workflows can be global or HOA-specific

Multi-Level Approval

Workflows support multiple approval levels with different requirements:

• Level 1: Might require any board member
• Level 2: Might require the treasurer specifically
• Level 3: Might require a board vote

Each level can specify:

• Approver type: Specific user, role-based (treasurer, president, board member, admin), or any board member
• Required approvals: How many approvers are needed at this level
• Auto-approve threshold: Skip this level if the amount is below a specified limit
• Sequential vs. parallel: Whether approvals must happen in order or can be concurrent

Status Lifecycle

Approval requests follow a strict state machine:

PENDING → IN_PROGRESS → APPROVED
PENDING → REJECTED
IN_PROGRESS → REJECTED
PENDING/IN_PROGRESS → CANCELLED

No backward transitions. A rejected request cannot be re-opened — a new request must be created.

Payee-Change Freeze

When sensitive bank account details change on an HOA payout destination, CommunityPay automatically freezes disbursements to that account until re-approved.

What Triggers a Freeze

Any modification to these fields on a non-personal (HOA) bank account:

• Provider account ID
• Account mask (last 4 digits)
• Bank name
• Payment provider
• Account type

When a change is detected:

1. The account's payout_status is set to frozen
2. The bank_details_version increments (audit trail)
3. The last_verified_at timestamp is cleared
4. All HOA admins receive an in-app notification identifying what changed

What Happens While Frozen

Any call to debit_invoice() or process_disbursement() targeting the frozen account returns a deterministic error:

"Payout destination recently changed and requires re-approval."

No payment will execute. No partial processing. The gate is binary.

Unfreezing

An admin must explicitly re-approve the bank account, which:

1. Sets payout_status back to active
2. Records last_verified_at with the current timestamp
3. Payments resume immediately

Risk-Differentiated Behavior

Personal (resident) bank account changes are logged but not frozen. The risk profile is different — a resident changing their own bank details is normal behavior. An HOA's payout destination changing is a potential fraud vector that warrants a freeze.

Integrity Gate

If the ledger has unresolved CRITICAL integrity findings, CommunityPay blocks all payments for that HOA.

How It Works

Before every payment operation, the system checks:

1. Does this HOA have any IntegrityFinding records with severity=CRITICAL and status in [OPEN, ACKNOWLEDGED]?
2. If yes: is there an active AuditOverride with scope=INTEGRITY_GATE that hasn't expired?

If findings exist and no override is active, the payment is blocked with error code INTEGRITY_GATE_BLOCK.

Override ("Break Glass")

For emergency situations, an authorized admin can create a time-limited override:

• Scope: INTEGRITY_GATE
• Maximum duration: 24 hours (system-enforced, cannot be extended)
• Audit trail: The override records who created it, why, and when it expires
• Automatic expiry: When the override expires, the gate re-engages automatically

The override exists because real HOAs occasionally need to process payroll or emergency vendor payments while a ledger issue is being resolved. But it's time-boxed and audited — it's a pressure valve, not a bypass.

Overrides are visible in audit logs and included in evidence packs. Every override usage is recorded with the resulting enforcement decision, creating full traceability.

Non-Blocking Severities

INFO and WARNING severity findings are visible in dashboards and reports but do not block payments. Only CRITICAL findings trigger the gate. This prevents operational disruption from minor bookkeeping issues while still catching genuine ledger integrity problems.

Policy Snapshots

Every governance evaluation references a frozen snapshot of the policy that was active at decision time.

PolicySnapshot captures the exact fund policy configuration (rules, thresholds, constraints) that was evaluated. Each snapshot includes a rules_hash and snapshot_hash for integrity verification.

GovernancePolicySnapshot captures the governance policy configuration (approval thresholds, workflow assignments, enforcement flags) active when a decision was made.

This prevents "policy ex post facto" arguments — no one can claim a different policy was in effect. The snapshot proves exactly which version of which policy governed each decision.

Both snapshot types include a verify_integrity() method that recomputes the hash and compares it against the stored value, detecting any tampering after creation.

EligibilityRule Evaluation

Before payments execute, declarative eligibility rules determine whether the transaction is permitted.

Rules are:

• Versioned: Multiple versions of the same rule can exist. Only ACTIVE versions are evaluated.
• Immutable once active: Once a rule moves from DRAFT to ACTIVE, its criteria cannot be modified. Changes require a new version.
• Categorized: Rules cover GOVERNANCE, FINANCIAL, COMPLIANCE, VOLUME, TENURE, and COMPOSITE categories.
• Deterministic: Each rule evaluates to ALLOW, DENY, or REFER (manual review required).

This means the eligibility evaluation for a payment made on January 15 can be reproduced exactly, using the same rule versions that were active on January 15.

Definitions

CARI Integration

Governance control effectiveness is one of five CARI score components, carrying a 25% weight in the composite score. The governance coefficient, board attestation status, and quorum compliance rates measured by the enforcement layer described here directly feed the CARI Governance sub-score. An HOA's enforcement decision history — including the ratio of ALLOW to BLOCK outcomes and the presence of current board attestations — determines whether the Governance component passes the minimum threshold for CARI eligibility.

For published methodology and component weights, see CARI Methodology and Scoring Framework.