Support inspector signatures on agreements
Objective
- Support inspector signatures on inspection agreements for markets (e.g. Washington, Oregon) where both the client and the inspector must sign before the inspection proceeds.
- Eliminate manual workarounds while preserving the correct inspector identity on the signed agreement record.
- Keep the existing client signing flow intact; add a complementary inspector signing capability.
Background
- During an implementation call, the team discussed Washington law requiring both client and inspector signatures on the inspection agreement; Oregon was mentioned as a similar market.
- The open product question is how and when the inspector signature should be applied. Ideas discussed included:
- Storing an inspector signature on the inspector profile
- Stamping the agreement when the report is published or when the job starts
- Allowing the assigned inspector to sign directly on the job before the inspection begins
- Edge cases called out for clear handling:
- Inspector reassignment before the inspection
- Multiple inspectors on a job
- Someone other than the inspector publishing the report
- Signature timing must still satisfy pre-inspection compliance requirements
- Current behavior (code audit): Attik agreements today support client/contact signing only. The client portal flow in
AgreementSigningSection.tsx/AgreementSigningForm.tsxcollects one signature and submits viaagreements.tsPATCH withstatus: 'signed'. Signing requires a portal-access token withcontactIdand a contact role grantingagreementpermission. TheagreementSchemastores a single signer (signedBy,signedByEmail,signatureData,signedRenderedHtml, etc.) — no inspector signature fields. Agreement templates support text and initials blocks (AgreementBuilderBase.tsx,initialsBlockin merged content); there is no inspector signature block type. Report unlock treats agreements as signed when the client has signed all active non-stale agreements (computeAgreementSignedForReportLock.ts,agreementLockSync.ts,checkReportAccess.ts). Inspector signatures on Spectora reports (InspectorSignatureSection.tsx) are a separate path from report/Spectora data and do not satisfy agreement signing requirements. The AttikinspectorSchemahas no stored signature field for agreements today.
Decisions needed (product)
Lock before or during implementation:
- When inspector signature is captured — profile stamp vs job-level sign before inspection vs tied to report publish/job start (only options that meet pre-inspection compliance are valid for WA/OR).
- Where the inspector signs — Tools inspection/workorder UI, mobile app, or automated stamp from profile.
- Which inspector when multiple are assigned — primary only, all assigned, or configurable per company.
- Reassignment behavior — invalidate/require re-sign, or keep original inspector signature.
- Report lock — whether inspector signature is required for
agreement.signed/ report access, or tracked separately from client sign. - Company/market enablement — global feature vs per-company or per-state setting.
Scope
Backend
- Extend agreement signing data model beyond single client signature — e.g. inspector identity, timestamp, signature image/data, and rendered output — in or alongside
agreementSchema.ts. - New or extended routes in
agreements.ts(or inspector-specific signing endpoint) with auth appropriate for inspector/staff (not client portalcontactIdflow). - Agreement merge/render pipeline (
mergeAgreementBlocksToContent.js,renderAgreementDocToHtml.ts,signedRenderedHtmlcapture) must include inspector signature in the immutable signed record when applicable. - Decision needed: whether inspector signature invalidates or triggers stale agreement logic (
agreementStaleWorker.ts,signedContentHash/computeSignedContentHash). - Decision needed: updates to
agreementLockSync.ts/checkReportAccess.tsif inspector sign is required for compliance before reports unlock. - Inspector profile storage (if profile-based approach chosen) would touch
inspectorSchema.tsand inspector settings routes — not present today.
Frontend — Client portal
- Agreement view/sign pages under
src/app/client/job/[slug]/agreement/[id]/— today client-only. May need read-only display of inspector signature once applied, or dual-signer UX if inspector signs via portal (unlikely; decision needed). AgreementContent.tsx/ template builder may need a new block type or merge-field for inspector signature placement in PDF/HTML output.
Frontend — Tools
- Inspector signing entry point on inspection/workorder (
src/app/tools/inspections/[id]/) or agreements UI — not built today. - Agreement template builder (
src/app/tools/agreements/templates/[id]/,AgreementGlobalBlockModal.tsx) — extend block types beyondtextandinitialsif inspector signature appears in template body. - Settings if profile-stored signature: inspector settings under
src/app/tools/settings/inspectors/.
Mobile
- Decision needed: whether inspectors must sign from attik-mobile in v1 or Tools web only.
Explicitly out of scope unless product expands
- Using report publish inspector signatures (
InspectorSignatureSection.tsx) as a substitute for agreement compliance without explicit product approval - Replacing client signing flow or contact-role
agreementpermission model
Acceptance themes (from edge cases)
- Correct inspector identity on the final agreement artifact after reassignment scenarios are resolved per product decision.
- Multi-inspector jobs handled consistently (not silently wrong signer).
- Pre-inspection timing: agreement with inspector signature satisfies compliance before inspection start, independent of who publishes the report.
References
- Client agreement signing:
attik-frontend/src/app/client/job/[slug]/agreement/[id]/components/AgreementSigningSection.tsx,AgreementSigningForm.tsx - Agreement API & sign gate:
attik-backend/src/routes/agreements.ts - Agreement model:
attik-backend/src/models/agreementSchema.ts - Template blocks:
attik-frontend/src/app/tools/agreements/templates/[id]/AgreementBuilderBase.tsx - Report lock / agreement signed:
attik-backend/src/util/functions/agreements/agreementLockSync.ts,attik-frontend/src/util/functions/report/computeAgreementSignedForReportLock.ts - Report inspector signature (separate system):
attik-frontend/src/app/client/reports/components/InspectorSignatureSection.tsx
Status: Planned
Log in to comment and vote
No comments yet
Be the first to share your thoughts.