The Design Registry

Proposals, Work Orders, Invoicing & Payments

Document: 06 - Proposals, Work Orders, Invoicing & Payments
Version: 2.0
Prepared: August 2026
Status: Engineering and product source of truth
Primary principle: Commercial records originate in Projects, preserve exact scope and move through explicit decisions.

1. Executive Summary

This specification defines the shared commercial operating system used by Designer Studios, Clients, Providers and authorized Design Registry operators. It connects Project requirements to external quotes, Client proposals, Provider awards, Work Orders, evidence, invoices, payments and accounting reconciliation.

The system must support two equally important commercial journeys:

1. A Designer Studio creates a branded Project Proposal for a Client, receives acceptance, establishes the Client engagement and invoices according to agreed deposits, milestones, recurring services or completion.
2. A Designer or Registry operator sends a Project Work Package to one or more Providers, receives a fixed response or Proposal, awards the work, issues a Work Order, monitors delivery of the work and processes the Provider invoice.

Both journeys use the same templates, versioning, line items, calculations, document rendering, acceptance, audit, invoice and payment primitives. They differ through record relationship, audience, Provider category, Project phase and visibility—not copied applications.

Projects remain the operational centre. A storage quote is generated from selected Project items, receiving requirements and expected timing. A white-glove quote includes the item manifest, pickup, delivery, access and installation-day requirements. A millwork Proposal references rooms, drawings, materials, measurements and approval milestones. A Designer’s Client Proposal references the design scope, Project phases, services, fees, allowances, assumptions and payment schedule.

Every submitted or accepted commercial document is immutable. Later Project edits never silently change what another party reviewed or accepted. Material changes flow through a new Proposal version, addendum or Change Order. Acceptance, internal approval, award, conversion, invoice approval and payment are separate actions with separate authority and audit records.

Global navigation gives each Workspace a table of its permitted Proposals, Work Orders, Invoices and Payments. The same records also appear inside the relevant Project. Providers see only Offers they received, Proposals they authored, Work Orders awarded to them and invoices/payments belonging to their Workspace.

Project requirement → Work Package → Offer or Proposal → acceptance and award → Commitment and Work Order → evidence → Invoice → Payment and reconciliation.

2. Objectives and Non-Goals

2.1 Objectives

• Create commercial documents directly from Project scope, items, budgets and schedules.
• Support branded Designer-to-Client Proposals.
• Support category-specific Provider Offers, Proposals and Work Orders.
• Preserve immutable versions and acceptance evidence.
• Keep internal approval, recipient acceptance, award and conversion distinct.
• Give Providers enough operational context to quote and perform work inside the platform.
• Support deposits, milestones, partial, recurring, final and credit invoices.
• Support Stripe payments and recorded manual/bank payments.
• Integrate QuickBooks without making it the Project source of truth.
• Register every communication in the Notifications Builder.
• Expose global tables and Project-scoped tabs using shared components.

2.2 Non-goals

• Legal or tax advice
• Final accounting chart-of-accounts design
• Final permissions-builder interface
• Payroll
• General-purpose inventory accounting
• Full procurement/item specification
• Guarantee that every country’s payment or tax rules are supported at launch

2.3 Current product correction contract

The global Proposals navigation item is currently a disabled, non-routable placeholder without an availability label. No Proposal directory, Proposal Profile, version history, creation flow or commercial state is available at the reviewed route. Until the shared commercial records in this specification are implemented:

• label every disabled entry point Coming soon;
• keep it non-interactive and remove any implication that a blank or broken page exists;
• do not count the placeholder or disabled record tab as a functioning Proposal module;
• enable navigation only when the directory opens permission-scoped Client and Provider Proposals and each row resolves to a canonical Proposal Profile;
• preserve distinct Proposal, acceptance, award, Commitment, Work Order, Invoice and Payment records rather than collapsing them into one status.

The initial directory must clearly distinguish Client Proposals from Provider Proposals and restrict Provider Workspaces to Proposals they authored or received through authorized Project scope.

3. Product Principles

3.1 Project generated

Rooms, items, materials, phases, schedules, files, site conditions and budgets already exist in the Project. Commercial documents select and snapshot those records rather than retyping them.

3.2 Build once, configure by relationship

One document engine supports Client Proposals, Provider Proposals, Work Orders, purchase orders, Change Orders, invoices and credits. Templates and category modules control the content.

3.3 Versioned and immutable

Drafts can change. Sent, submitted, accepted, issued and paid records preserve exact structured data and rendered output.

3.4 Explicit decisions

• Internal approval authorizes sending or awarding.
• Recipient acceptance agrees to one exact version.
• Award selects a commercial response.
• Conversion creates the governing Commitment and Work Order.
• Invoice approval confirms eligibility for payment.
• Payment settlement confirms movement of funds.

3.5 Audience-safe

Commercial data is filtered server-side. Providers never see competing quotes, internal margins, other Provider identities, Client-private records or unrelated Project scope.

3.6 Honest financial state

The application never labels funds paid because a checkout page returned success. Payment state comes from an authoritative payment event or approved manual reconciliation.

3.7 No silent scope drift

