The Design Registry

Communications, Unified Inbox & Client Collaboration

Version: 1.0
Prepared: August 2026
Status: Engineering and product source of truth

1. Executive Summary

Communications is the relationship layer of The Design Registry. It brings email, in-app messaging, internal notes, SMS, business calling, voicemail, recordings, transcripts and record context into one dependable workspace so Designers can run their businesses without losing the inbox experience on which they already rely.

The product is not a basic chat widget and it is not a replacement email provider. It is an Intercom-inspired shared communications workspace built around design Projects. It must know who is speaking, which Workspace they represent, which Client, Project, Provider, Offer, Proposal, Work Order, Invoice, item or application the conversation concerns, and what each participant is permitted to see.

The primary supported relationships are:

• Design Registry administrator to Designer;
• Design Registry administrator to Client;
• Design Registry administrator to Provider;
• Designer to Client; and
• Designer to Provider.

Provider-to-Client or Provider-to-Provider communication is not enabled by default. It may be opened for a defined Project purpose, such as delivery coordination, only through explicit policy and scoped access.

Email is a first-class channel. Designers may connect a Gmail mailbox, use an approved Workspace sender identity or route designated messages into the platform. Incoming email is normalized, deduplicated, threaded and associated with the correct business records using deterministic identifiers first and permission-aware AI suggestions second. Ambiguous email enters a reconciliation queue rather than being silently attached to the wrong Project.

In-app conversations use the same canonical Conversation and Message model. A participant can reply in the portal or by email without creating a duplicate history. Every message retains its channel, sender identity, delivery state and audience. Internal notes are physically and logically separated from external messages so they can never be sent to a Client or Provider by mistake. Notes support @mentions, structured record tags, attachments, task creation and a complete version history.

The architecture follows build once, reuse everywhere. One inbox, composer, timeline, routing engine, email-ingestion service, search system, attachment system and audit model serve Registry, Designer, Provider and Client Workspaces. The interface and available actions change through permissions, relationship scope and Workspace type—not separate implementations.

This specification does not replace the Notification Builder. Human two-way conversations belong to Communications. Event-triggered notifications and transactional templates belong to the Notification Builder defined in Specification 03. Both may appear in an audience-safe timeline and share delivery infrastructure, but their ownership, reply behavior and audit semantics remain distinct.

2. Product Outcomes

2.1 Designer outcomes

• Work from one inbox without losing the familiarity or reliability of Gmail.
• Understand immediately which Client, Project and Provider an email concerns.
• Keep Client and Provider conversations separate while viewing the complete Project history.
• Collaborate privately through notes and @mentions without forwarding email chains.
• Turn commitments in messages into Tasks, calendar events and decisions.
• Find past decisions, attachments, pricing discussions and unanswered questions quickly.
• Send professional, branded email from an authorized identity.
• Know when a message was delivered, replied to, reassigned, snoozed or closed.

2.2 Client outcomes

• Communicate through email or the Client portal without learning a new process.
• See a clear, elegant Project conversation history appropriate to the Client.
• Receive timely requests, approvals and updates without internal operational noise.
• Know which person or team is responding.
• Keep attachments and decisions connected to the Project.

2.3 Provider outcomes

• Receive clear Project, Offer and Work Order communication in the Provider portal or email.
• Reply without exposing unrelated internal Provider operations.
• See the scope, items, dates and records relevant to the conversation.
• Collaborate with the Designer after authorization without seeing hidden Registry or Client information.
• Preserve accepted work communication as part of the operational Job record.

2.4 Registry outcomes

• Coordinate Designers, Clients and Providers without hidden side channels becoming the only record.
• Maintain service visibility appropriate to the Registry's role and permissions.
• Route conversations to the right market, team and record.
• Identify stalled replies, communication risk and service exceptions.
• Preserve a defensible audit trail without exposing private mailbox content unrelated to the platform.

3. Goals, Measures and Non-Goals

3.1 Goals

1. Create one permission-aware inbox and conversation model for every Workspace type.
2. Make email as capable as the in-app experience while preserving Gmail interoperability.
3. Associate communications with the correct records using explainable correlation.
4. Make internal collaboration safe, obvious and impossible to leak accidentally.
5. Support shared ownership, routing, queues, tags, SLAs and search.
6. Turn communication into operational work without duplicating Projects, Tasks or commercial records.
7. Preserve delivery, threading, consent, retention and audit state.
8. Provide a scalable foundation for SMS, calls and AI assistance.

3.2 Success measures

• Percentage of inbound messages automatically linked to the correct primary context at high confidence.
• Percentage of ambiguous messages resolved from the reconciliation queue within one business day.
• Median first-response and resolution time by relationship and Workspace.
• Unanswered Client and Provider conversation rate.
• Percentage of Project communications visible from the Project without duplicate records.
• Email delivery, bounce, complaint and authentication rates.
• Connected-mailbox synchronization health and lag.
• Percentage of internal notes with no external-leak incidents; the required target is 100% safe separation.
• User-rated usefulness of Project association and AI suggestions.
• Reduction in manual forwarding, searching and repeated status questions.

3.3 Non-goals

• Rebuilding Gmail, calendar or full personal email management.
• Importing every personal email in a connected account by default.
• Giving the Registry unrestricted access to a Designer's mailbox.
• Automatically sending AI-written replies without human review.
• Replacing Proposals, Work Orders, Invoices, Tasks or Project decisions with free-form messages.
• Allowing a public participant directory or unrestricted participant-to-participant chat.
• Using read receipts as guaranteed proof that a human read or understood a message.
• Recording calls or processing protected content without consent and policy.

4. Product Principles

4.1 Email-first, not email-only

Designers already live in email. The platform must improve that workflow rather than forcing every participant into chat. Email and portal replies converge on one conversation, but each message retains its transport and delivery evidence.

4.2 Project context is canonical

A conversation references Projects and related records; it does not copy or redefine them. Messages shown in several record tabs are projections of the same canonical Conversation.

4.3 Private by construction

Internal notes use a separate server-enforced data path from external messages. A visual color alone is not a safety boundary. External APIs and send workers cannot accept a Note ID as a sendable Message.

4.4 Progressive disclosure

Participants see only the information required for the active relationship. A Provider may receive an Offer conversation before award and a broader Job conversation after award. Access does not imply visibility into competing Providers, Client personal details or hidden margins.

4.5 Deterministic before intelligent

Provider thread IDs, email headers, reply aliases and existing Conversation membership outrank AI inference. AI helps classify ambiguous content; it does not override permissions or silently attach sensitive email.

4.6 One history, many views

Inbox, Project, Client, Provider, Offer and Work Order views filter the same durable history. Edits, links, tags, assignments and delivery events remain consistent everywhere.

4.7 Human accountability

Messages have a sender, identity, Workspace, audience and provenance. AI can draft and summarize, but an authorized person approves consequential external communication.

5. Scope and Ownership Boundaries

5.1 Current product correction contract

The global Messages navigation item is currently disabled and explicitly labelled Coming soon. This is the correct availability treatment until the Unified Inbox has a real route and end-to-end channel behavior. Record-level Communication tabs are partial contextual projections and must not be described as the global inbox.

Release requirements for enabling Messages navigation:

• a working Workspace-scoped inbox route;
• Conversation list, assignment, status, priority, tags, SLA and unread state;
• participant-visible Message and internal Note composer modes with a hard safety boundary;
• Project, Client, Provider, Task and commercial-record context;
• deterministic email/SMS/call correlation and an unmatched-item reconciliation queue;
• channel health, delivery failure and retry state;
• permission-safe search, attachments, mentions and Task creation;
• verified audience projections for Registry, Designer Studio and Provider Workspaces.

The Coming soon badge must remain on every disabled Messages entry point until these requirements are met.

System notifications must not masquerade as a human reply. Human messages, automated messages, delivery events, notes and activity events are visibly typed.

6. Communication Relationship Model

6.1 Supported default relationships

6.2 Relationship authorization

Creating or joining a Conversation requires both:

• a capability granted by Specification 08; and
• a valid relationship scope, such as a Project assignment, active Client relationship, Provider Offer or Registry administrative purpose.

