18 - Integrations, Connected Accounts & Data Sync

Product: The Design Registry
Version: 1.0
Prepared: August 2026
Status: Engineering and product source of truth
Backend: Supabase/Postgres with trusted server and worker execution
Depends on: Product Vision; Spec 03 Teammates, Teams, Role Labels & Notifications; Spec 06 Proposals, Work Orders, Invoicing & Payments; Spec 07 Projects, Calendar, Items, Budgets & Provider Operations; Spec 08 Permissions; Spec 09 Pipeline, Forms & Automation Builder; Spec 11 Communications; Spec 12 Tasks, Calendar & Resource Scheduling; Spec 17 Identity & Account Security
Connector scope: Resend, Twilio, Gmail, Google Calendar, Google Sheets, Stripe, QuickBooks Online, approved Vendor/Product APIs, carrier/tracking APIs and the website lead plugin

1. Executive Summary

The Design Registry must connect Designers, Providers, Clients and Registry operators to the specialist tools they already use without turning those tools into disconnected copies of Project data.

This specification defines one shared integration platform that every connector reuses:

• Connected Account management;
• OAuth and credential lifecycle;
• secret isolation and encryption;
• capability and Workspace authorization;
• webhooks and provider-event ingestion;
• durable jobs, queues, retries and dead letters;
• synchronization cursors and checkpoints;
• canonical object mapping;
• source-of-truth rules;
• conflict and reconciliation workflows;
• provenance and freshness;
• connection-health monitoring;
• audit and security events; and
• a consistent Settings and support experience.

The architecture follows build once, reuse everywhere. Gmail, Google Calendar, QuickBooks and Vendor APIs must not each invent different token tables, retry rules, error pages or webhook models.

Projects remain the operational center. External systems may be authoritative for a specialist domain—QuickBooks for accounting ledger entries, Stripe for processor settlement, Gmail for the connected mailbox, Google Calendar for selected external calendar events and Vendor systems for published catalogue data—but the Registry remains authoritative for Project relationships, workflow state, permissions, approvals, provenance and audit.

No integration may bypass the same permissions, field restrictions, Project access, commercial approval rules or notification policies that apply to a person using the application.

2. Product Decisions

1. Integrations are platform infrastructure, not features embedded separately in each module.
2. Every external record has a declared authority model; no connector uses blind last-write-wins.
3. User-managed, Workspace-managed and platform-managed connections are separate ownership classes.
4. External calls occur after the originating business transaction commits.
5. A durable outbox and server-consumed queue handle asynchronous work.
6. Provider webhooks are untrusted until signature, timestamp and replay validation pass.
7. External delivery is assumed to be repeatable; all handlers and commands are idempotent.
8. Provider access tokens and refresh tokens never enter ordinary application tables readable by clients.
9. Connection removal stops future access but does not erase canonical business history.
10. The first Google Sheets release supports governed import, refresh preview and export—not uncontrolled two-way editing.
11. Gmail is used for human correspondence; Resend is used for platform transactional delivery.
12. Google sign-in consent is separate from Gmail, Calendar, Sheets and Drive integration consent.
13. Stripe settlement state comes from verified webhooks or trusted reconciliation, never a browser success redirect.
14. QuickBooks does not determine Project Phase, Provider Job state or Work Order completion.
15. Vendor integrations are vendor-neutral. No single furniture supplier becomes mandatory infrastructure.
16. Website forms create auditable Pipeline Records through a narrow ingestion contract.
17. Integration failures are visible, actionable and recoverable; silent failure is not acceptable.

3. Outcomes and Measures

3.1 User outcomes

• A Workspace Owner can connect business services from one consistent Settings area.
• A user can understand exactly which account, permissions and data scope are connected.
• A Designer can connect Gmail and selected calendars without importing unrelated personal data.
• A Project team can import a spreadsheet with preview, field mapping and provenance.
• A Provider can use category-specific integrations without exposing credentials to Designers or Clients.
• A finance user can reconcile Stripe and QuickBooks exceptions without losing Project lineage.
• A user can disconnect safely and understand what will stop, remain and require follow-up.

3.2 Operational outcomes

• One connection framework supports every connector.
• Duplicate webhook delivery never duplicates payments, messages, events, items or invoices.
• Retryable errors recover automatically.
• Permanent errors reach a visible reconciliation or dead-letter workflow.
• Connection health and sync freshness are measurable by Workspace and connector.
• Support can diagnose failures without seeing raw secrets or unnecessary customer data.

3.3 Success measures

• Connection completion rate by connector.
• Median time to first successful sync.
• Sync success rate and freshness SLA.
• Webhook verification failure and replay rate.
• Retry recovery rate.
• Dead-letter count and median resolution time.
• Duplicate external-event suppression rate.
• Mapping/reconciliation exception rate.
• OAuth reconnect rate.
• Data correction rate after imports.
• Payment/accounting reconciliation lag.
• User-initiated disconnect completion rate.
• Zero verified cross-Workspace data leakage.
• Zero provider secrets in browser bundles, logs or client-readable rows.

4. Scope

4.1 In scope