The system continually compares active Project scope with commercial snapshots and requires governed resolution for material differences.

4. Actors and Commercial Relationships

4.1 Actors

• Client
• Designer Studio
• Provider Workspace
• Design Registry operating Workspace
• Authorized internal reviewer
• External accounting/payment service

4.2 Relationship types

4.3 Payer and payee configuration

Payer, payee, issuer and operational owner are explicit fields; they must not be inferred solely from Workspace type. The commercial model can support:

• Client pays Designer Studio.
• Client pays The Design Registry for an authorized service.
• Designer Studio pays Provider.
• The Design Registry pays Provider.
• A manual/off-platform payment is recorded and reconciled.

Marketplace fees, commissions or service charges are configurable commercial components and are visible only to authorized parties. They are not hardcoded into the core Proposal engine.

5. Core Records

5.1 Work Package

A versioned Project-generated scope prepared for one commercial request. It contains selected Project context, rooms, items, services, dates, files, response requirements, evidence expectations and visibility rules.

5.2 Offer / Request for Proposal

A structured invitation sent to one Provider recipient. Modes:

• Fixed Offer: accept or decline the offered price/scope
• Proposal requested: Provider prepares and submits a Proposal
• Availability/qualification request: Provider confirms fit before a detailed request

5.3 Proposal

A versioned commercial document containing parties, scope, line items, price, tax, schedule, payment schedule, assumptions, exclusions, validity, terms, branding and acceptance requirements.

5.4 Commercial Commitment

The authoritative awarded/accepted agreement record and lineage anchor. Subtypes:

• client_engagement
• provider_work_order
• purchase_order
• registry_service_order

5.5 Work Order

The Provider-facing operational commitment containing awarded scope, Project access, tasks, milestones, items, schedule, evidence recipe, change process and invoicing rules.

5.6 Purchase Order

A product-focused commercial commitment containing vendor, ship-to, bill-to, item lines, quantities, pricing, freight, tax, deposits, acknowledgement, expected dates and terms. It may use Work Order infrastructure but has a product-specific presentation.

5.7 Change Order

An append-only governed change to scope, amount, schedule, items, assumptions or terms after Commitment creation.

5.8 Invoice

A payment request against eligible Commitment scope, milestones, products, time, expenses, storage periods or accepted changes.

5.9 Payment Request

A payer-facing request containing eligible balance, permitted rails, due date, instructions and status.

5.10 Payment and Allocation

A recorded movement of funds and its allocation across invoices or credit balances. Payment records are append-oriented and preserve processor/manual reconciliation evidence.

6. Project Integration

6.1 Entry points

Commercial creation can begin from:

• Project Commercial tab
• Project Providers/Participants
• Project Items bulk selection
• Construction material list
• Decorating shopping list
• Procurement order view
• Storage/receiving requirements
• Calendar or installation planning
• Project Work Package quick action
• Global Proposals table for a selected Project

6.2 Seven-Phase alignment

6.3 Project Commercial tab

Sections:

• Summary and financial exposure
• Offers
• Proposals
• Commitments
• Work Orders and Purchase Orders
• Change Orders
• Invoices
• Payments and credits
• Activity and audit

The tab uses the same canonical records as global navigation, filtered to the Project.

6.4 Phase gates

Project templates may require commercial conditions before phase transition, such as accepted design Proposal, Client deposit paid, critical Work Orders acknowledged or approved procurement budget. The Project workflow references canonical commercial state; it does not duplicate it.

6.5 Project budget integration

Proposal and Work Order line items map to Project budget categories. The budget distinguishes:

• Planned
• Proposed
• Approved/committed
• Ordered
• Invoiced
• Paid
• Forecast final

Every aggregate drills into contributing records. Commercial actions that increase budget exposure show variance before confirmation.

7. Work Package Builder

7.1 Creation workflow

1. Choose Project and commercial purpose.
2. Choose Client or Provider relationship.
3. Choose Provider category when applicable.
4. Select rooms, phases, services, items/materials and files.
5. Set dates, milestones and dependencies.
6. Select response type and pricing format.
7. Select evidence recipe.
8. Review audience visibility.
9. Preview recipient experience.
10. Save draft or create Offer/RFP.

7.2 Shared content

• Project/site identity appropriate to recipient
• Scope narrative
• Service category
• Rooms/areas
• Item/material manifest
• Quantities and handling details
• Required deliverables
• Drawings/files
• Schedule and deadlines
• Site/access constraints
• Pricing response format
• Allowances/alternates
• Evidence requirements
• Questions and clarification period
• Response deadline

7.3 Item manifest

Subject to visibility, manifest columns include:

• Project item ID
• Product/material description
• Image
• Room/category
• Quantity
• Dimensions and weight
• Vendor/SKU/model
• Purchase order or tracking reference
• Expected date
• Condition and custody state
• Storage location
• Handling, assembly and installation notes

7.4 Category presets

The Work Package Builder loads a category preset while retaining shared components. Presets control required sections, manifest columns, response questions, files and evidence recipes.

7.5 Versioning

Sending freezes a Work Package version. A later edit creates a new draft version. Offers and Proposals always reference the exact version used.

8. Scope Snapshot and Difference Engine

