Contract Approval

AI contract review plus a role-enforced approval workflow for Twenty Opportunities.

A salesperson creates a Contract linked to an Opportunity, attaches the contract PDF, and submits it for review. An AI review reads the PDF and flags risky or inconsistent clauses — notably a customer-vs-supplier payment-terms mismatch (e.g. the customer pays monthly while the supplier must be paid in a single upfront installment). Managers/partners (Gerente/Sócio) then approve or reject, and only that role can approve.

What it installs

• Contract (custom object, related to Opportunity): payment terms (customer/supplier), lifecycle status, AI review summary, structured AI findings, aiPaymentMismatch, approver, submitter, and timestamps. The contract PDF attaches to the Contract via the native Attachment relation.
• Renewal tracking on Contract: dataInicio / dataTermino (vigência) and estagioRenovacao (ATIVO → RENOVACAO_INICIADA → RENOVADO / ENCERRADO, default ATIVO). See Renewal tracking.
• Approval Decision (custom object, child of Contract): the append-only audit of who decided what, when, and why (decidedBy, decision, comment, decidedAt).
• Gerente/Sócio role: assignable to users; the record-decision function checks this role before accepting an approval. A declarative field-permission on Contract.status is shipped as defense-in-depth.
• Logic functions: ai-review, submit-for-review, and record-decision (all route-auth'd), plus a no-op post-install.
• Front-component actions on a Contract: Submit for review, Approve, Reject.
• Pending approvals view: contracts with status = pending_manager_approval — the manager's work queue.

How it works

1. Submit for review sets status = pending_ai_review, records the submitter, then runs the AI review directly (no workflow required).
2. AI review fetches the Contract's most-recent PDF attachment (signed URL), sends it to the Anthropic Messages API as a document block with a broad clause-review prompt, writes back aiReviewSummary / aiFindings / aiPaymentMismatch, and advances status = pending_manager_approval. Supplier payment terms absent from the contract fall back to the standard — see Supplier payment default.
3. Approve / Reject calls the route-auth'd record-decision function, which resolves the invoking user and verifies they hold the Gerente/Sócio role before writing an Approval Decision (decidedBy = the actor) and updating the contract. A non-manager attempt is refused with a clear message and nothing is written.

Setup

1. Install the app.
2. In Settings → Apps, set ANTHROPIC_API_KEY (required for AI review). Optionally set LLM_MODEL (defaults to a multimodal Claude model). Without the key, the AI step degrades gracefully: it writes a "not configured" summary and the contract awaits manual manager review.
3. Assign the Gerente/Sócio role to the members who may approve.

Supplier payment default

When a contract does not state how the supplier is paid, the review applies the Excelium standard: a single payment (à vista) 30 days after signature (src/constants/payment-terms.ts).

The format matters as much as the term. Paying the supplier in one shot is exactly what creates cash-flow exposure when we bill the customer in installments — money goes out at once while it comes in over months. That comparison is the point of the whole check.

The default is applied in two places, deliberately split:

• In the prompt — the model is told the standard so it can still return a match/mismatch verdict instead of unknown, plus an explicit rule: customer paying in installments/recurring + supplier paid in a single installment ⇒ mismatch, with a vermelho finding flagged for manual review. It is also told not to invent a clause — when the contract is silent it must return supplierPaymentTerms: null.
• In code — paymentTermsSupplier is then filled from that null with the default. Manual input is never overwritten, and an extracted clause always wins over the default.

The stored value carries its own label — Parcela única (à vista) em 30 dias após a assinatura do contrato (padrão — não explícito no contrato) — and the AI-review Note states the same. This is the point of the design: a presumption must never be readable as a contractual term. To change the standard, edit DEFAULT_SUPPLIER_PAYMENT_TERMS_DAYS / DEFAULT_SUPPLIER_PAYMENT_TERMS_SHORT; the prompt, the stored value and the Note all derive from them.

Mismatch backstop

The prompt is what actually reads the contract, so it is the primary mechanism. On top of it, ai-review-contract runs a narrow guard (paysInInstallments, a pt-br text heuristic): when the review returns unknown, the supplier side is the applied default (so it is known to be a single payment), and the customer terms read as installments/recurring, the verdict is escalated to MISMATCH.

It only ever escalates a non-verdict — an explicit MATCH or MISMATCH from the review is never overridden — and it stands down when supplier terms were filled by hand, since those may themselves be an installment plan. A false positive here costs one extra manager glance; a false negative costs cash.

Renewal tracking

dataInicio, dataTermino and estagioRenovacao support renewal follow-up: dataTermino is the current term's expiry and is what any renewal alert should key off; estagioRenovacao is where the contract sits in the renewal cycle. Both are nullable — a contract with no dataTermino is invisible to every renewal report, so backfilling existing contracts is a prerequisite, not an optimisation.

These three fields were first created directly in the production workspace (via the metadata API, under the workspace's own application) and only afterwards declared here. Their universalIdentifiers in src/constants/universal-identifiers.ts are therefore pinned to the live UUIDs rather than freshly generated — scripts/generate-universal-identifiers.mjs must not be allowed to overwrite them.

Consequence for the first deploy that ships these declarations: the live fields belong to a different applicationId than the Contract object, so they are outside this app's metadata diff. The deploy will try to create them rather than adopt them, and creation collides with the existing fields on the (object, name) uniqueness constraint. Before that deploy, either confirm the migration adopts fields by universalIdentifier, or delete the three workspace-owned fields first and let the app recreate them. Deleting them also invalidates any dashboard widget that references their field-metadata IDs — those widgets must be repointed afterwards.

Graceful degradation

• No LLM key → AI review writes a "not configured" summary and leaves the status for manual review.
• No downloadable PDF → the AI review falls back to the structured payment-terms fields.

Development

yarn install
yarn twenty dev:build
yarn typecheck
yarn lint
yarn test        # unit tests (offline, fixtures/mocks)

Regenerate all universal identifiers:

node scripts/generate-universal-identifiers.mjs

Notes / out of scope

• Live-instance validation (real PDF → LLM round trip, front-component→route end-user auth, install-time workflow seeding) is deferred; unit tests use mocks.
• Email notifications require a connected account and are not install-seedable; the pending-approvals view is the notification surface.