Removing a relationship immediately prevents new replies and Realtime delivery. Historical access follows the governing Project, contract, retention and legal policy.

6.3 Multi-party conversations

Multi-party threads are supported only when the owner intentionally adds participants and the context policy permits it. The composer previews all external recipients and their organizations before send. BCC is not supported for in-app participants and must not be used to hide platform participants from one another.

7. Core Domain Concepts

7.1 Inbox

An Inbox is a Workspace queue with routing, membership, sender identities, business hours, SLA policies and saved views. Examples include Client Projects, Provider Coordination, Registry Applications and Billing.

7.2 Conversation

A Conversation is the durable participant and context container. It has one primary context, optional related-record links, participants, current owner/team, status, priority, tags and ordered timeline.

7.3 Message

A Message is a participant-visible communication sent through email, in-app or SMS. It retains content versions, sender identity, recipients, transport metadata, attachments and delivery events.

7.4 Internal Note

An Internal Note is private Workspace collaboration. It is not a Message, has no external recipients and cannot enter an external delivery queue. It may mention authorized Users/Teams and tag permitted records.

7.5 Notification

A Notification is an event-driven attention signal rendered by the Notification Builder. It may link to a Conversation but is not automatically a participant reply.

7.6 Record link

A Record Link connects one Conversation to a Project, Client, Provider, Offer, Proposal, Work Order, Invoice, application, Pipeline Record, Task, item, Purchase Order or other supported record. One link is primary; others express related context.

7.7 Assignment

Assignment identifies the responsible Inbox, Team and User. It does not change message authorship or Project assignment.

7.8 Tag

A Tag is Workspace-governed classification such as Awaiting Client, Specification Question, Damage, Urgent or Billing. Structured record mentions are not ordinary free-form tags.

8. Unified Inbox Information Architecture

Communications
├── My Inbox
├── Team Inboxes
├── Unassigned
├── Mentions
├── Waiting on Us
├── Waiting on External
├── Snoozed
├── Closed
├── Reconciliation
└── Saved Views

The three-pane desktop experience contains:

1. navigation and queue counts;
2. conversation list with participant, subject, Project, status, owner, tags and last activity; and
3. conversation timeline, composer and contextual record panel.

Mobile uses a progressive list-to-thread-to-context flow. No critical action depends on hover.

8.1 Conversation statuses

• Open
• Pending / waiting on external participant
• Snoozed until a defined time or event
• Closed
• Spam or blocked
• Reconciliation required

Closing never deletes history. A new external reply reopens the Conversation unless policy routes it elsewhere.

8.2 Inbox list controls

• Full-text and participant search
• Relationship, Workspace type and Project filters
• Channel, owner, Team, status, priority and tag filters
• Unread, unanswered, SLA risk and attachment filters
• Saved private or Team views
• Bulk assign, tag, close, snooze and mark read
• Configurable columns and density

8.3 Collision and presence

The thread indicates when another authorized teammate is viewing or composing. Presence is advisory and transient. It never replaces server-side optimistic concurrency, send idempotency or durable audit.

9. Conversation Experience

9.1 Header

• Subject and relationship type
• External participants and represented Workspaces
• Primary Project or record
• Channel summary
• Current owner, Team, status, priority, tags and SLA state
• Actions: assign, move, snooze, close, link record, create Task, report spam

9.2 Timeline

The timeline interleaves audience-safe events while preserving type:

• inbound and outbound Messages;
• internal Notes;
• attachments;
• participant and assignment changes;
• delivery failures;
• linked Task, approval and decision events;
• selected Notification events; and
• record-link corrections.

External participants never receive or query internal Notes, hidden assignment events, confidential tags or internal automation details.

9.3 Context panel

The right panel can show, subject to permission:

• Client identity and preferred contact details;
• Project phase, health, next milestone and address masking;
• Provider type, Offer/Work Order state and assigned contacts;
• open Tasks and upcoming calendar events;
• relevant items, POs, shipments or receiving exceptions;
• financial summary only when separately permitted;
• recent related Conversations; and
• suggested record links with confidence and evidence.

9.4 Composer modes

• Reply
• Reply all
• New message
• Internal note
• Forward by email
• Saved reply
• SMS when eligible

The active mode is explicit in the composer header and submit label. Keyboard shortcuts cannot change Reply to Note or Note to Reply without visible confirmation.

9.5 Send actions

• Send
• Send and close
• Send and keep pending
• Schedule send
• Save draft
• Cancel draft

Scheduled messages are re-authorized immediately before delivery. Removed access, invalid consent or closed relationships cancel the send and create a visible exception.

10. Internal Notes, Mentions and Tagging

10.1 Note behavior

Notes support rich text, links, emoji, attachments, structured mentions and AI writing assistance. A Note records author, Membership, Workspace, creation time and version history.

Notes may be edited by authorized users, but prior versions remain available in audit history. Deletion is limited to governed redaction workflows; normal users do not erase operational history.

10.2 Hard safety boundary

• Notes live in a separate table from Messages.
• External delivery workers accept only sendable Message records.
• Notes have no recipient rows, transport state or provider message ID.
• API serializers exclude Notes unless the caller has the internal-note capability.
• Client and Provider RLS policies deny Note access even when they belong to the same Conversation.
• Copying a Note into a reply creates a new draft and requires human review.

10.3 @mentions

Users may mention authorized teammates, Teams and role-based audiences. Mentions create Notification Builder events such as communication.note_mentioned. A mention cannot grant access; the recipient must already be permitted to view the Conversation and Note.

10.4 Structured record tagging

The composer can tag a Project, Client, Provider, Offer, Work Order, item, PO, Task or calendar event from a permission-filtered picker. Stored mentions use stable record IDs and display snapshots. Renaming a record updates the rendered reference without altering the original Note text history.

10.5 Convert to work

An authorized user can create a linked Task, calendar event, Project decision, issue or follow-up from selected Message/Note text. The created record keeps a source reference. The system never treats an informal message as a commercial approval when the governing workflow requires a formal Proposal, Work Order or approval record.

11. Email Strategy

11.1 Channel roles

Recommended production boundary:

• Connected Gmail sends and receives person-to-person business email as the authenticated user or approved shared mailbox.
• Resend sends platform notifications, invitations, security messages and approved Workspace-managed transactional email.
• The canonical Communications service normalizes both into the same timeline.

This separation preserves user trust, deliverability and sender authenticity while keeping system delivery observable.

11.2 Connection modes

A Workspace may enable one or more modes:

1. Connected individual Gmail mailbox with explicit OAuth consent.
2. Connected shared Google Workspace mailbox or delegated address where supported.
3. Designated Gmail label synchronization, recommended when users do not want broad mailbox ingestion.
4. Project forwarding/dropbox address.
5. Managed Workspace sender identity through the platform.

The default onboarding should recommend the least-permissive mode that meets the Workspace's needs. The platform must explain exactly which messages and metadata are accessed.

11.3 Privacy boundary

The Design Registry does not ingest an entire personal mailbox by default. A connection policy defines included labels, sender/recipient domains, aliases, Project tokens and manual imports. Users can preview scope before enabling sync.

Registry administrators cannot search a Designer's unrelated mailbox. Registry access is limited to platform Conversations that the Registry is a participant in or is explicitly permitted to oversee.

11.4 Sender identity

Before send, the composer shows:

• From identity and represented Workspace;
• reply-to behavior;
• all external recipients;
• associated primary record; and
• whether the message will be sent through Gmail or a managed platform identity.

Sender identities require verification and Workspace approval. Display-name customization cannot impersonate another Workspace or hide the true sender.

11.5 Signatures and saved replies

Users may configure personal and Workspace signatures subject to branding policy. Saved Replies are human-selected reusable content, separate from Notification Builder templates. Saved Replies support variables, validation and Team ownership but do not send automatically.

12. Email Ingestion and Threading

12.1 Inbound pipeline