• Integration directory and Settings experience.
• Connection ownership and lifecycle.
• OAuth, API key and service-account patterns.
• Secure server-side credential storage.
• Google incremental authorization.
• Webhook endpoints and event inbox.
• Durable outbox, queues, workers and schedules.
• Sync jobs, cursors, checkpoints and reconciliation.
• Object/field mapping and transform versions.
• Connection health, failures, retry and manual repair.
• Import/export provenance.
• Connector contracts for the named launch services.
• Public integration API and website form plugin.
• Permission, audit, notification and security requirements.
• Supabase/Postgres implementation architecture.

4.2 Out of scope

• Rebuilding Gmail, QuickBooks, Google Sheets or Vendor commerce systems.
• A general public app marketplace at launch.
• Customer-authored executable connector code.
• Arbitrary database access for external providers.
• Unreviewed Zapier-style actions with access to all Workspace data.
• Full two-way synchronization for every object.
• Treating external spreadsheets as the permanent Project database.
• Automatic financial conflict resolution.
• Storing payment-card data in the Registry.
• Scraping websites in violation of access terms.

5. Core Concepts

5.1 Connector Definition

Versioned platform metadata describing a provider, authentication method, supported capabilities, object types, scopes, webhooks, health checks and configuration schema.

5.2 Connected Account

An authorized relationship between a connector and a Platform, Workspace or User owner. It identifies the external tenant/account and the granted capabilities without exposing credentials.

5.3 Connection Grant

The encrypted provider credential set and approved scope attached to a Connected Account. Grant material is server-only.

5.4 External Object Reference

A durable mapping between one canonical Registry record and one external provider object, including provider ID, tenant, object type, version and sync state.

5.5 Sync Profile

Configuration defining direction, included objects, filters, mapping version, conflict policy, schedule and Workspace scope.

5.6 Sync Job

One requested execution with state, cursor, counts, warnings, errors and reconciliation results.

5.7 Provider Event

A verified external webhook or polled change stored once before domain processing.

5.8 Integration Command

A durable request to perform an external side effect, such as send email, create payment intent, publish event or create QuickBooks invoice.

5.9 Mapping Profile

Versioned mapping from external fields and enumerations into canonical Registry fields and states.

5.10 Reconciliation Case

A user-resolvable exception where identity, mapping, authority, amount or state cannot be safely decided automatically.

5.11 Provenance

Source connector, external object, source observation time, sync/import job, mapping version, proposed value, accepted value and approving actor.

6. Connection Ownership

Connections are never transferred implicitly when a user leaves. User-owned connections pause immediately when the owner loses the relevant Membership. Workspace-owned connections remain only when another authorized connection administrator exists.

7. Source-of-Truth Matrix

8. Shared Integration Architecture

Business transaction
    -> canonical record + domain event + outbox row (one transaction)
    -> queue dispatcher
    -> connector worker
    -> external provider
    -> verified response or webhook
    -> provider-event inbox
    -> mapping/reconciliation
    -> canonical state update
    -> activity + notification + audit

8.1 Transactional outbox

Any business mutation that requires external work writes its canonical state and an outbox event in one database transaction. The external call does not occur inside the business transaction.

8.2 Durable queue

Integration jobs use a durable server-consumed queue. Client-side access to queue tables/functions remains disabled. Queue payloads contain IDs and safe routing metadata, not full message bodies, secrets or payment data.

8.3 Workers

Workers:

• acquire a visible queue message;
• load current command and connection state;
• verify that the connection and authorization are still valid;
• obtain server-side credentials;
• enforce provider rate limits;
• execute idempotently;
• persist response/reference;
• acknowledge/archive on success; and
• retry or dead-letter on classified failure.

Request-lifetime background tasks may perform short best-effort follow-up only. They are not the durability boundary for payment, email, sync, calendar or accounting work.

8.4 Schedules

Scheduled incremental sync and health checks use a governed scheduler to enqueue jobs. Scheduling never executes large synchronization work directly inside a database transaction.

9. Integration Settings Experience

Settings
└── Integrations
    ├── Connected Accounts
    ├── Communications
    ├── Calendar
    ├── Sheets & Imports
    ├── Payments
    ├── Accounting
    ├── Products & Vendors
    ├── Website & Lead Capture
    ├── Webhooks & API
    ├── Mapping & Reconciliation
    └── Sync Health

9.1 Integration directory

Each connector card shows:

• provider name and purpose;
• connection owner class;
• availability for the current Workspace type;
• required capability;
• connected account identity;
• granted scope summary;
• status and last success;
• setup/reconnect/manage action; and
• link to privacy and data-use explanation.

9.2 Connection detail

Tabs:

• Overview;
• Data & Scope;
• Sync Rules;
• Mapping;
• Activity;
• Errors;
• Security; and
• Disconnect.

9.3 Statuses

not_connected
connecting
active
action_required
degraded
rate_limited
permission_changed
expired
revoked
paused
disconnecting
disconnected

9.4 Disconnect preview

Before disconnecting, show:

• affected automations/sync profiles;
• queued work that will be cancelled or allowed to finish;
• data retained in the Registry;
• external subscriptions/webhooks to be removed;
• records requiring manual follow-up; and
• reconnect behavior.

10. Connection and Consent Flow

Choose connector
-> explain owner, purpose, scopes and data direction
-> verify capability and recent authentication when required
-> create short-lived signed connection intent
-> redirect to provider authorization
-> validate state and exact callback
-> exchange code server-side
-> identify external tenant/account
-> store encrypted grant
-> configure subscriptions/webhooks
-> run health test and initial discovery
-> show configuration review
-> activate sync profile