8.1 Purpose

Project records continue to change. Commercial snapshots must not. The difference engine compares current Project values with the governing snapshot.

8.2 Difference classes

• Informational: no commercial consequence
• Non-material: acknowledged without reissue
• Material pre-award: requires addendum, replacement or reissue
• Material post-award: requires Change Order
• Removed/cancelled: requires explicit disposition

8.3 Difference record

source_record_type
source_record_id
field_key
snapshot_value
current_value
classification
detected_at
resolved_by
resolution_type
resolution_record_id

8.4 Examples

• Item quantity changes after a Vendor quote.
• Delivery address changes after a white-glove award.
• Installation date moves outside the accepted schedule.
• Millwork drawing revision changes dimensions.
• A Client removes a room after accepting a Designer Proposal.

Material differences appear as Project and Work Order attention items.

9. Offers and RFPs

9.1 Offer modes

Fixed Offer

Issuer supplies scope and commercial terms. Provider may accept, decline or request clarification/change if enabled.

Proposal requested

Provider receives the Work Package and prepares a category-specific Proposal.

Availability request

Provider confirms timing, service area, capability and interest before detailed scope is released.

9.2 Canonical states

draft
→ internal_review
→ ready_to_send
→ sent
→ delivered
→ viewed
→ clarification
→ accepted / declined / expired / withdrawn
→ awarded
→ converted

Delivery and viewed are communication signals, not agreement.

9.3 Provider actions

• Accept
• Decline with structured reason
• Request clarification
• Request permitted deadline extension
• Propose changes
• Start Proposal

9.4 Confidential sourcing

Each Provider receives an independent Offer record. Providers cannot see recipient count, competitors, responses, rankings, internal comparisons or award rationale.

9.5 Offer access

Pre-award access exposes only the Work Package snapshot, files and clarification channel. It does not create full Project access.

10. Proposal Builder and Templates

10.1 Proposal types

• Designer-to-Client Project Proposal
• Provider response Proposal
• Registry service Proposal
• Revised Proposal
• Budgetary/indicative Proposal

10.2 Builder sections

1. Cover and parties
2. Project summary
3. Scope and deliverables
4. Phases, schedule and milestones
5. Line items and fees
6. Allowances and alternates
7. Payment schedule
8. Assumptions and exclusions
9. Terms and validity
10. Acceptance/signature
11. Attachments
12. Preview and send

10.3 Template Builder in Settings

Settings
└── Commercial Templates
    ├── Proposal Templates
    ├── Work Order Templates
    ├── Purchase Order Templates
    ├── Change Order Templates
    ├── Invoice Templates
    ├── Clause Library
    ├── Calculation Rules
    ├── Numbering
    └── Branding

Templates are selected by Workspace, relationship, Provider category, market and currency. Published template versions are immutable.

10.4 Template controls

• Section order and visibility
• Required/optional sections
• Approved variables
• Line-item columns
• Calculation rules
• Clause blocks
• Signature/acceptance blocks
• Workspace branding
• Client-facing Registry attribution
• Web and PDF layout
• Locale/currency/tax display

10.5 Designer branding

Designer Studios can use their logo, business name, accent, approved typography treatment, cover imagery, footer and sender identity while maintaining accessibility and document provenance. Branding cannot hide the legal contracting party.

10.6 Variables

Variables are schema-controlled, such as:

project.name
project.address.client_safe
client.display_name
designer.workspace_name
provider.workspace_name
proposal.valid_until
proposal.subtotal
proposal.tax_total
proposal.total

Missing required variables block sending. Variables never execute arbitrary code.

10.7 Template testing

Test mode uses synthetic data and renders:

• Missing/optional data
• Long names and descriptions
• Many line items
• Multiple tax rates
• Discounts/allowances
• Mobile web view
• PDF output

Test mode never consumes document numbers, creates events or sends messages.

11. Proposal State Machine and Decisions

11.1 Canonical states

draft
→ internal_review
→ revision_required
→ ready_to_send
→ sent
→ delivered
→ viewed
→ questions_open
→ revision_requested
→ revised
→ accepted / declined / expired / withdrawn
→ awarded
→ converted

11.2 Versioning

• Editing a draft updates the draft version.
• Sending freezes that version.
• A change after sending creates a new version.
• Acceptance references exact version, hash, rendered artifact and acceptance record.
• Superseded versions remain visible in history.

11.3 Internal approval

Internal approval can be required by amount, discount, category, Project risk, template deviation or Workspace policy. Approval permits sending or awarding; it does not accept for the recipient.

11.4 Recipient acceptance

Acceptance requires:

• Exact version displayed
• Identity and active session
• Required acknowledgements
• Timestamp and time zone
• IP/user-agent metadata where policy allows
• Typed name/signature or explicit acceptance mechanism
• Copy available to recipient

11.5 Award

Authorized issuer selects a Proposal or fixed Offer. Award records selection actor, selected version, approved amount, rationale where required and any internal comparison record. Award is not exposed to losing Providers beyond the configured outcome notification.

11.6 Conversion

Conversion creates the Commitment and appropriate operational record atomically. Repeated commands are idempotent.

12. Category-Specific Proposal Content