Provider push/webhook or incremental sync
→ authenticate source and store minimal receipt
→ deduplicate external event and message IDs
→ fetch permitted message content
→ normalize headers, addresses, body and attachments
→ inspect content and attachment safety
→ resolve sender, recipients and represented Workspaces
→ match existing Conversation
→ evaluate primary and related record links
→ persist Message and delivery evidence transactionally
→ enqueue indexing, notifications and AI assistance
→ broadcast permitted new-message identifier

12.2 Threading evidence order

1. Existing provider thread ID within the same mailbox connection.
2. RFC Message-ID, In-Reply-To and References headers.
3. Signed platform reply alias or correlation token.
4. Existing Conversation participant set and sender identity.
5. Explicit Project or record token in an approved alias/subject.
6. High-confidence record correlation.
7. Human reconciliation.

Subject similarity alone is insufficient to merge sensitive conversations.

12.3 Deduplication

The same email may arrive through Gmail sync, a forwarding address and a provider webhook. Deduplication uses provider IDs, normalized Message-ID, mailbox connection and content fingerprints. One canonical Message can retain multiple ingestion-source references.

12.4 Replies sent outside the platform

When an authorized connected Gmail user replies in Gmail, the outbound sync records the reply in the canonical Conversation if it meets the connection policy. It is labeled as sent externally through Gmail, not as a platform-composed Message.

12.5 Attachments

Attachments are scanned, typed, size-limited and stored through the shared Files service. Inline images retain content-ID relationships. Executables and unsafe archives are blocked or quarantined. Access is inherited from both the Message audience and linked record policy.

13. Project and Record Correlation

13.1 Primary context

Every Conversation has at most one primary context at a time. Common primary contexts are Project, Project Opportunity, Provider Application, Offer, Work Order or support case. A Conversation may have several related links without being duplicated.

13.2 Correlation signals

• Signed reply alias or platform correlation token
• Existing Conversation and provider thread
• Explicit Project/Offer/Work Order reference
• Sender/recipient contact relationship
• Active Project assignments
• Recent related activity
• Participant organization and market
• Subject and body entities
• Attachment filename or embedded PO number
• AI classification confidence and cited evidence

13.3 Confidence policy

Highly sensitive categories, conflicting Clients, overlapping Project participants or financial messages require stricter thresholds.

13.4 Reconciliation experience

The reconciliation queue shows the email, permitted metadata, possible Conversations/records, reasons, confidence and conflicts. An authorized user can:

• link to an existing Conversation;
• create a new Conversation;
• change the primary context;
• add secondary record links;
• mark unrelated/private;
• mark spam; or
• escalate to a Team.

Every correction is audited. Corrections improve future suggestions only through governed features; the system does not silently retrain on private content.

13.5 Moving and unlinking

Moving a Message between Conversations is a privileged correction, not a destructive rewrite. The system preserves original ingestion, previous links, actor and reason. Participants who previously had access must be re-evaluated; caches and search indexes are invalidated immediately.

14. Project Communications

The Project Communication tab displays linked Conversations grouped by Client, Provider, internal Project team and commercial context. It does not store copies.

Required controls:

• Compose Client message
• Compose Provider message from an authorized Work Package, Offer or Job
• Add internal Project Note
• Filter by participant, channel, Project phase, Provider, item and date
• View unanswered and SLA-risk Conversations
• Link or correct a Conversation
• Create Task, event, issue or decision

14.1 Client communication

Designer-to-Client communication defaults to the Project as primary context. Client portal visibility includes only external Messages and published attachments. Internal Project notes, Provider comparisons, hidden economics and Registry operations remain excluded.

14.2 Provider communication

Pre-award Provider communication links to the Requirement, shortlist, Offer or RFP and exposes only authorized scope. After award, operational communication links to the Work Order/Provider Job and Project. The system does not automatically reveal Client direct contact details.

14.3 Item and logistics context

Messages can reference items, Purchase Orders, shipments, receiving records, damage exceptions, delivery routes and installation events. A Storage Provider's condition Note and photos remain operational records; participant-facing communication can link to the resulting exception without exposing internal review.

15. In-App Messaging

15.1 Shared model

In-app Messages use the same Conversation model as email. A Conversation may contain both channels. The timeline labels channel transitions and retains the source of every reply.

15.2 Portal behavior

• Unread counts by Workspace and Inbox
• Conversation list scoped to participant relationships
• Realtime new-message indicators
• Draft persistence
• Attachment upload and preview
• Reply, emoji reaction where permitted and Message link
• Read state as an approximate convenience signal
• Email fallback or notification based on preferences

15.3 Channel bridging

An in-app Message may generate a Notification email with a safe excerpt and reply link. If email reply bridging is enabled, a reply to the signed alias enters the original Conversation. The Notification email itself is not duplicated as a human Message.

15.4 Client experience

The Client portal uses plain language, Project branding and a simplified thread. It does not expose internal queue status, teammate presence, SLA, hidden tags or system routing.

15.5 Provider experience

Provider Conversations appear inside Offers and accepted Jobs as well as the Provider Inbox. The Provider sees only conversations assigned to or shared with its Workspace and authorized users.

16. SMS, Business Calling, Recordings and Transcripts

16.1 SMS

Twilio SMS is available only when:

• the recipient has a valid normalized phone number;
• appropriate consent and jurisdictional requirements are satisfied;
• the message purpose and Workspace policy permit SMS;
• quiet hours and opt-out state are respected; and
• the sender identity is configured.

Inbound and outbound SMS joins an existing Conversation where confidently correlated. STOP/START and provider delivery events are handled centrally. Sensitive detail should be linked securely rather than placed in SMS.

16.2 Product objective for calling

Calling is a first-class channel in the Unified Inbox. A Designer or authorized teammate can buy or port a business number, place and receive calls, route callers, capture voicemail, record with consent, generate a speaker-aware transcript and keep the resulting history with the correct Conversation and Project.

The call experience must support:

• inbound and outbound PSTN calling;
• browser calling through a supported Voice SDK, plus optional forwarding to a verified phone;
• local, national or toll-free business numbers where available;
• Workspace, Inbox, Team or User number assignment;
• business-hours routing, ring groups, queues, extensions and voicemail;
• caller identification from Clients, Designers, Providers and Project contacts;
• Project and record matching before or after answer;
• warm transfer, hold, mute, keypad and participant addition where permitted;
• call status, duration, disposition and follow-up;
• consent-aware dual-channel recording;
• voicemail and call transcription;
• timestamped speaker segments and AI summaries; and
• one durable timeline shared with email and in-app communication.

16.3 Buy or port a business number

Workspace Owners with billing and telephony permission can open Settings → Communications → Phone Numbers and select Get a number.

The purchase flow is:

Choose country/region
→ select local, national or toll-free type
→ search area code, locality or number pattern
→ filter required capabilities: Voice, SMS/MMS where supported
→ review availability, regulatory requirements and pricing
→ select intended Inbox/Team/User and use
→ accept billing, emergency-calling and number-ownership terms
→ complete required identity/regulatory verification
→ purchase through the telephony provider
→ configure inbound routing and outbound caller ID
→ run a call/SMS test
→ activate

Availability, capabilities, documentation requirements and price are fetched from the provider at the time of purchase and are never hard-coded. The confirmation separates recurring number rental, usage rates, taxes and optional recording/transcription charges.

An approved Workspace may also request to port an existing business number. Porting is a tracked operational workflow with ownership evidence, letter of authorization, carrier status, target date, exception handling and temporary routing. The interface must never imply a port is complete until the carrier confirms it.

16.4 Number ownership and lifecycle

Each purchased or ported number becomes a Workspace Phone Number with:

• E.164 number and formatted display;
• country, locality and number type;
• provider/subaccount and external resource ID;
• Voice/SMS/MMS capabilities;
• owning Workspace and billing account;
• assigned Inbox, Team and optional User;
• inbound call flow and outbound caller-ID permissions;
• recording/transcription policy;
• regulatory bundle/status and renewal requirements;
• monthly and usage cost attribution;
• activation, suspension, port and release states; and
• complete lifecycle audit.

One Workspace can hold several numbers, such as a general studio line, Project intake number and procurement line. One number can route to several eligible users, but it has one owning Workspace.