Google sign-in and Google business integration use separate consent transactions. Connecting Gmail later must not mutate the authentication identity or silently grant Calendar/Drive access.

OAuth callbacks are one-time, environment-bound and linked to the initiating User, Workspace and connector. Client-provided return URLs are not trusted.

11. Credentials and Secret Management

11.1 Secret classes

• platform API keys;
• webhook verification secrets;
• OAuth client secrets;
• user/Workspace OAuth access and refresh tokens;
• Provider API credentials;
• signing keys; and
• temporary connection-intent secrets.

11.2 Storage rules

• Platform runtime secrets use the approved server/Edge Function secret manager.
• Per-connection grants use encrypted server-only storage with key rotation and access audit.
• Supabase Auth provider tokens are not treated as a long-term Gmail/Calendar/Sheets token store.
• Vault may be used only after security review of its current feature status and operational requirements; the domain model must not depend on a specific secret-store implementation.
• Browser-visible tables hold only masked account identity, granted scope names, status and safe metadata.
• Logs never include authorization headers, access tokens, refresh tokens, API keys, raw signatures or full banking identifiers.

11.3 Rotation and revocation

Support key-version metadata, credential rotation without replacing the Connected Account, provider revocation, breach-driven bulk disablement and proof that obsolete ciphertext can no longer be decrypted after retirement policy permits.

12. Sync Engine

12.1 Modes

• one-time import;
• one-way inbound sync;
• one-way outbound publication;
• controlled two-way sync;
• webhook-driven observation;
• scheduled incremental polling; and
• on-demand reconciliation.

12.2 Sync lifecycle

requested -> queued -> running
-> completed / completed_with_warnings
-> retry_wait / action_required / failed / cancelled

12.3 Cursor contract

Each incremental profile stores provider cursor/token, observed-through time, last successful checkpoint and safe restart data. Advance the committed cursor only after the corresponding canonical changes are durable.

12.4 Pagination and partial completion

Jobs checkpoint between pages/batches. A timeout or provider outage resumes from the last committed checkpoint without replaying accepted side effects.

12.5 Initial sync

Initial discovery estimates record volume and allows scope refinement. Large imports run asynchronously with progress, cancellation boundaries and visible partial results.

13. Webhook Ingestion

13.1 Endpoint contract

Each provider endpoint:

1. preserves the raw request bytes required for verification;
2. resolves the provider/environment;
3. verifies signature/secret and timestamp;
4. rejects stale/replayed invalid requests;
5. computes a provider-event deduplication key;
6. stores a minimal immutable inbox event;
7. returns the provider-required response quickly; and
8. queues domain processing.

13.2 Trust boundary

Webhook payloads do not authorize a User. They are accepted only through provider verification and then mapped to a known active Connected Account and external reference.

13.3 Ordering

Events may arrive late, duplicated or out of order. Processing compares provider version/occurred time and retrieves current provider state where event payloads are insufficient.

13.4 Retention

Store safe normalized events and a protected raw-payload reference only as long as operational, legal and support policy requires. Redact or encrypt sensitive payload fields.

14. Idempotency, Retry and Dead Letters

14.1 Idempotency keys

Outbound commands use a stable key derived from business command identity, connector and intended operation. Retrying a create does not create a second invoice, payment, event or message.

14.2 Error classes

14.3 Retry policy

Connector-specific limits respect Retry-After, provider quotas and event urgency. The platform prevents retry storms with circuit breakers and per-tenant concurrency controls.

14.4 Dead-letter workflow

Dead letters show connector, command, affected business record, safe error, attempts, next action and owner. Actions include retry, reconnect, remap, cancel, mark manually resolved or escalate. Payload editing is prohibited.

15. Mapping, Transformation and Provenance

15.1 Canonical model

Connectors map into stable Registry concepts such as Contact, Workspace, Project, Task, Calendar Event, Item, Product, Purchase Order, Shipment, Invoice, Payment and Message.

15.2 Versioning

Mappings are versioned with effective time. A historical sync can be explained using the mapping version used at execution.

15.3 Enumeration mapping

External states map into canonical states while preserving the raw provider state and observation time. Unknown values enter a review queue rather than silently mapping to “other.”

15.4 Field provenance

For imported or synchronized fields retain:

• source connector/account;
• external object and field;
• source observation time;
• ingestion time;
• mapping version;
• prior canonical value;
• proposed/accepted value;
• confidence where AI assisted; and
• accepting actor/rule.

15.5 AI use

AI may propose mappings, record links or normalized values. It cannot autonomously settle financial conflicts, change approval state, select a Workspace, or attach ambiguous private communications. AI output includes confidence and explanation and follows Spec 08 field restrictions.

16. Reconciliation Centre

One shared Reconciliation Centre handles:

• unmatched Contacts/Customers/Vendors;
• duplicate external objects;
• ambiguous Project/message association;
• tax/account/category mapping failures;
• competing edits;
• payment amount/currency mismatch;
• deleted/recreated external records;
• stale Vendor availability;
• sheet row identity changes; and
• disconnected-account work.

Each case shows both sources, timestamps, authoritative fields, financial/Project impact, recommended action, available resolutions and audit history.

Resolution choices are typed: keep Registry, accept external, merge/link, create mapping, create new record, detach, defer or escalate. Options are filtered by permission and source-of-truth policy.