12.1 Vendors and Product Suppliers

• SKU/model and description
• Quantity
• Trade/retail/list price where permitted
• Availability
• Deposit/balance
• Freight and delivery
• Tax
• Lead time
• Returns, claims and warranty
• Substitution/expiry rules

12.2 Millwork and Fabrication

• Assemblies/rooms
• Drawing and measurement basis
• Materials and finishes
• Samples/mockups
• Fabrication and install
• Approval milestones
• Allowances
• Schedule and exclusions

12.3 Contractors and Trades

• Labour/material breakdown
• Allowances and alternates
• Mobilization
• Permits
• Schedule and dependencies
• Site conditions
• Change rules
• Progress billing

12.4 Photography

• Brief and shot list
• Shoot date/crew
• Deliverables
• Retouching/revisions
• Delivery turnaround
• Licensing/usage rights
• Travel/expenses

12.5 Measurement and Drafting

• Site visit
• Measurement scope
• Deliverable formats
• Drawing standards
• Revisions
• Turnaround
• File ownership/licence

12.6 Receiving, Warehouse and Storage

• Receiving/inspection fees
• Condition photography
• Handling rates
• Storage basis and minimums
• Recurring billing period
• Pull/release fees
• Insurance/liability assumptions
• Hours and appointment rules

12.7 White-Glove Delivery

• Item manifest
• Pickup/drop-off
• Vehicle and crew assumptions
• Stairs/elevator/access
• Travel/wait time
• Assembly/placement
• Packaging removal
• Tracking and proof
• Damage/exception terms

12.8 Installation

• Item/room scope
• Crew and duration
• Site readiness assumptions
• Assembly/mounting
• Exclusions
• Deficiency process
• Completion evidence

13. Commercial Commitments

13.1 Creation

A Commitment is created only from an accepted/awarded commercial source or authorized direct-entry exception. It stores:

• Source record/version
• Parties and roles
• Project and Workspace
• Currency and tax basis
• Original amount
• Current approved amount
• Scope snapshot
• Payment schedule
• Terms snapshot
• Effective date
• Cancellation/change policy

13.2 Commitment ledger

The Commitment financial ledger derives:

• Original commitment
• Accepted Change Orders
• Current commitment
• Invoiced
• Credits
• Paid
• Outstanding
• Remaining uninvoiced

The ledger is recomputable and reconciled against invoice/payment records.

14. Work Orders and Provider Jobs

14.1 Work Order states

draft
→ issued
→ acknowledgement_due
→ acknowledged
→ scheduled
→ in_progress
→ blocked / awaiting_evidence
→ ready_to_invoice
→ partially_invoiced
→ fully_invoiced
→ complete / cancelled

14.2 Work Order tabs

1. Overview
2. Scope & Items
3. Milestones
4. Tasks
5. Schedule
6. Communication
7. Files
8. Evidence
9. Change Orders
10. Invoices
11. Activity
12. History

14.3 Acknowledgement

Acknowledgement confirms receipt and operational readiness. It does not replace Proposal acceptance. Provider can flag conflicts, missing information or schedule risk before acknowledging.

14.4 Provider Job

A Provider Job is a Project-scoped projection around one or more Work Orders awarded to the Provider. It is not a duplicate Project and does not grant unrelated access.

14.5 Project access grant

Conversion creates a revocable access grant defining:

• Provider Workspace
• Project
• Source Work Order
• Visible rooms/items/files
• Permitted communications
• Operational capabilities
• Effective and expiry times
• Revocation reason

14.6 Category operations

Work Order state may be driven by category evidence:

• Storage receiving and condition records
• Delivery route milestones and proof
• Installation completion and deficiencies
• Millwork drawing/fabrication approvals
• Trade inspections and closeout
• Photography asset delivery and rights

15. Evidence Recipes

15.1 Purpose

Evidence recipes define what proves that awarded work reached a milestone and can progress or be invoiced.

15.2 Recipe fields

• Evidence type
• Responsible role
• Timing/milestone
• Required metadata
• Required file/photo/signature
• Reviewer/approval
• Exception path
• Invoice eligibility effect
• Client visibility

15.3 Examples

• Storage: item received, quantity, condition, photos and location
• Delivery: load confirmation, en route, delivered, item outcome, signature and photos
• Installation: installed/blocked per item, deficiency and completion photo
• Millwork: approved shop-drawing version and fabrication milestone
• Photography: asset set delivered and usage rights confirmed

The Work Order snapshots the recipe version.

16. Change Orders

16.1 Triggers

• Scope addition/removal
• Quantity change
• Price change
• Schedule change
• Allowance reconciliation
• Site condition
• Substitution
• Client-requested change
• Provider-requested change

16.2 States

draft
→ internal_review
→ submitted
→ viewed
→ revision_requested
→ accepted / declined / withdrawn / expired
→ applied

16.3 Application

Accepted Change Order appends to the Commitment and updates current approved amount/schedule. Original and previous values remain visible. Related Project budget and Work Order projections rebuild.

16.4 Emergency work

Emergency work requires a governed exception containing reason, authorizer, amount cap and retrospective documentation deadline. It cannot silently bypass the Change Order record.