Releasing a number is a destructive commercial action. It requires impact review, Owner confirmation, re-authentication, display of affected routing/templates and a configured cooling period where supported. Numbers are never released automatically for an overdue payment without a visible suspension and recovery workflow. Port-out, ownership at termination and recovery rights must be defined in customer terms.

16.5 Inbound call flow

Call reaches Workspace number
→ validate provider webhook and number state
→ resolve known caller and permitted candidate records
→ apply business hours, holiday and routing policy
→ play required recording/AI disclosure before capture begins
→ ring assigned User/Team or enqueue
→ show caller and likely Project context to eligible agents
→ connect, transfer or route to voicemail
→ persist call legs/status events idempotently
→ finalize recording/transcript when enabled
→ create missed-call/voicemail/follow-up events

The incoming call card shows caller name when known, represented organization, possible Projects, last interaction, number called and routing source. Sensitive Project information is not shown until the answering user is authorized. If several Projects match, the call remains unlinked until the user chooses or reconciliation completes.

16.6 Outbound call flow

Users can call from a Conversation, Client, Designer, Provider, Project, Offer, Work Order or authorized contact. Starting from a record deterministically establishes the initial context. Before dialing, the interface shows:

• destination and contact;
• selected Workspace caller ID;
• Project/record context;
• whether recording and transcription are proposed;
• jurisdiction/consent policy;
• cost or international-call warning where material; and
• alternate contact methods.

The provider call request uses an idempotency key. A successful request creates a Call record before connection so retries cannot create duplicate calls.

16.7 Browser, forwarded and mobile answering

The preferred Workspace experience supports browser calling with an approved Voice SDK. Users may also forward or simultaneously ring verified phones according to policy. The system records which endpoint answered without exposing the private forwarding number to external participants.

Mobile web must support click-to-call and call-context handoff. A later native application may add richer background incoming-call behavior while retaining the same call records and permissions.

16.8 Call controls and routing

During a connected call, eligible users can:

• mute/unmute;
• place on hold/resume;
• open keypad;
• add an internal participant or approved external participant;
• warm or blind transfer;
• pause/resume recording;
• open the linked Project/context panel;
• add private live Notes and mark follow-ups; and
• end the call.

Inbound policies support business-hours greetings, holiday rules, ring groups, ordered or simultaneous ringing, queues, maximum wait, overflow destination, voicemail and blocked callers. Advanced IVR remains configuration-driven and should not force small Designer Workspaces to build a complex phone tree.

16.9 Recording consent

Recording is disabled unless the Workspace has an approved policy for the caller/recipient context. Because consent requirements vary by participant location and use, launch behavior should follow the strictest practical standard: clear notice and affirmative consent from all participants before recording or transcription.

Required controls:

• play an approved notice before recording starts;
• store notice template/version, language, time and consent outcome;
• allow the participant to continue without recording when policy permits;
• stop or pause immediately when consent is withdrawn;
• show a persistent visual recording state to platform users;
• emit an audible notice when required;
• prohibit silent user-controlled bypass;
• support recording pause during payment or other restricted data; and
• prevent transcription when no authorized recording/audio stream exists.

The Design Registry must obtain jurisdiction-specific legal review before enabling recording by market. Consent evidence is a durable compliance record, not merely a checkbox.

<!-- PAGE BREAK -->

16.10 Recording architecture

Use separate participant channels when supported so speakers can be distinguished reliably. Recording starts only after the approved consent point. Provider callbacks mark recording processing, available, failed, absent, deleted or quarantined states.

The canonical system stores a recording reference, checksum, duration, channel layout, encryption/retention policy and provider identifiers. Audio access uses short-lived authorized URLs; permanent provider URLs are never exposed to the browser or ordinary logs.

Authorized users can play at variable speed, skip silence, move by transcript segment and download only when a separate capability permits it. Deleting/redacting audio follows retention, legal hold and audit requirements.

16.11 Transcription

Transcription is generated asynchronously after a recording or voicemail becomes available. The provider is abstracted so Twilio transcription/Conversational Intelligence or another approved service can be used without changing the Conversation model.

Preferred output:

• language and model/version;
• speaker labels tied to known call legs where possible;
• timestamped segments and words where available;
• confidence at transcript and segment level;
• detected names, dates, amounts and Project references;
• redaction markers for configured sensitive patterns;
• processing, complete, partial, failed and unavailable states; and
• immutable original plus audited human corrections.

Real-time transcription may be added later for accessibility and live assistance, but post-call transcription is the baseline. Low-confidence text is visibly marked. The transcript is not treated as a legally perfect verbatim record.

16.12 Call summary and follow-up

After the call, an authorized user sees a review screen containing the disposition, recording/transcript status, an AI summary with timestamp citations, extracted questions, commitments, dates, amounts and decisions, suggested Project/record links, proposed Tasks/calendar events/follow-up message and a private internal Note area.

Nothing is added to formal Project scope, budget, approval, Proposal, Work Order or Invoice until an authorized user confirms it. The approved summary appears in the Conversation timeline as a typed call artifact, not a human Message.

16.13 Voicemail and missed calls

Voicemail creates a Call artifact with audio, transcript, caller, number called, time and routing history. It reopens or creates a Conversation and enters the appropriate Inbox. Missed calls without voicemail create a callback item, subject to spam/rate-limit policy.

Voicemail greetings can be Workspace, Inbox, business-hours or holiday specific. AI may summarize voicemail and suggest context but cannot automatically return the call.

16.14 Call-to-record correlation

Outbound calls started from a record inherit deterministic context. Inbound matching uses the Workspace number, caller/contact identity, existing Conversation, active Project relationships, recent activity and Project-specific extensions/aliases. Ambiguous calls enter the same reconciliation system used for email.

A single Call has one primary Conversation and may have related Project, Client, Provider, Offer, Work Order or other links. Recordings and transcripts are not copied between modules.

16.15 Call statuses and dispositions

Canonical technical statuses include queued, initiated, ringing, in progress, completed, busy, no answer, cancelled and failed. Product dispositions are separately selected or suggested, such as:

• connected—resolved;
• connected—follow-up required;
• left voicemail;
• voicemail received;
• wrong number;
• declined/not interested;
• schedule appointment;
• escalation required; and
• spam/blocked.

Provider-specific statuses map into the canonical model. A completed technical call does not imply a successful business outcome.

16.16 Channel escalation

A user can move from email to SMS or call without losing context, but each channel requires its own eligibility. Automation may suggest escalation; consequential contact remains governed by quiet hours, consent and human authority.

17. Assignment, Routing and Service Levels

17.1 Assignment

A Conversation may be assigned to one primary User and one Team/Inbox. Collaborators may follow or be mentioned without becoming the owner.

17.2 Routing rules

Rules can evaluate:

• represented Workspace and relationship type;
• Project, market, Provider category and Project phase;
• sender domain or known contact;
• channel and recipient alias;
• language, priority and operating hours;
• tags and classification; and
• current workload.

Rules are versioned, tested and audited. They may assign, tag, prioritize, set SLA or request AI classification. They cannot expand data access.

17.3 Round-robin and workload routing

Optional policies distribute eligible Conversations among active Team members. Availability is based on Membership state, schedule and configured capacity. A routed user must have record access before assignment.

17.4 SLA policies

SLAs define first-response and follow-up targets by Inbox, relationship, priority and business hours. Paused states and external-wait states are explicit. Alerts are Notification Builder events; the Inbox remains the source for live work state.

17.5 Snooze

Users may snooze until a date/time or supported event such as Provider reply, shipment arrival or Project milestone. Event-based snooze uses a durable subscription and always includes a fallback date.

18. Tags, Saved Views and Search

18.1 Tag administration

Workspace administrators can create tags with name, color, description, allowed record types and optional automation eligibility. Protected Registry tags cannot be redefined by a Workspace.

18.2 Search

Search covers permitted subject, body, participant, attachment metadata, Project, Provider, Client, record reference, tag and date. Results are permission-filtered before ranking and highlighting. Search snippets must not leak hidden text.

18.3 Saved views

Views can be personal or shared with a Team and include filters, sorting and displayed columns. Sharing a view does not share Conversations the recipient cannot access.