17. Permissions and Data Minimization

Spec 08 remains authoritative. Initial capabilities:

integrations.view
integrations.connect
integrations.manage
integrations.disconnect
integrations.credentials.rotate
integrations.sync.run
integrations.sync.cancel
integrations.reconciliation.resolve
integrations.webhooks.manage
integrations.api.manage
integrations.logs.view
integrations.sensitive_payload.view

Connection permission does not imply access to every external object. Before outbound sync, payload creation applies record scope and field-level restrictions. A user unable to view internal margin, Client contact details or residential access instructions cannot export them through Sheets, QuickBooks, Calendar, AI or webhooks.

Provider Workspaces receive only Provider Job and Project data explicitly shared with them. Hidden Provider commercial relationships remain hidden from Designers and Clients.

18. Connector Requirements

18.1 Resend

Purpose: platform transactional email and Notification Builder delivery.

• Platform-managed connection.
• Product modules enqueue notification requests; they do not call Resend directly.
• Verified sending domains and approved From identities are environment-specific.
• Store provider message ID and canonical delivery state.
• Verify webhook signatures and deduplicate delivery events.
• Map delivered, delayed, bounced, complained and failed states.
• Suppression/bounce state prevents unsafe repeated sending.
• Security/auth messages use protected templates and cannot be disabled as marketing preferences.

18.2 Twilio

Purpose: Workspace-managed SMS, voice, phone numbers, recording metadata and call events under Spec 11.

• Platform master credentials remain platform-managed.
• Purchased numbers are assigned to a Workspace through governed records.
• Regulatory/address/bundle requirements create explicit pending/action-required states.
• Verify webhook signatures using exact request context.
• Record consent, opt-out, quiet-hours and jurisdiction policy before SMS.
• Calls, recordings and transcripts retain Project/Conversation access controls.
• Releasing or porting a number is high risk, recently authenticated and audited.

18.3 Gmail

Purpose: human business correspondence synchronized into the unified inbox.

• User-managed or approved shared-mailbox connection.
• Separate OAuth consent from Google sign-in.
• Prefer least-permissive modes: selected label, explicit forwarding/routing or approved mailbox scope.
• Do not import every personal email by default.
• Preserve Gmail thread/message identifiers and normalized Message-ID.
• Support incremental sync, push renewal/health and deduplication across forwarding and Gmail ingestion.
• Replies sent through Gmail retain the real sender identity and Project conversation link.
• Ambiguous record association enters communications reconciliation.
• Google provider refresh tokens are stored and refreshed by the trusted application integration layer.

18.4 Google Calendar

Purpose: selected Project and operational event synchronization.

• User or Workspace-managed connection.
• User chooses calendars and direction per Sync Profile.
• Publish only selected Registry events.
• Import free/busy without private details when only availability is required.
• Preserve external calendar/event IDs, ETags/version and sync token.
• Update/cancel idempotently.
• Minimize residential addresses, Client names and Provider commercial detail in external descriptions.
• External edits cannot complete Project gates, approvals or Work Orders.
• Disconnection preserves native Registry events and marks external state unknown.

18.5 Google Sheets

Purpose: migration, Item/budget import, controlled refresh and exports.

Launch modes:

• one-time import;
• refresh with difference preview;
• governed one-way source sync; and
• export of a selected authorized view.

Requirements:

• file/sheet picker with narrow Drive/Sheets scope;
• worksheet, header and range selection;
• reusable field mapping;
• data-type, currency, date and required-field validation;
• row identity and duplicate strategy;
• room/category/Project matching;
• formula result capture with source indication;
• preview before commit;
• immutable import job and row results;
• rollback that protects later user changes; and
• no silent two-way overwrite at launch.

18.6 Stripe

Purpose: Client payments, refunds/disputes and approved Provider/marketplace funds flow under Spec 06.

• Platform or approved Workspace configuration according to the final legal funds-flow model.
• The Registry stores Stripe identifiers and safe status, never raw card data.
• Payment Intent/Checkout creation originates from a canonical Invoice/payment request.
• Use idempotency keys for external create/refund actions.
• Verified webhooks are authoritative for processor state.
• Browser redirect is presentation only.
• Duplicate/out-of-order events are safe.
• Amount, currency, customer and Invoice relationship are revalidated before applying state.
• Disputes, refunds and payout exceptions create attention/reconciliation.
• Provider payout remains distinct from Client receipt.

18.7 QuickBooks Online

Purpose: synchronize accounting objects while preserving Project operations in the Registry.

Objects:

• Customers;
• Vendors;
• Products/services;
• chart-of-account/category mappings;
• tax codes;
• invoices and credit notes;
• payments; and
• class/location where configured.

Requirements:

• Workspace-managed OAuth connection to one company/realm;
• realm identity shown before activation;
• mapping version/effective date;
• external reference and sync token/version;
• create/update conflict detection;
• accounting close/lock-date awareness;
• no default account used silently when mapping is missing;
• posted financial conflicts require authorized reconciliation; and
• disconnect preserves Registry commercial lineage and marks ledger sync stale.

18.8 Approved Vendor and Product APIs

Purpose: bring products, trade pricing, availability, samples, orders, shipments and ETAs into Project Items and procurement.

Connector adapters normalize:

