DOC: FIN-001
ENGINE: B — FINANCIALS

Draw Request Flow (GC → Owner → QuickBooks)

01
Daily Log Sync
Work photos, completion %, crew count auto-tagged to project
→
02
Draw Compilation
System auto-compiles backup docs from logs. GC reviews.
→
03
Lien Waiver Check
System blocks submission if any sub waiver is OUTSTANDING
→
04
Owner Approval
Emailed PDF with digital sign. Timestamp logged to audit trail.
→
05
QuickBooks Sync
Approved draw auto-posts invoice to QBO via OAuth2 API
→
06
Payment Registered
QBO webhook fires. Draw status → PAID. Rating timer starts.

Invoice State Machine

DRAFT
→
SUBMITTED
→
UNDER REVIEW
→
APPROVED
→
LATE
Triggered at Net+5 days. Flags GC's Trust Commons payment score. Supplier routing deprioritized.

Lien Waiver Engine

Conditional Waiver

Issued before payment. Waives lien rights upon receipt of funds. The system blocks Draw submissions until all conditional waivers from prior draw period are collected.

Gate Logic

If lien_waiver_status = REQUIRED for any payee on project_id, draw submission is hard-blocked. Not soft-warned. Hard-blocked.

Unconditional Waiver

Issued after payment is confirmed. Final proof that the sub/supplier cannot file a lien for that draw period. Auto-generated by the platform when QBO confirms payment.

Auto-Generation Logic

On financial_draws.status → PAID webhook, system generates PDF waiver, requests e-signature via DocuSign API, archives to AWS S3 + project_id/waivers/

Payment → Trust Commons Feedback Loop

How Late Payment Destroys GC Score

Days Past DueSystem ActionTrust Impact
Net+1 to Net+5Status remains APPROVED. No action.None
Net+6 to Net+14Status → LATE. GC receives reminder push notification.-0.5 pending score
Net+15 to Net+30Sub/Supplier ecosystem flagged. Visible to their network.-1.2 score impact
Net+30+GC de-tiered. Supplier routing priority dropped. Lien right window alert sent to Sub.Tier Downgrade

QuickBooks Online Integration Spec

Auth: OAuth 2.0

GC authorizes Nail'd It to post invoices on their behalf. Token stored encrypted. Refresh tokens auto-rotated every 100 days.

Outbound: Invoice POST

On draw approval, system posts to POST /v3/company/{realmId}/invoice with line items mapped from project activity nodes.

Inbound: Payment Webhook

QBO fires Invoice.Payment webhook on payment. Nail'd It listener sets draw status PAID, triggers lien waiver generation, starts rating prompt timer.