18.4 Export

Export requires an explicit capability and applies field masking, Conversation access, retention policy and audit. Internal Notes and message bodies are separately controllable from metadata export.

19. Communications Settings

Settings adds a Communications area rather than overloading Pipeline Builder.

Settings
└── Communications
    ├── Inboxes & Teams
    ├── Mailbox Connections
    ├── Sender Identities & Domains
    ├── Routing Rules
    ├── Business Hours & SLAs
    ├── Tags
    ├── Signatures & Saved Replies
    ├── Phone Numbers
    ├── Call Routing, Voicemail & Transcription
    ├── SMS
    ├── Consent & Preferences
    ├── Retention & Compliance
    └── Sync & Delivery Health

Notification Builder remains its existing Settings destination. Pipeline automation may reference a Conversation action or Notification Definition but does not own channel connections or inbox routing.

19.1 Connection health

Each connection shows owner, scope, last successful sync, cursor age, webhook/push state, permissions granted, failures and reconnect action. Revoked tokens stop synchronization and create an operational alert without deleting canonical platform Conversations.

19.2 Test tools

Administrators can send safe tests, preview sender identity, validate reply routing and run routing rules against synthetic data. Production message bodies are not copied into test environments.

20. Notification Builder Integration

Every new attention event is registered in the shared Notification Builder. Example definitions:

communication.message_received
communication.message_assigned
communication.note_mentioned
communication.conversation_unassigned
communication.sla_at_risk
communication.sla_breached
communication.external_reply_overdue
communication.scheduled_send_cancelled
communication.delivery_failed
communication.mailbox_disconnected
communication.sync_delayed
communication.reconciliation_required
communication.sms_opted_out
communication.call_incoming
communication.call_missed
communication.voicemail_received
communication.call_assigned
communication.call_recording_available
communication.call_transcript_available
communication.call_transcription_failed
communication.phone_number_activated
communication.phone_number_action_required
communication.phone_number_suspended

Editable templates may vary by Workspace, brand, language and allowed channel. Recipient resolution and security-critical behavior remain code-governed. A Message received event may alert a user; the alert must not be inserted as a duplicate Message.

21. Permissions and Visibility

Specification 08 remains authoritative. Communications adds capability keys including:

• communications.inbox.view
• communications.conversation.create
• communications.message.send
• communications.note.view
• communications.note.create
• communications.assign
• communications.link_records
• communications.export
• communications.connections.manage
• communications.call.place
• communications.call.answer
• communications.call.transfer
• communications.call.recording.listen
• communications.call.recording.download
• communications.call.transcript.view
• communications.call.transcript.correct
• communications.phone_number.purchase
• communications.phone_number.assign
• communications.phone_number.release
• communications.call_routing.manage
• communications.routing.manage
• communications.retention.manage
• communications.sensitive_content.view

Access is the intersection of Workspace membership, capability, Conversation participation/assignment, linked-record access and field policy. A user who can see a Project does not automatically see every related Conversation. A user who can see a Conversation does not automatically see restricted financial or contact fields in the context panel.

21.1 Contact masking

Client and Provider contact information follows field-level permission. Operational channels can use platform relay identities so a participant may communicate without receiving the underlying private email or phone number.

21.2 Revocation

Revocation closes Realtime channels, removes queue/search visibility, invalidates pending signed links and re-authorizes scheduled sends. Historical delivery to legitimate past recipients cannot be undone, but future platform access is removed.

22. AI Assistance

22.1 Supported assistance

• Summarize a long Conversation with source links.
• Draft a reply in the user's tone and Workspace brand.
• Improve clarity, grammar or warmth without changing facts.
• Suggest Project, Provider, Client and commercial record links.
• Extract commitments, decisions, dates, amounts and follow-up Tasks.
• Classify intent, urgency, sentiment and routing category.
• Detect unanswered questions, conflicting dates and stalled conversations.
• Suggest a saved reply or knowledge resource.
• Produce a Project communication brief.
• Summarize a call or voicemail with timestamp citations.
• Suggest a call disposition and next actions.
• Identify speakers, commitments and unanswered questions from an authorized transcript.

22.2 Guardrails

• AI receives only content the requesting user may access.
• Suggestions display confidence, evidence and unresolved uncertainty.
• AI never grants access, adds external participants or changes sender identity.
• AI never autonomously sends consequential external communication.
• Extracted amounts and dates are drafts until confirmed.
• Hidden notes cannot influence a Client-visible draft in a way that reveals their content.
• Providers and Clients are not ranked or judged from private communications without a separately governed purpose.
• AI never fabricates transcript text when audio is missing or unclear.
• AI call summaries must link back to transcript timestamps and retain uncertainty.

22.3 Project correlation assistance

AI correlation is used only after deterministic evidence. The model returns candidate record IDs from a permission-filtered set, confidence, matched evidence and conflict reasons. Low-confidence output enters reconciliation.

22.4 Data policy

Workspace policy controls AI eligibility by channel and sensitivity. Prompts, outputs, model/version, user decision and source references are auditable. Provider contracts must prevent training on customer content unless The Design Registry explicitly approves a compliant arrangement.

23. Delivery, Consent and Compliance

23.1 Email authentication

Production sender domains require SPF, DKIM and DMARC alignment appropriate to the delivery provider. Sender health includes bounce, complaint, suppression and authentication monitoring.

23.2 Consent and preferences

Communication preferences distinguish service/transactional contact from marketing. A participant cannot disable legally or operationally required messages when a valid relationship exists, but marketing consent is never inferred from Project participation.

23.3 Retention

Retention is configurable within Registry minimums, contractual needs and applicable law. Legal hold prevents deletion. Expiration workflows remove or redact content in a controlled manner while preserving required audit metadata.

23.4 Residential and financial sensitivity

Subjects, push previews and SMS must not expose full residential addresses, access codes, payment details or hidden commercial terms. Secure links require authentication and current authorization.

23.5 Spam and abuse

The platform supports sender blocking, spam classification, rate limits, domain reputation controls and participant reporting. Blocking a sender must not suppress security or legal records without review.

23.6 Voice recording and transcription compliance

Recording and transcription policies are resolved from Workspace, participant location, number jurisdiction, communication purpose and consent state. The strictest applicable configured rule wins. If the system cannot establish an approved policy, recording and transcription remain off.

Recording access, playback, download, transcript view, transcript export, redaction and deletion are separate capabilities. Retention may differ for call metadata, audio, transcript, summary and consent evidence. Legal hold freezes governed artifacts without granting broader access.

24. Data Architecture

24.1 Core tables

communication_inboxes

• id, workspace_id, name, key
• default_team_id, business_hours_policy_id, sla_policy_id
• status, created_at, updated_at

mailbox_connections

• id, workspace_id, owner_user_id nullable
• provider, external_account_id, connection_mode
• encrypted token reference, scopes and inclusion policy
• sync_cursor, last_synced_at, health_state, revoked_at

sender_identities

• id, workspace_id, mailbox_connection_id nullable
• address, display name, reply-to and provider
• verification, domain, default and status fields

conversations

• id, workspace_id, inbox_id
• subject, relationship type and primary context polymorphic reference
• status, priority, owner user/team, SLA state
• last message/activity timestamps, created and closed fields

conversation_participants

• conversation_id, participant type/ID and represented Workspace
• role, channel addresses, visibility start/end and state

conversation_record_links

• Conversation, record type/ID and link role
• source, confidence, evidence reference, actor and timestamps
• one active primary link constraint

messages

• id, conversation_id, workspace_id, author_identity_id
• direction, channel, body format/content reference, subject
• reply/forward/source Message references
• send state, scheduled time, sent time, received time
• idempotency key, created/updated fields

message_recipients

• Message, recipient type/ID/address, recipient kind
• represented Workspace and delivery eligibility snapshot

message_external_refs

• Message, provider, connection, external message/thread/event IDs
• normalized Message-ID and ingestion source

message_delivery_events

• Message/recipient, canonical and provider state
• provider event ID, event/received times, safe failure code

conversation_notes