• Vendor and product identifiers;
• SKU/variant/options;
• media and documents;
• dimensions/material/finish;
• list/trade price and currency;
• availability/lead time;
• minimums and order rules;
• order acknowledgement;
• shipment/tracking; and
• observed-at/freshness.

Price and availability are observations, not guarantees. Approved proposals/POs retain immutable commercial snapshots. A refreshed catalogue never rewrites an approved historical price without a change workflow.

Shopify-based Vendors may use an approved API adapter. The platform remains Vendor-neutral and supports non-Shopify Providers.

18.9 Carrier and Tracking APIs

• Normalize tracking number, carrier, shipment, packages, scan events, ETA and exception.
• Match only to known PO/shipment references.
• Do not treat “delivered” as warehouse condition acceptance.
• Storage receiving remains a separate human/evidence workflow.
• ETA changes can update Project attention/calendar through governed automation.

18.10 Website Lead Plugin

Purpose: allow Designer and Registry websites to create qualified Pipeline Records.

• Hosted embed or lightweight script with brand/field configuration.
• Public form definition retrieved by opaque publishable form ID.
• Domain allowlist, CAPTCHA/risk control and rate limits.
• No Supabase secret or service credential in the embed.
• Server validates form version, allowed fields and Workspace routing.
• Honeypot/risk signals stored separately from customer content.
• Duplicate detection by normalized contact/project evidence.
• Consent and marketing preferences captured explicitly.
• Successful submission returns an opaque receipt, not internal record IDs.
• Creates a canonical ingestion event and Pipeline Record through the same form engine as Spec 09.

19. API and Webhook Platform

19.1 Internal connector commands

GET    /api/integrations/connectors
GET    /api/integrations/connections
POST   /api/integrations/:connector/connect-intent
GET    /api/integrations/:connector/callback
PATCH  /api/integrations/connections/:id
POST   /api/integrations/connections/:id/test
POST   /api/integrations/connections/:id/reconnect
POST   /api/integrations/connections/:id/disconnect
POST   /api/integrations/sync-profiles/:id/run
POST   /api/integrations/sync-jobs/:id/cancel
GET    /api/integrations/sync-jobs/:id
GET    /api/integrations/reconciliation-cases
POST   /api/integrations/reconciliation-cases/:id/resolve

19.2 Provider webhooks

POST /api/webhooks/resend
POST /api/webhooks/twilio
POST /api/webhooks/stripe
POST /api/webhooks/google/:subscriptionType
POST /api/webhooks/vendor/:connectorKey
POST /api/webhooks/carrier/:connectorKey

19.3 Public lead ingestion

GET  /api/public/forms/:publicId
POST /api/public/forms/:publicId/submissions

19.4 External developer API

Future approved API clients use scoped credentials, explicit Workspace grants, versioned resources, rate limits, idempotency and audit. API credentials cannot impersonate arbitrary users or bypass Project/field permissions.

20. Data Model

20.1 connector_definitions

• stable key/version;
• category, display metadata and status;
• ownership/auth methods;
• capability/object declarations;
• configuration and scope schemas;
• webhook/event definitions; and
• feature maturity/environment availability.

20.2 connected_accounts

• connector definition/version;
• owner type and owner ID;
• external tenant/account ID and masked label;
• state, granted scopes and capabilities;
• connected/last verified/disabled timestamps;
• created by and current administrator; and
• no raw credential fields.

20.3 connection_grants

Protected server-only schema:

• connected account;
• credential type;
• encrypted payload reference;
• encryption key version;
• provider expiry/refresh metadata;
• rotation and revocation timestamps; and
• last server use.

No direct anon or authenticated access.

20.4 sync_profiles

• connection, Workspace and optional Project;
• direction/mode;
• object types and filters;
• mapping version;
• schedule and conflict policy;
• active/paused state; and
• last successful checkpoint.

20.5 sync_jobs and sync_job_items

• requested source/actor;
• state and idempotency key;
• cursor/checkpoint;
• totals created/updated/skipped/warned/failed;
• safe error summary;
• start/finish/cancel timestamps; and
• item-level result/provenance reference.

20.6 integration_outbox

• domain event/command key;
• aggregate and Workspace;
• connector operation;
• idempotency key;
• safe payload reference;
• state, attempts and available time; and
• correlation/causation IDs.

20.7 provider_event_inbox

• connector and environment;
• provider event/dedup key;
• signature verification result;
• connected-account resolution;
• occurred/received/processed time;
• processing state; and
• protected payload reference.

20.8 external_object_references

• connection;
• canonical record type/ID;
• external type/ID/parent;
• provider version/etag;
• last observed/synced state; and
• unique constraints preventing ambiguous active links.

20.9 mapping_profiles and mapping_versions

• owner/scope;
• external/canonical object type;
• field and enum rules;
• transforms and validation;
• published version/effective time; and
• author/approver.

20.10 reconciliation_cases

• case type, severity and state;
• Workspace/Project/connection;
• canonical/external references;
• safe comparison snapshot;
• assigned owner and due time;
• resolution type/actor/time; and
• audit correlation.

20.11 integration_health_snapshots

• connection/profile;
• observed state;
• cursor age, webhook age and queue lag;
• last success/failure;
• user impact; and
• collected time.

20.12 Constraints and indexes