17. Invoices

17.1 Invoice sources

• Deposit
• Milestone
• Delivered products
• Approved time and expenses
• Recurring storage/service period
• Accepted Change Order
• Final completion
• Credit/refund adjustment

17.2 Invoice states

draft
→ submitted
→ validation_failed / under_review
→ action_required
→ approved
→ payment_pending
→ partially_paid
→ paid
→ overdue / disputed
→ void

Void is governed and retains the original record. A paid invoice cannot be deleted.

17.3 Line eligibility

Every invoice line references eligible Commitment scope, milestone, item, time entry, expense, recurring period or Change Order. The system blocks duplicate billing beyond configured tolerance.

17.4 Invoice validation

• Correct parties and Project
• Active Commitment
• Currency consistency
• Tax calculation/registration fields
• Line eligibility
• Quantity/amount remaining
• Required evidence complete
• Milestone achieved
• Duplicate number/file detection
• Banking/payment details policy

17.5 Provider invoice submission

Providers can generate an invoice from eligible Work Order lines or upload an external invoice. Uploaded documents enter AI-assisted extraction and mandatory Provider confirmation before submission.

17.6 Designer Client invoices

Designer Studios can invoice from Client engagement payment schedules, retainers, hourly work, milestones, procurement services or completion. Client-visible invoices inherit approved branding and terms.

17.7 Recurring invoices

Recurring storage or services create draft invoice periods from a schedule. Each period is reviewable before issue. Changes to rates or quantity require governing commercial authority.

17.8 Credits and refunds

Credit notes reference original invoice lines and reason. Refunds reference payment and credit allocation. Totals remain auditable.

18. Payments

18.1 Payment rails

• Stripe online payment
• Manual bank transfer
• Cheque/other recorded manual payment where enabled
• Credit balance application

18.2 Stripe

The platform creates payment requests from the canonical invoice. Processor customer, payment and intent IDs are stored as external references. Webhooks are verified, idempotent and authoritative for settlement state.

18.3 Large payments

For large Project amounts, manual bank payment instructions may be preferred. The platform records instructions, expected amount, reference, receipt evidence, reconciliation actor and date. Manual recording requires appropriate authority and audit.

18.4 Payment states

requested
→ processing
→ succeeded / failed / cancelled
→ partially_refunded / refunded
→ disputed

18.5 Allocation

A payment may allocate across one or more invoices where the commercial policy allows. Allocation records preserve amount, currency, invoice, actor/source and date. Unallocated balance is explicit.

18.6 Payment failure and dispute

Failure or dispute creates attention, notification and reconciliation work. It does not erase earlier payment attempts.

18.7 Provider payout

If The Design Registry collects funds and pays a Provider, Client receipt and Provider payout are separate records. The platform must not mark a Provider invoice paid until the Provider-side settlement condition is satisfied.

19. QuickBooks and Accounting Integration

19.1 Source-of-truth rule

The Design Registry is authoritative for Project scope, Work Order lineage, evidence and operational invoice eligibility. QuickBooks may be authoritative for configured accounting records after sync.

19.2 Sync objects

• Customers/contacts
• Vendors
• Products/services or mapped categories
• Invoices
• Credit notes
• Payments
• Tax codes
• Accounts/classes/locations where configured

19.3 Mapping

Workspace settings define mapping version and effective date. Unmapped records enter reconciliation rather than silently using a default account.

19.4 Sync states

• Not connected
• Ready
• Queued
• Synced
• Conflict
• Failed/retryable
• Failed/manual action

19.5 Conflict handling

Conflicts show both values, source timestamps and permitted resolutions. Financial records are never blindly last-write-wins.

20. Navigation and Record Experience

20.1 Global navigation

Offers
Proposals
Work Orders
Invoices
Payments

The initial shell may group them under Commercial to reduce navigation weight.

20.2 Shared tables

Each table supports search, filters, sorting, saved views, columns, export, pagination/virtualization and permitted bulk actions.

20.3 Workspace scope

• Designers see records they issue, receive or are party to.
• Clients see Client-facing records requiring action or payment.
• Providers see Offers received, Proposals authored, awarded Work Orders and their invoices/payments.
• Registry operators see records within authorized market/Project scope.

20.4 Record tabs

Commercial records reuse:

• Overview
• Document/preview
• Line items
• Project scope
• Activity
• Notes, internal where allowed
• Files
• Communication
• Related records
• History

21. Notifications Builder Integration

21.1 Required events

offer.ready_to_send
offer.sent
offer.viewed
offer.clarification_requested
offer.expiring
offer.accepted
offer.declined
offer.awarded

proposal.internal_review_requested
proposal.sent
proposal.viewed
proposal.revision_requested
proposal.accepted
proposal.declined
proposal.expiring
proposal.awarded

work_order.issued
work_order.acknowledgement_due
work_order.acknowledged
work_order.blocked
work_order.ready_to_invoice
work_order.completed

change_order.submitted
change_order.accepted
change_order.declined

invoice.submitted
invoice.action_required
invoice.approved
invoice.payment_due
invoice.overdue
invoice.partially_paid
invoice.paid
invoice.disputed

