Audience: Everyone
Outcomes: Shared mental model; events to watch; roles per phase
What is a contract?
Source of truth for a commercial engagement: scope, parties, terms, pricing, signers. Orders, milestones, invoices, and disputes trace back to a contract.
Lifecycle (canonical)
stateDiagram-v2 [*] --> draft draft --> pending_review: Send for review pending_review --> approved: Approve pending_review --> rejected: Reject approved --> pending_signature: Request signatures pending_signature --> active: All required signatures rejected --> draft: Revise & resend active --> amended: Amendment / addendum amended --> active
Roles per phase
Member: author drafts, incorporate feedback
Admin: approve, manage signers & policy, activate
Owner: policy override, dispute authority
Events (high-level)
contract.draft.created, contract.review.requested, contract.approved, contract.rejected, contract.signature.requested, contract.fully_signed, contract.amended.
Edge cases
Changing terms after approval ⇒ back to draft or re-review
Signature window expired ⇒ resend request; optional new deadline
QA checklist
Draft → Review → Approve → Request signatures → Active emits correct events
Attempt to sign without required roles/KYC ⇒
403with reason
Runbook: “Stuck in pending_signature”
Verify all signers assigned and reachable
Check expiration; resend if expired
Confirm KYC/approvals satisfied
Inspect event log for failed webhook/UI errors