• unique provider-event dedup key per connector/environment;
• unique active external object reference per connection/type/ID;
• unique outbound idempotency key per connector operation;
• connection owner foreign-key integrity;
• indexes for due outbox work, sync state, reconciliation state and health status;
• check constraints for lifecycle timestamps; and
• no cascade that deletes business records when a connection is removed.

21. Supabase Architecture

21.1 Database

Postgres stores connection metadata, mappings, outbox, event inbox, jobs, references, reconciliation and audit. Sensitive grant material lives in a protected schema/storage mechanism unavailable to ordinary Data API roles.

21.2 Data API and RLS

• Newly created tables are not assumed to be exposed automatically.
• Explicit grants and RLS are separate controls.
• Every exposed table has RLS with Workspace/Membership predicates.
• TO authenticated alone is insufficient.
• Update policies include USING and WITH CHECK.
• Integration views use security-invoker behavior or remain unexposed.
• Secret/grant/outbox raw-payload tables are server-only.

21.3 Queues

Use durable basic queues for integration work after confirming current production availability. Do not expose queue APIs or underlying queue tables to browser clients. Consumers use trusted server credentials and implement idempotency regardless of queue delivery claims.

Suggested queues:

• integration-commands;
• integration-webhooks;
• integration-sync;
• integration-notifications;
• integration-reconciliation; and
• connector-specific high-volume queues only when isolation is justified.

21.4 Edge Functions and workers

Short signed webhook ingestion and authenticated orchestration may use Edge Functions. Long or high-volume sync processing uses durable queue consumers and checkpointed work. Function wall-clock lifetime is not treated as a workflow guarantee.

21.5 Schedules

Cron/scheduling enqueues health checks, incremental sync, subscription renewal and retry release. Schedules have environment ownership, monitoring and concurrency limits.

21.6 Storage

Protected raw payloads, imports and provider files use private buckets with short-lived authorized access. Storage paths are not authorization. RLS and server commands enforce access.

21.7 Service keys

Publishable keys may appear in the frontend with RLS. Secret/service-role keys remain server-only and are used narrowly. Integration workers must not serialize privileged clients or credentials into queue payloads.

22. Activity, Notifications and Automation

Every meaningful integration transition writes Activity and, where attention is required, a Notification Builder event.

Required event keys include:

integration.connected
integration.connection_action_required
integration.permission_changed
integration.degraded
integration.disconnected
integration.sync_started
integration.sync_completed
integration.sync_completed_with_warnings
integration.sync_failed
integration.sync_delayed
integration.reconciliation_required
integration.reconciliation_assigned
integration.reconciliation_resolved
integration.webhook_verification_failed
integration.dead_letter_created
integration.rate_limit_active
integration.credential_rotation_required
integration.subscription_renewal_failed

Templates can be edited within allowed copy/branding controls. Recipient rules, security recipients, secret redaction and mandatory security behavior remain code-governed.

Pipeline automation may request an approved connector action but cannot provide raw credentials, expand scopes or override integration permissions.

23. Observability and Operations

23.1 Dashboards

• connections by state/connector;
• webhook verification and processing rate;
• queue depth/oldest message;
• job duration and success rate;
• provider latency/rate limiting;
• sync freshness;
• retries/dead letters;
• reconciliation backlog;
• token refresh/reconnect failures; and
• affected Workspaces/Projects.

23.2 Correlation

Trace business command -> outbox -> queue message -> provider request -> provider event -> canonical update using safe correlation and causation IDs.

23.3 Logging

Structured logs include connector, environment, safe connection ID, operation, outcome, duration, attempt and error class. Redaction is automatic and tested.

23.4 Support tools

Authorized support can run connection tests, inspect safe request metadata, compare sync cursors, retry eligible work and export a redacted diagnostic bundle. Support cannot reveal tokens or silently change mappings.

24. Security, Privacy and Compliance

• Least OAuth scope and incremental consent.
• Exact redirect/callback allowlists by environment.
• Signed, expiring OAuth state/connection intents.
• Webhook signature, timestamp and replay protection.
• Encryption in transit and at rest.
• Server-only credential decryption.
• Workspace/Membership authorization at connection and execution time.
• Recent authentication for sensitive connection and disconnect actions.
• RLS and least grants for all exposed integration metadata.
• Payload minimization based on record and field permissions.
• Secret scanning in repository, logs and built assets.
• Data retention and disconnect/deletion behavior per connector.
• No production bodies/payloads copied into test environments.
• Provider terms, branding and API usage policies documented.
• Financial providers receive enhanced audit and separation of duties.

25. Failure and Edge Cases

Test at minimum:

1. OAuth callback state mismatch.
2. User completes callback after losing Workspace permission.
3. Provider returns no refresh token.
4. Granted scopes differ from requested scopes.
5. Token refresh races across workers.
6. User revokes provider access externally.
7. Connection owner leaves the Workspace.
8. External tenant changes or user selects the wrong company.
9. Webhook arrives twice, late or out of order.
10. Webhook signature is valid but external object belongs to another tenant.
11. Queue consumer crashes after external success but before acknowledgement.
12. Provider returns 429 with and without Retry-After.
13. Circuit breaker opens during a Project-critical workflow.
14. Mapping version changes during a running job.
15. Sheet headers/rows move between refreshes.
16. Calendar event is deleted externally.
17. Gmail message arrives through push and forwarding.
18. Stripe redirect succeeds before webhook.
19. Stripe webhook amount/currency mismatches the Invoice.
20. QuickBooks record is locked/closed/deleted.
21. Vendor price changes after Client approval.
22. Carrier marks delivery but Storage flags damage.
23. Website form is spammed or embedded on an unapproved domain.
24. Disconnect occurs with queued outbound commands.
25. Reconnect selects a different external tenant.
26. Data export includes a field the user cannot view.
27. Dead-letter retry occurs after underlying record was cancelled.
28. Production webhook is delivered to preview environment.