payment.processing
payment.succeeded
payment.failed
payment.refunded
payment.disputed
accounting.sync_failed

21.2 Channels

• In-app
• Resend email
• Twilio SMS for configured urgent/payment events
• Push, future

Documents use secure links rather than sensitive full contents in SMS.

21.3 Recipient rules

Recipients are resolved from commercial parties, Project role, assignment, Workspace membership, Team rules and personal preferences. Losing Provider notifications never reveal award recipient.

22. Numbering, Rendering and Audit

22.1 Numbering

Workspace-scoped collision-safe sequences support document type and optional fiscal period:

OFF-2026-0042
PROP-2026-0088
WO-2026-0114
PO-2026-0201
CO-2026-0016
INV-2026-0302
CR-2026-0007

Numbers are assigned at issuance/submission, never preview, and never reused.

22.2 Rendered artifact

Sent/issued versions store:

• Structured snapshot
• Rendered PDF/artifact
• Content hash
• Template version
• Rendering version
• Locale/currency
• Timestamp

22.3 Audit

Material events include actor, active Workspace, source, timestamp, IP/device metadata where policy allows, before/after, reason, correlation ID and related record/version.

23. Access and Visibility

23.1 Visibility classes

23.2 Enforcement surfaces

The same visibility applies to:

• API responses
• Global/Project tables
• Search
• Files and signed URLs
• Notifications
• Exports
• Realtime events
• AI context
• Accounting/payment integrations

23.3 Internal notes

Internal notes are separate records from counterparty communication. A visibility toggle cannot accidentally publish an unrestricted internal note.

24. AI Assistance

24.1 Approved uses

• Draft Proposal scope from Project records
• Suggest category template
• Extract line items from uploaded quote, PO or invoice
• Import product details from an authorized URL or vendor integration
• Compare Proposal versions
• Summarize commercial differences
• Flag possible duplicate invoice lines
• Draft clarification or revision messages

24.2 Guardrails

• Extracted data remains draft until user confirmation.
• AI cannot accept, award, sign, issue, approve invoice, record manual payment or change bank details.
• AI only receives viewer-authorized records.
• Calculations are deterministic; AI does not calculate authoritative totals.
• Suggestions cite source Project records/documents and confidence.

25. Data Model

commercial_document_templates
commercial_document_template_versions
commercial_clause_definitions
commercial_calculation_rules
commercial_numbering_rules

work_packages
work_package_versions
work_package_items
work_package_files
scope_differences

offers
offer_recipients
offer_responses
offer_clarifications

proposals
proposal_versions
proposal_sections
proposal_line_items
proposal_acceptances
proposal_awards

commercial_commitments
commercial_commitment_sources
commercial_commitment_parties
commercial_commitment_ledger_entries

work_orders
purchase_orders
work_order_milestones
work_order_assignments
evidence_recipes
evidence_recipe_versions
work_order_evidence
project_access_grants

change_orders
change_order_versions
change_order_acceptances

invoices
invoice_versions
invoice_line_items
invoice_approvals
credit_notes

payment_requests
payments
payment_events
payment_allocations
refunds
disputes

accounting_connections
accounting_mappings
accounting_sync_jobs
accounting_sync_conflicts

25.1 Constraints

• Sent/accepted/issued versions are immutable.
• Line item currency matches its document.
• Commitment sources reference exact accepted/awarded versions.
• Invoice lines cannot exceed eligible remaining scope without governed exception.
• Payment event provider IDs are unique by processor.
• Project access grants reference governing commercial records.

26. API Design

26.1 Work Packages and Offers

POST /v1/projects/:projectId/work-packages
POST /v1/work-packages/:id/versions
POST /v1/work-package-versions/:id/offers
POST /v1/offers/:id/send
POST /v1/offers/:id/respond
POST /v1/offers/:id/clarifications

26.2 Proposals

POST /v1/projects/:projectId/proposals
POST /v1/proposals/:id/versions
POST /v1/proposal-versions/:id/internal-review
POST /v1/proposal-versions/:id/send
POST /v1/proposal-versions/:id/accept
POST /v1/proposal-versions/:id/award
POST /v1/proposal-versions/:id/convert

26.3 Work Orders and Changes

GET  /v1/workspaces/:workspaceId/work-orders
GET  /v1/work-orders/:id
POST /v1/work-orders/:id/acknowledge
POST /v1/work-orders/:id/evidence
POST /v1/work-orders/:id/change-orders
POST /v1/change-orders/:id/submit
POST /v1/change-orders/:id/respond

26.4 Invoices and payments

POST /v1/work-orders/:id/invoices
POST /v1/commitments/:id/invoices
POST /v1/invoices/:id/submit
POST /v1/invoices/:id/approve
POST /v1/invoices/:id/payment-requests
POST /v1/payments/manual
POST /v1/webhooks/stripe
POST /v1/payments/:id/allocations
POST /v1/payments/:id/refunds

Commands are idempotent and enforce active relationship, capability, record version and optimistic concurrency.

27. Supabase and Integration Architecture

27.1 Supabase services