• id, conversation_id, workspace_id, author_membership_id
• content reference, created/edited/redacted fields
• separate from Messages by design

note_versions and note_mentions

• immutable Note versions
• mentioned User/Team/record, notification state and timestamps

message_attachments

• Message or Note owner, File ID, inline disposition, content ID
• scan and quarantine state

communication_tags and conversation_taggings

• Workspace-scoped definitions and assignments

conversation_assignments

• ownership history, reason, rule/version and actor

communication_routing_rules

• versioned conditions, actions, priority, status and test results

communication_consents

• participant/channel/purpose, source, jurisdiction, granted/withdrawn times

communication_reconciliation_items

• source Message, candidates, confidence, conflicts, owner and resolution

communication_sync_events

• provider event receipt, dedupe key, processing state, attempts and safe error

workspace_phone_numbers

• id, workspace_id, provider/subaccount and external number ID
• E.164/display number, country, locality, type and capabilities
• assigned Inbox/Team/User, routing policy and caller-ID policy
• regulatory status/reference, billing owner and cost attribution
• lifecycle state, activated/suspended/released/ported timestamps

phone_number_orders

• Workspace, requester, search/selection snapshot and quoted costs
• regulatory requirements, billing acceptance and provider order ID
• requested, awaiting documents, provisioning, active, failed and cancelled states
• idempotency key, failure reason and audit reference

call_routing_policies

• number/Inbox, version, business-hours/holiday policy
• ring strategy, eligible endpoints, timeout and queue settings
• overflow, voicemail, greeting and recording/transcription policy

calls and call_legs

• calls: Conversation, Workspace, number, direction, primary participant and context
• canonical status/disposition, start/answer/end times and duration
• provider Call ID, idempotency key, recording policy and reconciliation state
• call_legs: participant/endpoint, external leg ID, direction, status and timestamps

call_recordings

• Call, provider recording ID, processing state, duration and channel layout
• encrypted object reference/checksum, consent reference and retention policy
• available/quarantined/redacted/deleted timestamps and safe failure code

call_transcripts

• Call/Recording, provider, language, model/version and overall confidence
• processing state, immutable original reference, corrected version and redaction state
• searchable/indexed state, retention and legal-hold fields

call_transcript_segments

• Transcript, ordered index, speaker/call-leg reference
• start/end time, text, confidence and redaction markers

call_consents

• Call and participant/leg
• notice template/version/language and presented time
• consent outcome, evidence source, withdrawn/pause times and policy version

call_summaries and call_followups

• source Transcript/version, AI provider/model and timestamp citations
• proposed summary, decisions, commitments and follow-up records
• human reviewer, approval state and resulting Task/event/Note references

24.2 Content storage

Message bodies may remain in Postgres when size and policy permit; large raw MIME, attachments, call recordings and original transcript artifacts belong in encrypted object storage with references. Ordinary logs never contain full bodies, audio, transcripts, tokens or attachment content.

24.3 Integrity constraints

• One canonical inbound Message per deduplication identity.
• One active primary Conversation context.
• Notes cannot have recipients or delivery events.
• External references are unique per provider/connection.
• Participant visibility ranges cannot exceed relationship policy.
• Workspace IDs are carried on high-volume tables for efficient RLS.
• A Call has one owning Workspace, primary Conversation and unique provider call identity.
• Recording cannot enter an available state without an approved consent/policy reference.
• Transcript segments cannot outlive their governing Transcript retention state.
• Releasing a number requires an approved lifecycle operation and cannot orphan active routing silently.

25. Supabase and Realtime Architecture

25.1 Data API and RLS

All browser-visible tables use Row Level Security plus explicit grants. Grants and RLS are both required. Prefer a dedicated exposed API schema and opt-in grants rather than relying on broad defaults.

Policies evaluate Workspace membership, capabilities, Conversation participation, assignment, linked-record access and Note visibility. Service-role operations are isolated to trusted workers and never exposed to the browser.

25.2 Realtime

Canonical Messages and Notes are committed to Postgres before Realtime notification. Private Realtime channels broadcast only minimal identifiers and permitted state changes. Clients fetch the authorized record through RLS.

Broadcast and Presence are transient. They support new-message hints, typing and viewing indicators; they are never the durable Message store. Authorization changes require token refresh/reconnect so cached channel permissions do not outlive access.

25.3 Edge Functions and workers

Short authenticated commands and signed webhooks may use Edge Functions or an equivalent trusted runtime. Gmail synchronization, MIME processing, attachment scanning, call-event processing, recording retrieval, transcription, indexing, retry, digest and AI work use durable queues/workers. Request lifetime is not treated as a background-job guarantee.

25.4 Keys and secrets

Frontend clients use publishable credentials and RLS-protected access. Secret/service credentials, Gmail refresh tokens, Resend/Twilio secrets and webhook verification keys remain server-side. The implementation should use current Supabase publishable/secret key guidance and avoid new dependence on legacy key patterns.

26. Service Architecture and Processing

26.1 Transactional outbox

Creating a sendable Message writes the Message, recipients, authorization snapshot and outbox event in one transaction. External delivery happens asynchronously. Idempotency prevents double send during retries.

26.2 Inbound event inbox

Provider events are authenticated, replay-checked and stored idempotently before processing. Duplicate delivery events update no business state twice.

26.3 Authorization at delivery

Scheduled, retried or delayed sends re-check sender membership, recipient relationship, consent and sender identity immediately before provider submission.

26.4 Failure handling

• transient provider failures retry with exponential backoff;
• permanent failures create an actionable delivery exception;
• mailbox auth failures pause sync and notify owners;
• poison events enter a dead-letter queue with safe diagnostics;
• workers expose lag, throughput and retry metrics; and
• no failure silently marks a Message delivered.
• call and recording callbacks may arrive out of order and are reduced idempotently by event time/provider sequence;
• a failed transcription does not delete the authorized recording and can be retried or sent to an approved fallback provider; and
• telephony outage policy preserves voicemail/overflow routing where the provider supports it and creates visible incident state.

27. API Design

Representative application endpoints:

GET    /communications/inboxes
GET    /communications/conversations
POST   /communications/conversations
GET    /communications/conversations/{id}
PATCH  /communications/conversations/{id}
POST   /communications/conversations/{id}/messages
POST   /communications/conversations/{id}/notes
POST   /communications/conversations/{id}/assign
POST   /communications/conversations/{id}/snooze
POST   /communications/conversations/{id}/close
POST   /communications/conversations/{id}/record-links
DELETE /communications/conversations/{id}/record-links/{linkId}
POST   /communications/messages/{id}/create-task
GET    /communications/search
GET    /communications/reconciliation
POST   /communications/reconciliation/{id}/resolve
GET    /settings/communications/connections
POST   /settings/communications/connections/google/start
POST   /settings/communications/connections/google/callback
POST   /settings/communications/connections/{id}/disconnect
GET    /settings/communications/routing-rules
POST   /settings/communications/routing-rules/test
GET    /settings/communications/phone-numbers
GET    /settings/communications/phone-numbers/available
POST   /settings/communications/phone-numbers/orders
POST   /settings/communications/phone-numbers/ports
PATCH  /settings/communications/phone-numbers/{id}/assignment
POST   /settings/communications/phone-numbers/{id}/release-request
GET    /settings/communications/call-routing
POST   /settings/communications/call-routing/test
POST   /communications/calls
GET    /communications/calls/{id}
POST   /communications/calls/{id}/transfer
POST   /communications/calls/{id}/recording/pause
POST   /communications/calls/{id}/recording/resume
POST   /communications/calls/{id}/end
GET    /communications/calls/{id}/recording
GET    /communications/calls/{id}/transcript
PATCH  /communications/calls/{id}/transcript/corrections
POST   /communications/calls/{id}/followups

Provider webhooks use separate signed endpoints. External webhooks do not rely on end-user JWTs. All mutation responses return stable IDs, current authorization-safe state and idempotency results.

27.1 Events