26. User Stories

26.1 Designer

• I can connect my business Gmail without importing unrelated personal mail.
• I can publish selected Project dates to Google Calendar.
• I can import my existing Item spreadsheet with a safe preview.
• I can see when a sync is stale or needs my action.

26.2 Provider

• I can connect tools relevant to my category without exposing my credentials.
• My Vendor/shipment updates flow into only the authorized Jobs and Projects.
• I can use QuickBooks or payment integrations while the Registry retains Work Order lineage.

26.3 Workspace Owner

• I can see every Workspace connection, owner, granted scope and health state.
• I can delegate integration management without exposing secrets.
• I can disconnect safely and understand the impact.

26.4 Finance user

• I can see whether an Invoice is synchronized, paid, conflicted or waiting for reconciliation.
• I can resolve an accounting mapping without changing Project history.

26.5 Registry operator

• I can monitor systemic connector health and affected Workspaces.
• I can support users using redacted diagnostics and audited repair actions.

26.6 Client

• I can pay through an approved Stripe flow and see authoritative processing status.
• I do not see internal connector or Provider commercial information.

26.7 Website visitor

• I can submit a secure branded enquiry and receive confirmation without learning internal IDs.

27. Acceptance Criteria

27.1 Shared framework

• Every launch connector uses the shared Connected Account, job, event, error and health models.
• No connector stores credentials in client-readable rows or bundles.
• Connection owner and Workspace scope are explicit.
• Disconnect/reconnect are audited and preserve canonical history.

27.2 Reliability

• Outbound side effects originate from committed outbox commands.
• Worker crash/retry cannot duplicate external business effects.
• Webhook delivery is verified, deduplicated and processed asynchronously.
• Long syncs checkpoint and resume.
• Retry, circuit-breaker and dead-letter behavior are tested.

27.3 Data quality

• External references are unique and traceable.
• Mappings are versioned.
• Imported/synchronized values preserve provenance and freshness.
• Unknown or conflicting values enter reconciliation rather than silent overwrite.

27.4 Permissions

• Connecting an account requires the correct capability.
• Execution rechecks current Membership/capability.
• Field restrictions apply to outbound payloads and exports.
• Cross-Workspace integration access tests pass.

27.5 Connector-specific

• Resend delivery/bounce/complaint states update from verified events.
• Twilio SMS/Voice respects consent, number ownership and signed events.
• Gmail uses separate least-scope consent and incremental sync.
• Calendar publication is selective and conflict-aware.
• Sheets import provides mapping, preview, provenance and safe rollback.
• Stripe state comes from verified events/reconciliation.
• QuickBooks conflicts never use blind last-write-wins.
• Vendor product price/availability display source and observation time.
• Website plugin rejects invalid origin/risk and creates one canonical submission.

27.6 Security

• OAuth state, redirect and callback tests pass.
• Tokens/secrets are absent from logs, analytics and client artifacts.
• Webhook forgery/replay tests pass.
• RLS and explicit grants protect all exposed integration tables.
• Queue access is server-only.
• Sensitive support actions are authorized and audited.

28. Migration from Existing Module Integrations

28.1 Inventory

Identify every direct Resend, Twilio, Google, Stripe, QuickBooks, Vendor API and webhook call in the CRM. Record current credential source, retry behavior, idempotency, data owner and affected module.

28.2 Wrap before replacing

Introduce shared connector interfaces around working calls. Preserve existing behavior while routing new activity, command, delivery and error state into the shared models.

28.3 Backfill

• Create Connected Account metadata for approved current configurations.
• Backfill external object references from existing provider IDs.
• Backfill delivery/payment/sync events where reliable evidence exists.
• Do not invent successful sync history.
• Flag ambiguous external links for reconciliation.

28.4 Cutover

Use per-connector feature flags. Run shadow observation before enabling outbound writes where possible. Cut over one operation class at a time and retain rollback that does not delete newly captured provider events.

28.5 Retirement

Remove module-specific token tables, unverified webhook routes, ad hoc retries and direct browser/provider calls after reconciliation and rollback windows close.

29. Implementation Phases

Phase 1 — Shared foundation

• Connector registry and Connected Accounts.
• Ownership/capability model.
• encrypted grant abstraction.
• outbox, provider-event inbox and external references.
• durable server-only queues and worker contract.
• Settings directory and connection health.
• common audit, notification and observability.

Phase 2 — Existing delivery connectors

• Centralize Resend under Notification Delivery.
• Centralize existing Twilio contracts from Communications.
• Verify webhook ingestion, deduplication and delivery state.
• Build shared dead-letter and support tooling.

Phase 3 — Google productivity

• Separate Google business consent from sign-in.
• Gmail scoped mailbox connection.
• Google Calendar selected sync.
• Google Sheets import, refresh preview and export.
• token refresh, subscriptions and reconciliation.

Phase 4 — Payments and accounting