• Postgres canonical commercial data
• Row Level Security by Workspace, Project relationship and commercial party
• Storage for rendered documents, attachments and evidence
• Edge Functions for rendering orchestration, acceptance, Stripe webhooks, QuickBooks sync, Resend and Twilio
• Realtime for non-authoritative status refresh
• Background jobs/outbox for documents, notifications, reconciliation and projections

27.2 Security

Service-role credentials remain server-side. Signed document URLs are short-lived and authorized before issuance. Stripe webhook signatures are verified. Manual payment recording requires privileged audited commands.

27.3 Outbox processing

Commercial state changes emit durable events. Handlers idempotently update Project/budget projections, notifications, accounting sync and dashboard attention.

28. Reporting and Reconciliation

28.1 Commercial reporting

• Proposal value and acceptance rate
• Offer response and award rate
• Commitment value
• Change Order value
• Invoiced, paid and outstanding
• Aging
• Provider payment cycle
• Project budget variance
• Revenue/fee components by authorized audience

28.2 Reconciliation controls

• Commitment vs invoice eligibility
• Invoice vs payment allocation
• Stripe vs internal payments
• QuickBooks vs internal records
• Project budget vs commercial ledger
• Duplicate external invoice numbers

Discrepancies enter Data Reconciliation with owner, status, evidence and resolution.

29. User Stories

29.1 Designer

• As a Designer, I can create a branded Client Proposal from Project phases and fees.
• As a Designer, I can send selected Project items to a Provider for quote without rebuilding a spreadsheet.
• As a Designer, I can compare Provider responses privately and award one.
• As a Designer, I can see committed, invoiced and paid amounts in the Project budget.

29.2 Provider

• As a Provider, I can receive an Offer with the exact scope needed to quote.
• As a Provider, I can create a category-specific Proposal and retain my own private drafting data.
• As a Provider, I can acknowledge a Work Order and operate only the work assigned to me.
• As a Provider, I can invoice eligible work and track payment.

29.3 Client

• As a Client, I can review a polished Proposal, ask questions and accept the exact version.
• As a Client, I can receive and pay invoices without seeing internal Provider or Registry economics.

29.4 Registry operator

• As an operator, I can trace an invoice to approved scope, evidence and commercial lineage.
• As an operator, I can reconcile processor/accounting conflicts without rewriting history.

30. Acceptance Criteria

30.1 Project and scope

• Work Packages select and snapshot Project records.
• Later Project changes do not mutate sent commercial versions.
• Material differences require reissue, addendum or Change Order.
• Project budget aggregates drill into commercial sources.

30.2 Offers and Proposals

• Providers see only their Offer and authorized Work Package.
• Internal approval, recipient acceptance, award and conversion are distinct.
• Submitted/sent versions and rendered artifacts are immutable.
• Designer Client Proposals support Workspace branding and legal-party clarity.

30.3 Work Orders

• Accepted/awarded source creates exactly one idempotent Commitment and operational subtype.
• Provider Job access is limited to awarded scope.
• Category Evidence Recipes can control milestones and invoice readiness.
• Changes cannot silently reprice awarded work.

30.4 Invoices and payments

• Every invoice line references eligible scope.
• Duplicate/overbilling rules run before approval.
• Stripe state derives from verified webhooks.
• Manual payments require evidence and audit.
• Credits, refunds, disputes and partial allocations preserve history.
• QuickBooks conflicts never silently overwrite canonical records.

30.5 Navigation and notifications

• Global and Project views show the same canonical records.
• Provider tables contain only records sent to, authored by, awarded to or payable to that Provider.
• Every material event has a Notification Builder definition and delivery history.

30.6 Security

• RLS tests prove commercial-party and Project isolation.
• Exports, files, search, realtime, notifications and AI obey the same visibility model.
• Service credentials and payment secrets never reach the browser.

31. Test Matrix

31.1 Versioning

• Edit before send
• Edit after send
• Recipient opens superseded version
• Acceptance races with withdrawal
• Duplicate conversion command
• Template version retired after document sent

31.2 Scope

• Item removed after quote
• Quantity changed after award
• Schedule changed after acknowledgement
• Access grant revoked
• Change Order accepted while invoice draft exists

31.3 Financial

• Partial invoice and partial payment
• Overbilling attempt
• Duplicate Provider invoice number
• Payment succeeds after page closes
• Duplicate/out-of-order Stripe webhook
• Manual payment later found incorrect
• Refund and credit allocation
• QuickBooks conflict

31.4 Visibility

• Competing Providers
• Client vs internal line items
• Provider private draft
• Registry market restriction
• Signed URL after access revocation
• Notification recipient removed before send

32. Migration Plan

32.1 Preserve current experience

Reuse the existing Proposals navigation placeholder, Project tabs, enterprise grids, shared record tabs, files, tasks, communication, activity and Notifications Builder.

32.2 Normalize legacy records

• Assign canonical commercial types and statuses.
• Map legacy proposals to immutable versions.
• Backfill Project and party relationships.
• Preserve original files and identifiers.
• Flag records without sufficient lineage for reconciliation.

32.3 Shadow reconciliation

Before enabling payments, compare commitment, invoice, payment and Project budget projections in shadow mode. Resolve discrepancies through Data Reconciliation.