communication.conversation_created
communication.message_received
communication.message_queued
communication.message_submitted
communication.message_delivered
communication.message_failed
communication.note_created
communication.note_mentioned
communication.assignment_changed
communication.record_linked
communication.record_link_corrected
communication.status_changed
communication.sla_at_risk
communication.reconciliation_created
communication.reconciliation_resolved
communication.mailbox_health_changed
communication.call_created
communication.call_ringing
communication.call_answered
communication.call_completed
communication.call_missed
communication.voicemail_received
communication.recording_available
communication.recording_failed
communication.transcription_completed
communication.transcription_failed
communication.call_followup_confirmed
communication.phone_number_ordered
communication.phone_number_activated
communication.phone_number_suspended
communication.phone_number_released

28. Audit and Observability

28.1 Audit

Audit records actor User/Membership/Workspace, action, Conversation/Message/Note, previous and new state, recipient set, sender identity, record-link evidence, routing rule/version, IP/device context where appropriate and reason for privileged changes.

Reading every Message need not create a high-volume immutable audit event unless policy requires it, but sensitive export, impersonation, redaction, connection changes and privileged access must be audited.

28.2 Metrics

• Inbound and outbound throughput/lag
• Provider delivery states and bounce/complaint rate
• Gmail synchronization cursor age and errors
• Reconciliation rate and accuracy
• First-response, follow-up and resolution time
• SLA risk and breach counts
• Realtime disconnect/reconnect rate
• Search latency and indexing lag
• Queue retry and dead-letter counts
• Attachment scan/quarantine rate
• AI suggestion acceptance and correction rate
• Number inventory, activation/porting exceptions and monthly/usage cost by Workspace
• Call answer, abandonment, missed-call and voicemail callback rates
• Call setup time, duration, failure reason and provider quality indicators
• Recording availability lag and consent refusal/pause rate
• Transcription completion, latency, confidence and correction rate
• Call follow-up confirmation and overdue rate

28.3 Operational dashboards

Dashboards expose system health without showing message bodies by default. Operators can drill into safe identifiers and reason codes. Access to content requires support authorization and audit.

29. UX, Accessibility and Responsive Requirements

• Keyboard navigation across queues, messages, participants and composer.
• Visible focus, labels, errors and status announcements.
• Note/Reply mode conveyed through text, icon and submit wording—not color alone.
• Screen-reader labels for delivery, unread and participant state.
• Accessible attachment upload progress and failure recovery.
• Minimum touch targets and mobile-safe composer.
• Draft autosave with recovery after connection loss.
• Time displayed in user timezone with absolute timestamp available.
• Participant names include represented organization to avoid identity ambiguity.
• Conversation loading uses stable skeletons and preserves reading position.

30. User Stories

30.1 Designer

• As a Designer, I can connect only an approved Gmail label so unrelated personal mail remains outside the platform.
• As a Designer, I can see that an email belongs to the Smith Residence Project and a specific Millwork Provider.
• As a Designer, I can reply from my real business identity and see the reply in Gmail and the Project.
• As a Designer, I can add a private Note and mention my procurement teammate without risking Client delivery.
• As a Designer, I can turn a Provider's promised date into a Project Task and calendar event.
• As a Designer, I can find every conversation about a damaged item by Project, PO and tag.

30.2 Registry administrator

• As a Registry administrator, I can communicate with Designers, Clients and Providers when my relationship permits it.
• As a Registry administrator, I cannot browse a Designer's unrelated connected mailbox.
• As an operations user, I can route Provider application messages to the correct market Team.
• As an administrator, I can see disconnected mailboxes and delivery failures without reading private content.

30.3 Client

• As a Client, I can reply by email or in the portal and see one coherent Project history.
• As a Client, I never see internal Notes, Provider comparisons or hidden commercial details.
• As a Client, I can receive a request that links securely to the formal approval record.

30.4 Provider

• As a Provider, I can see Offer clarification messages before award and Job communications after award.
• As a Provider, I can reply from my portal or email without seeing unrelated Projects.
• As a Storage Provider, I can discuss a receiving exception linked to the affected items and evidence.

30.5 Workspace owner

• As an Owner, I can configure Inboxes, Teams, routing, sender identities, business hours and SLAs.
• As an Owner, I can view sync scope and revoke a mailbox connection.
• As an Owner, I can customize allowed Saved Replies while Notification Builder remains the source for transactional alerts.

31. Acceptance Criteria

31.1 Unified inbox

• Authorized users can list, search, filter, assign, tag, snooze and close Conversations.
• Queue counts and statuses update without requiring full-page refresh.
• Search and saved views never expose inaccessible Conversation metadata or snippets.

31.2 Email

• Gmail OAuth scope and included-message policy are shown before connection.
• Inbound email is deduplicated and threaded using deterministic evidence.
• Replies sent from the platform use the selected verified identity exactly once.
• Replies sent through connected Gmail appear in the correct Conversation when in scope.
• Delivery and synchronization failures are visible and recoverable.

31.3 Context correlation

• Deterministic Project/record links are created and audited.
• Medium/low-confidence messages enter reconciliation rather than being silently linked.
• Authorized users can correct links with history and immediate access re-evaluation.
• One canonical Message can appear in several authorized record views without duplication.

31.4 Notes

• Internal Notes cannot be addressed, queued or delivered externally.
• Client and Provider users cannot access Notes through UI, API, search, export, Realtime or AI.
• Mentions notify only already-authorized recipients.
• Note edits retain version history.

31.5 Projects and participants

• Project Communication shows Client, Provider and internal threads filtered by permission.
• Provider pre-award and post-award visibility follows Offer/Job access.
• Provider-to-Client communication is disabled unless explicitly enabled for a scoped purpose.

31.6 Notifications

• Every required communication attention event is registered in Notification Builder.
• Notifications do not duplicate human Messages.
• Template customization cannot change protected recipient resolution or expose sensitive variables.

31.7 Security and reliability

• RLS and grants prevent cross-Workspace and cross-Project access.
• Private Realtime channels deliver only to authorized subscribers.
• External provider events are signature-verified/replay-resistant where supported and idempotent.
• Scheduled and retried sends re-check authorization and consent.
• Secrets and mailbox tokens never reach the browser or ordinary logs.

31.8 Phone numbers and calling

• An authorized Owner can search available numbers by jurisdiction, locality/type and required capabilities.
• The purchase screen displays provider-fetched availability, recurring/usage pricing and regulatory requirements before confirmation.
• Number purchase is idempotent and results in one auditable Workspace Phone Number.
• Purchased/ported numbers can be assigned to an Inbox, Team or User and tested before activation.
• Release requires protected confirmation and cannot silently orphan routing or published contact points.
• Authorized users can place and receive calls using an approved Workspace caller ID.
• Inbound routing respects business hours, queues, overflow and voicemail configuration.
• Calls started from a Project/record inherit context; ambiguous inbound calls enter reconciliation.
• Missed calls and voicemail produce actionable Inbox records.

31.9 Recordings and transcripts

• Recording/transcription remains off unless an approved policy resolves and required notice/consent is captured.
• A participant can decline or withdraw recording where the policy provides, and pause/resume is auditable.
• Recording state is visible to the platform user throughout the call.
• Completed authorized recordings are stored through protected references and short-lived playback access.
• Voicemail and recorded calls can generate speaker-aware, timestamped transcripts.
• Low-confidence segments and unavailable/failed states are visible.
• AI summaries cite transcript timestamps and require human confirmation before creating formal work.
• Recording listen, download, transcript view, correction, export and deletion are separately permissioned.
• Call artifacts appear once in the canonical Conversation and are projected into authorized Project/record views.

32. Migration Plan

32.1 Inventory

Inventory existing Messages, Communication tabs, activity entries, email logs, Notification deliveries, contacts, Project links, attachments and prototype thread identifiers.

32.2 Canonical mapping

• Convert existing participant-visible threads into Conversations/Messages.
• Keep internal notes in conversation_notes, never infer external visibility from visual labels.
• Link records through conversation_record_links.
• Preserve original authorship, timestamps and legacy IDs.
• Keep Notification deliveries typed as Notifications rather than human Messages.

32.3 Reconciliation

Low-confidence legacy links enter a migration reconciliation report. The migration must not attach a message to a Client or Provider based only on matching display names.