• Stripe payment commands/webhooks/reconciliation.
• QuickBooks connection, mappings and object sync.
• separation of Project obligation, processor state and ledger state.
• finance reconciliation centre and controls.

Phase 5 — Vendor operations

• Connector adapter kit.
• initial approved Vendor/Product integration.
• carrier/tracking adapter.
• source freshness, immutable commercial snapshots and mapping tools.

Phase 6 — Website and developer platform

• secure lead form plugin.
• public form configuration and domain controls.
• approved external API credentials/scopes.
• outbound signed webhooks and developer logs.

Phase 7 — Scale and governance

• connector certification/checklist;
• automated contract tests;
• per-tenant quotas/circuit breakers;
• key rotation drills;
• retention and privacy automation; and
• broader connector catalogue.

Each phase includes migration, security, RLS, accessibility, failure, rate-limit, observability and rollback testing.

30. Launch Decisions Requiring Confirmation

1. Final worker runtime and scheduler for durable queue consumption.
2. Approved encryption/KMS approach for per-connection refresh tokens.
3. Whether Supabase Vault's current maturity is acceptable for any credential class.
4. Gmail launch mode: selected label, full approved mailbox scope or forwarding-first.
5. Google Calendar two-way edit policy.
6. Google Sheets file-picker and refresh schedule.
7. Stripe funds-flow/legal account model and connected-account strategy.
8. QuickBooks objects and direction enabled at launch.
9. First Vendor/Product API and commercial access terms.
10. First carrier/tracking adapters.
11. Website plugin hosting/domain and CAPTCHA provider.
12. Connector-specific retention periods.
13. Reconciliation ownership and SLA by connector.
14. Whether customer-created outbound webhooks launch with the public API.
15. Production secrets, callback domains and environment separation.

31. Current Supabase Implementation Notes

Implementation must recheck the Supabase changelog and official documentation when coding. The August 2026 review reflected:

• newly created tables may require explicit Data API exposure/grants in addition to RLS;
• Supabase Queues is Postgres-native and pull-based;
• queue client exposure is optional and should remain disabled for this architecture;
• Edge Function background work remains bounded by function resource/lifetime constraints;
• database webhooks are asynchronous convenience wrappers around triggers/pg_net and do not replace the durable application outbox;
• Supabase Auth can return Google provider tokens, but the application must securely persist and refresh business-integration tokens itself; and
• server secrets and secret/service-role keys must never be exposed to frontend clients.

Official references:

• Supabase Changelog
• Supabase Queues
• Consuming Queue Messages with Edge Functions
• Edge Function Background Tasks
• Edge Function Secrets
• Securing Supabase Data
• Database Webhooks
• Google Authentication and Provider Tokens

32. Definition of Done

Spec 18 is implemented when:

• every launch connector uses the shared integration framework;
• Connected Account ownership, scope and health are visible;
• provider credentials remain encrypted and server-only;
• OAuth, reconnect and disconnect flows are safe and recoverable;
• the outbox/queue/worker path is durable, idempotent and observable;
• webhooks are verified, deduplicated and replay-resistant;
• synchronization is checkpointed and conflicts are governed;
• provenance and freshness are available for imported/synchronized values;
• reconciliation is a first-class shared workflow;
• permissions and field restrictions apply to every inbound/outbound action;
• Resend, Twilio, Gmail, Calendar, Sheets, Stripe, QuickBooks, Vendor APIs, tracking and website lead capture meet their connector requirements;
• RLS, explicit grants, Storage and queue isolation tests pass;
• connection failures create understandable attention, fallback and support paths;
• current direct integrations migrate without losing business or external-reference history; and
• security, accessibility, privacy, reliability, load, provider-contract and rollback testing passes.

The finished system allows The Design Registry to fit naturally into how Designers and Providers already work while ensuring that Projects—not disconnected inboxes, spreadsheets or accounting tools—remain the operational center of the network.

Live-product correction contract — Data Reconciliation

The current Data Reconciliation surface establishes a safe principle: scans never merge or delete. Production implementation must preserve and deepen that boundary.

• Every run stores immutable inputs, rule version, started/completed timestamps, actor, counts and status.
• Every finding stores category, severity, affected canonical records, evidence, detection rule and current review state.
• A scan is always read-only. Resolution is a separate permission-checked command with preview, idempotency key and audit.
• Duplicate identity, Workspace ownership, Membership, cross-Workspace Team, attribution and passive-Entity corrections require purpose-specific resolution flows rather than one generic merge.
• Ignored requires a reason and may reopen if material evidence changes.
• Sensitive merges and ownership changes require explicit confirmation, recent authentication and a rollback or compensating-action plan.
• Constraint readiness may block a migration or release but must never auto-correct production data.
• Run and finding history must remain searchable after resolution.

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

Current-product review gap closure register

Generated: August 4, 2026
Owning future specification: 18
Mapped current-product profiles: 1
Recorded review gaps: 3

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 — Data Reconciliation

Current-product profile: data-reconciliation
Observed route: /admin/settings/reconciliation
Evidence confidence: Verified

Review gaps

• No completed run.
• No evidence drawer, resolution preview, approval or rollback was reviewed.
• No run history or rules version is visible.

Required future closure

• Add immutable run history and rules versions.
• Add evidence-backed finding profiles and safe commands.
• Connect blocking constraints to migration readiness without auto-correction.

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 -->