33. Implementation Phases

Phase 1 — Commercial foundation

• Templates and numbering
• Parties/relationships
• Versioned documents
• Rendering and audit
• Access/visibility

Phase 2 — Work Packages and Offers

• Project selection
• Category presets
• Recipient Offer experience
• Clarifications and deadlines
• Matchmaking handoff

Phase 3 — Proposal Builder

• Designer Client Proposals
• Provider Proposals
• Internal review
• Acceptance and award
• Branding and PDF/web preview

Phase 4 — Commitments and Work Orders

• Conversion
• Provider Jobs and access grants
• Milestones/tasks/schedule
• Category Evidence Recipes

Phase 5 — Changes and invoices

• Difference engine
• Change Orders
• Invoice eligibility and approval
• Recurring/storage billing
• Credits

Phase 6 — Payments and accounting

• Stripe
• Manual bank payments
• Allocation/refunds/disputes
• QuickBooks sync
• Reconciliation

Phase 7 — Category expansion and intelligence

• Purchase Orders/vendor workflows
• Category-specific Proposal templates
• AI extraction/import
• Reporting and optimization

Every phase includes RLS tests, audit, Notification Builder events, mobile states, accessibility and reconciliation.

34. Definition of Done

The commercial system is complete when:

1. Designers can send branded Client Proposals from Project scope.
2. Every Provider category can receive a tailored Offer, submit a Proposal and operate an awarded Work Order.
3. Projects, global tables and Provider portals show the same canonical records.
4. Sent and accepted versions are immutable and verifiable.
5. Internal approval, acceptance, award, conversion, invoice approval and payment are distinct.
6. Material Project changes use governed commercial changes.
7. Invoice lines can be traced to eligible Commitment scope and evidence.
8. Stripe, manual payments and QuickBooks reconcile without overwriting history.
9. Commercial visibility is enforced across every delivery surface.
10. Every commercial event is auditable and registered in the Notifications Builder.

The Design Registry commercial system should remove duplicate administration while making every commitment, Project handoff, invoice and payment easier to understand and harder to dispute.

<!-- CURRENT-PRODUCT-GAP-COVERAGE:START -->

Current-product review gap closure register

Generated: August 4, 2026
Owning future specification: 06
Mapped current-product profiles: 2
Recorded review gaps: 7

This register is part of the release contract. It maps the current-product reverse review into required future behavior. A gap is not closed because a screen exists; closure requires the corrected canonical data, permissions, states, migration, audit and test evidence described below.

Register rules

1. Every profile in the Current Product Library must resolve to one owning future specification.
2. Current limitations are evidence, not optional ideas. If a limitation is intentionally retained, the specification must record the decision, risk, owner and review date.
3. Shared-component defects are corrected through Spec 16 and then consumed here; feature teams may not create local replacement controls.
4. Permission, contact, financial and visibility defects also require Spec 08 enforcement, even when the functional feature is owned by another specification.
5. Legacy Proper Gallery, Lead, Partner and implementation-facing labels are migration inputs only and must not return through new UI, APIs, exports or notifications.
6. Verification must use realistic fixtures for Admin, Designer, Provider and Client audiences where applicable.

G01 — Record Proposals

Current-product profile: record-proposals
Observed route: /admin/leads/:id?tab=proposals
Evidence confidence: Known limitation

Review gaps

• Dedicated proposal content is missing.
• No global proposal route is currently available.
• No statuses, versioning, approvals, PDFs or acceptance behavior are evidenced.
• Coming soon does not provide timing, documentation or an alternate workflow.

Required future closure

• Implement Spec 06 proposal, work-order and invoicing model.
• Provide record-scoped list plus global table from one canonical dataset.
• Support Designer proposals and Provider quotes with configurable branded templates.
• Replace the disabled placeholder only when loading, empty, populated, error and permission states exist.

Closure evidence required

• The corrected behavior is demonstrated in the relevant loading, empty, populated, error, permission and responsive states.
• Server-side rules, data migration and audit behavior are verified where this feature changes canonical records.
• Automated tests cover the identified defect or missing journey so it cannot silently regress.
• Product, Engineering and the operating owner accept any deliberately deferred item with an owner and target phase.

G02 — Proposals directory

Current-product profile: proposals-directory
Observed route: Coming soon — no route
Evidence confidence: Verified

Review gaps

• No working route.
• No Coming soon label.
• No directory, profile, template, version, line item, send, acceptance or conversion behavior can be verified.

Required future closure

• Label the placeholder Coming soon immediately.
• Build the shared Proposals directory and Proposal Profile from Spec 06.
• Expose Project-scoped and Provider-owned projections from the same records.
• Connect accepted Proposals to Commitments, Work Orders, Invoices and Payments.

Closure evidence required

• The corrected behavior is demonstrated in the relevant loading, empty, populated, error, permission and responsive states.
• Server-side rules, data migration and audit behavior are verified where this feature changes canonical records.
• Automated tests cover the identified defect or missing journey so it cannot silently regress.
• Product, Engineering and the operating owner accept any deliberately deferred item with an owner and target phase.

<!-- CURRENT-PRODUCT-GAP-COVERAGE:END -->