32.4 Parallel validation

Run new projections alongside existing Communication views. Compare message counts, participants, attachments, Projects, timestamps and visibility before cutover.

32.5 Cutover

1. Freeze legacy message creation.
2. Complete final incremental migration.
3. Switch tabs and navigation to the canonical Conversation service.
4. Monitor access denials, missing links, delivery and sync health.
5. Retain a read-only legacy reference for a defined support period.

33. Implementation Phases

Phase 1 — Canonical conversations and notes

• Core schema, RLS, capabilities and audit
• Conversation list/thread/context UI
• In-app Messages
• Separate internal Notes, mentions and record tagging
• Project, Client, Provider and commercial record links

Phase 2 — Inbox operations

• Inboxes, Team/User assignment and statuses
• Tags, saved views, search and SLA foundation
• Notification Builder events
• Shared responsive components

Phase 3 — Gmail and managed email

• Gmail connection and least-permissive sync modes
• Inbound normalization, threading and deduplication
• Gmail/managed sender identities and outbound delivery
• Delivery/sync health and reconciliation queue
• Domain authentication and safe attachment handling

Phase 4 — Project-aware intelligence

• Deterministic and AI-assisted record correlation
• Task/event/decision extraction
• Conversation summaries and suggested replies
• Provider Offer/Job and logistics context

Phase 5 — Business phone, SMS and advanced routing

• Twilio SMS consent, inbound/outbound and opt-out
• Phone-number search, purchase, assignment, porting and lifecycle management
• Inbound/outbound browser calling and verified forwarding
• Business hours, ring groups, queues, transfer, voicemail and missed-call workflows
• Consent-aware dual-channel recordings and protected playback
• Voicemail/call transcripts, speaker segments, AI summaries and confirmed follow-ups
• Workload routing, event snooze and richer SLAs
• Operational analytics

Phase 6 — Hardening and scale

• Retention/legal hold and advanced compliance
• Search/index scale testing
• Disaster recovery and provider failover procedures
• Deliverability and mailbox-provider review
• AI quality, privacy and bias evaluation

Every phase includes security, accessibility, mobile, audit, failure recovery, migration and user-acceptance testing.

34. Testing Strategy

34.1 Unit tests

• Conversation access and participant rules
• Note serializers and external-delivery exclusion
• Threading and deduplication keys
• Record-correlation confidence policies
• Routing, SLA and business-hours calculations
• Consent and sender identity eligibility
• Idempotency and delivery-state mapping

34.2 Integration tests

• Gmail inbound, outbound and outside-platform replies
• Resend notification versus managed human message behavior
• Twilio delivery/opt-out when enabled
• Twilio number search/purchase, regulatory pending state, assignment and protected release
• Inbound/outbound calls, multiple legs, transfer, queue, voicemail and out-of-order callbacks
• Consent accepted, declined, withdrawn and recording paused/resumed
• Recording available/absent/failed and transcript complete/partial/failed
• Transcript speaker/timestamp mapping and audited human correction
• Project/Offer/Work Order link propagation
• Permission removal during open thread and scheduled send
• Mailbox disconnect/reconnect and incremental sync
• Attachment quarantine and authorized retrieval

34.3 Security tests

• Cross-Workspace Conversation enumeration
• Client/Provider attempts to access Notes
• Search/export/AI leakage
• Forged reply aliases and webhook signatures
• OAuth token exposure and scope escalation
• Record move/link cache invalidation
• Realtime subscription after access revocation
• Unauthorized recording/transcript playback, download, search, export and AI access
• Forged telephony callbacks, replayed call events and caller-ID misuse
• Number purchase/release without billing or Owner authority
• Consent-policy bypass and transcript creation without authorized audio

34.4 Scenario library

• Duplicate inbound email through forward and Gmail sync
• Same subject for two Clients
• One Provider working on several Projects
• Forwarded chain containing unrelated private history
• Participant removed before scheduled send
• Provider replies after Offer expiry
• Client replies after Project closure
• Delivery failure followed by manual correction
• Ambiguous PO number and conflicting Project participants
• Internal Note copied intentionally into a reviewed draft
• Inbound call matches two active Projects for the same Client
• Provider calls the general number before and after Work Order award
• Participant refuses recording but continues the call
• Call includes payment information and recording is paused
• User transfers a recorded call to another teammate
• Voicemail is transcribed and linked to the correct Project
• Workspace requests a local number where documentation is required
• Number port remains pending while temporary routing is active
• Owner attempts to release a number used in published templates and active Projects

35. Open Configuration Decisions

These are launch configuration choices, not architectural blockers:

• Gmail connection modes enabled at launch.
• Whether managed Workspace identities may send human email through Resend or another provider.
• Initial mailbox retention period and legal-hold policy.
• Initial SMS regions and consent language.
• Launch markets and eligible number types/capabilities.
• Number pricing/markup, cost pass-through and usage limits.
• Telephony provider account/subaccount isolation and customer port-out terms.
• Browser-only calling versus verified-phone simultaneous ring at launch.
• Call queue, IVR and after-hours defaults by Workspace type.
• Recording jurisdictions, consent wording, retention and download policy after legal review.
• Transcription provider, supported languages and real-time versus post-call scope.
• Registry oversight policy for Registry-originated Projects.
• Provider-to-Client operational channel categories.
• Default Inbox/Team structure by Workspace type.
• Initial SLA targets and business hours.

The safest launch assumption is Gmail for human correspondence, Resend for platform transactional messages, in-app messaging for authenticated collaboration, Twilio for Workspace-managed phone numbers/SMS/Voice, post-call transcription for consented recordings and manual reconciliation for any uncertain record match.

36. Definition of Done

The Communications, Unified Inbox and Client Collaboration system is complete for its approved release scope when:

• all supported Registry, Designer, Client and Provider relationships use one canonical Conversation model;
• email and in-app replies converge without duplicate histories;
• incoming email is associated deterministically or routed for human reconciliation;
• Projects and related records show permission-filtered projections of canonical Conversations;
• internal Notes and mentions are protected from every external channel by server-enforced separation;
• routing, ownership, statuses, tags, search and SLA behavior are usable by operational Teams;
• Gmail, Resend and enabled Twilio processing is idempotent, observable and recoverable;
• authorized Workspaces can obtain, assign and operate a business number with governed billing and lifecycle controls;
• inbound/outbound calls, voicemail, consent, recordings, transcripts and follow-ups appear in the correct canonical Conversation;
• Notification Builder remains the governed source for event-triggered templates;
• RLS, Realtime, export, search and AI enforce the same access model;
• migration reconciliation and security testing pass agreed thresholds; and
• Designers can confidently use the platform as the communications centre of their business without giving up the inbox workflow they depend on.

The finished product should feel like an elegant, project-aware business inbox: as immediate as messaging, as dependable as email and as organized as the operating system around it.

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

Current-product review gap closure register

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

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 Communications

Current-product profile: record-communications
Observed route: /admin/leads/:id?tab=communication
Evidence confidence: Verified

Review gaps

• No populated live conversation was available.
• Channel composers, sending, receiving and delivery states were not tested.
• Health values appear inconsistent with zero channel events and may be seed/demo data.
• Purchased phone numbers, call recordings and transcripts are not evidenced here.
• Connection/setup states are not exposed.
• Thread-to-Project/provider auto-classification remains unverified.

Required future closure

• Implement the unified inbox and record-aware classification in Spec 11.
• Make connection state, delivery state and consent explicit.
• Add purchased-number management, call recordings/transcripts and searchable summaries.
• Use one communication object across Admin, Designer, Provider and Client relationships with strict visibility.

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 — Messages and Unified Inbox

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

Review gaps

• No route or working inbox exists.
• No email, SMS, calling or in-app queue can be verified.
• No Conversation assignment, notes, tags, mentions, SLA, search or participant controls exist globally.

Required future closure

• Implement the four-panel Unified Inbox from Spec 11.
• Connect all channels through shared Conversations and Messages.
• Add deterministic Project/Entity correlation and a governed reconciliation queue.
• Support internal collaboration, Task creation, notification preferences and channel health.

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