Studio Communication Hub & Inbox: Complete Tenant & AI Co-Pilot Guide

This document is the definitive master manual for the Studio Communication & Messaging Hub. It details the architecture, UI controls, step-by-step workflows, real-world print shop scenarios, linking strategies, and AI Co-Pilot prompt guidelines.

---

1. Vision & Core Philosophy

In custom apparel and commercial print shops, email is where deals happen, artwork is approved, and revisions are requested. Traditional print shop CRMs disconnect email from production, forcing staff to constantly juggle browser tabs, search Gmail/Outlook, and risk missing crucial client instructions.

Studio's Communication Hub integrates live Gmail & Microsoft Outlook directly into the shop's production pipeline:

• Zero Disconnect: Emails automatically associate with Quotes, Invoices, and Customer accounts.
• No Re-inventing the Wheel: Staff use their real @yourshop.com email addresses via secure OAuth without managing separate webmail accounts.
• Production Context: When a printer, press operator, or salesperson views an order (/quotes-invoices/[id]), the complete email history is embedded right on the job ticket under "Messages & Emails".

---

2. Visual Architecture & UI Control Directory

┌──────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                       STUDIO INBOX (/inbox)                                      │
├───────────────────────────────────┬──────────────────────────────────────────────────────────────┤
│ LEFT PANE: Filter & Thread Stream │ RIGHT PANE: Active Conversation & CRM Context               │
├───────────────────────────────────┼──────────────────────────────────────────────────────────────┤
│ 🔍 Search Bar (Active Match Count)│ ✉️ Thread Subject Header & Status Chips (Linked / Starred)   │
│ 📁 [CRM Contacts (X)] [All (Y)]   │ 🔗 [Link to Quote / Invoice] | 🏷️ Star | 👁️ Mark Unread     │
│ 📑 Category Tabs:                 │ 👤 [View Customer CRM Drawer]                               │
│    • All (Total Count)            ├──────────────────────────────────────────────────────────────┤
│    • Unread                       │ 📨 Sandboxed Email Messages (Chronological)                  │
│    • Starred                      │    • Clean Theme Typography (Dark / Light reactive)          │
│    • Linked (CRM Attached)        │    • Quote Collapsing: [··· Show quoted text]                │
│    • Unlinked (General)           │    • High-res Attachment Previews & Instant Download         │
│ 🔄 Refresh Mailbox                ├──────────────────────────────────────────────────────────────┤
│ ────────── Thread Items ──────────│ ✍️ Inline Reply Composer:                                    │
│ • [Customer Badge] Quote #1042    │    • Rich Text / Plain Text formatting                       │
│ • Star / Unread Indicators        │    • File Attachments & Artwork Drag-and-Drop                │
│ • Relative Time (e.g., "12m ago") │    • [Send Email] / [Discard]                                │
└───────────────────────────────────┴──────────────────────────────────────────────────────────────┘

A. Left Pane: Navigation & Search Controls

Control / Button	Location	Action & Behavior
Search Input	Top of left pane	Filters threads in real time across sender names, email addresses, subjects, body text, and quote/invoice numbers. Shows active match count (e.g. "3 conversations found") with an instant [✕] clear button.
CRM Contacts Toggle	Top sub-header	Filters mailbox to show only conversations from recognized customer emails and contacts in your Studio database. Displays active badge count.
All Mailbox Toggle	Top sub-header	Displays full inbox (including suppliers, general inquiries, logistics, and non-CRM emails). Matches height of action buttons (h-9).
Category Tabs	Under toggle	• All: Every message in selected mailbox mode.<br>• Unread: Threads requiring immediate staff attention.<br>• Starred: Flagged priority threads.<br>• Linked: Threads already tied to a Quote, Invoice, or Customer.<br>• Unlinked: Unassigned emails waiting to be associated with jobs.
Refresh Button (🔄)	Top right of left pane	Live-syncs latest messages from Gmail/Outlook servers.
Thread List Item	Left stream	Clicking selects the active thread. Highlights document tags (e.g. Quote #1042, Customer: Acme Corp), unread status dots, star icons, and sender avatar.

---

B. Right Pane: Thread Viewer & Actions

Control / Button	Location	Action & Behavior
Link Entity Button (🔗 Link)	Thread header toolbar	Opens the Link Entity Dialog to associate the active conversation with a Quote, Invoice, or Customer.
Unlink Button (Unlink)	Entity badge & dialog	Instantly severs the link with a single click if an email was assigned to the wrong job, returning the thread to unlinked status.
Star Button (⭐)	Thread header toolbar	Toggles priority star status, syncing across Studio and the connected mailbox.
Mark Unread (👁️)	Thread header toolbar	Resets thread unread badge to keep it in the triage queue.
CRM Context Drawer (👤)	Thread header right	Opens the slide-over drawer displaying customer lifetime spend, open invoices, active quotes, contact phones/addresses, and linked job cards.
··· Show quoted text	Inside message body	Automatically trims and collapses messy nested email histories (.gmail_quote, On ... wrote:, previous thread headers). Clicking smoothly expands the full unedited email trail.
Attachment Chips	Below email body	Displays file icon, filename, and file size. Clicking downloads the attachment securely via server-mediated streaming.
Inline Reply Box	Bottom of thread	Type reply, attach artwork or PDF specs, and send directly through connected Gmail/Outlook OAuth bridge.

---

C. Embedded Job Ticket & Customer Panels

1. Quote / Invoice Detail Page (/quotes-invoices/[id]):
   • Navigate to the "Messages & Emails" tab.
   • Displays all email threads linked to that specific quote or invoice.
   • Staff can read client correspondence, download customer-submitted artwork, and reply to the thread directly from the job ticket without opening the central inbox.
2. Customer CRM Page (/customers/[id]):
   • Navigate to the "Email History" tab.
   • Displays an aggregated history of all communications across every quote, invoice, and inquiry for all contacts belonging to that account.

---

3. Step-by-Step Tenant Guides

Guide 1: How to Connect Your Shop Email (Gmail or Outlook)

1. Expand Finance & Settings in the left sidebar, click Settings (/settings), then select the Connections tab.
2. Click Connect Gmail or Connect Outlook.
3. Complete the standard Google / Microsoft OAuth authorization screen.
4. Once connected, your email address is displayed with a green Connected status badge.
5. Go to Inbox (/inbox) in the left navigation sidebar — your emails will sync automatically!

---

Guide 2: How to Link an Email Thread to a Quote or Invoice

When a customer sends an email regarding a job:

1. Open Inbox (/inbox) and click on the customer's email in the left list.
2. In the top-right toolbar of the message header, click the 🔗 Link button.
3. In the modal that appears:
   • Select Quote / Invoice.
   • Search by Quote Number (e.g. 1042), Customer Company, or Job Name.
   • Click Link Conversation.
4. Result:
   • The thread is tagged with a badge (e.g. Quote #1042 - Fall Festival Shirts).
   • The conversation now instantly appears on the job ticket under /quotes-invoices/1042 $\rightarrow$ Messages & Emails tab!

---

Guide 3: How to Link an Email Thread to a Customer Account

If an email is a general sales inquiry or customer relationship message not tied to a single specific order:

1. Open the thread in /inbox.
2. Click 🔗 Link $\rightarrow$ select Customer Account.
3. Search for the customer company name or contact.
4. Click Link Conversation.
5. Result: The thread appears under the customer's CRM profile at /customers/[id] $\rightarrow$ Email History.

---

Guide 4: How to Unlink or Re-assign a Misplaced Email

If staff accidentally link an email to the wrong job:

1. Open the thread in /inbox or in the CRM Context Drawer.
2. Click the Unlink button next to the linked document badge, or click Link and choose Unlink Current.
3. The conversation returns to unlinked status immediately. You can now link it to the correct quote or invoice.

---

Guide 5: How to Filter Between CRM Customers and Shop Mailbox

• Click CRM Contacts (X) to focus strictly on real print clients and active opportunities. This hides supplier marketing, vendor spam, and automated receipts.
• Click All Mailbox (Y) when you need to inspect supplier emails (SanMar, S&S, AlphaBroder), shipping carrier tracking, or unassigned new leads.

---

4. Real-World Scenarios & Best Practices

Scenario	Situation	Recommended Action	Why This Matters
1. Customer Sends Artwork via Email	Customer replies: "Here is our vector SVG logo and Pantone colors for the hoodies!"	Link to Quote #XXXX	The production department, pre-press artist, and screen printer can access the artwork files directly from the Job Ticket tab without asking sales to forward files.
2. Customer Requests Proof Revision	Customer replies: "Can we make the front logo 2 inches smaller and change ink to White?"	Link to Quote #XXXX	Creates an undeniable timestamped audit trail on the job ticket. If a discrepancy arises on press, the exact email instruction is attached to the order.
3. Customer Sends PO / Terms Authorization	Corporate or school client emails: "PO #98234 is approved, please net-30 invoice us."	Link to Invoice #XXXX	Bookkeeping and sales staff see the official purchase order authorization directly on the financial invoice.
4. General Price List or Capability Inquiry	New prospect emails: "Hi, do you guys do DTF gang sheets and embroidery?"	Link to Customer (or keep unlinked until Quote is created)	Once you create their quote, link the thread to Quote #XXXX so the conversation follows the job.
5. Multi-Job Client Email	Client discusses two separate jobs in one email: "Regarding Quote 1050 and Invoice 1045..."	Link to Primary Quote or Customer Account	Linking to Customer ensures it is visible across the entire account history; you can also reference the second quote in internal notes.
6. Supplier Tracking & Packing Slips	SanMar or S&S Activewear emails shipping tracking for blanks.	View in All Mailbox	Keep in All Mailbox or link to the specific purchase order / job for quick blank receipt verification.

---

5. Security & Isolation Architecture

Studio implements a three-tier defense-in-depth security model for processing and rendering email content:

1. Server-Side Sanitization (src/lib/server/inbox-providers.ts):
   • Uses sanitize-html to strip executable <script>, <object>, <embed>, <applet>, <form>, <input>, and all inline JavaScript event handlers (onclick, onerror, onload).
   • Whitelists safe styling tags (<style>, <span>, <div>, <img>, <table>) so rich email newsletters, supplier POs, and formatted signatures render faithfully.
2. Hard Browser CSS & DOM Boundary (EmailBodyFrame.tsx):
   • Email HTML is rendered inside an isolated <iframe> using srcDoc.
   • Email CSS cannot touch or leak into the parent application DOM, preventing CSS injection, UI defacement, or styling conflicts.
3. HTML5 Sandboxing:
   • Uses sandbox="allow-same-origin allow-popups allow-popups-to-escape-sandbox".
   • allow-scripts is strictly disabled, making it physically impossible for any JavaScript to execute inside the email frame.

---

6. Shop Co-Pilot AI Prompting & Guidance Blueprint

When the shop owner or staff asks the Studio Shop Co-Pilot questions about the Inbox or Communication Hub, the Co-Pilot should follow these standardized guidelines:

A. Core Knowledge Checklist for Co-Pilot

• Page Location: /inbox (accessible from the main navigation sidebar under "Inbox").
• Staff Access: Visible to the shop owner by default. A staff account only sees the Inbox link (and can load threads) once the owner grants that staff member the "Access Inbox & Email Correspondence" (inbox_view) permission under Settings → Staff. If a staff member says they don't see Inbox at all, this is almost always why - have the owner enable it on their staff profile. See docs/STAFF_ACCOUNTS.md for the full permissions guide.
• Quote Tab: /quotes-invoices/[id] $\rightarrow$ "Messages & Emails" tab.
• Customer Tab: /customers/[id] $\rightarrow$ "Email History" tab.
• Connections: Expand Finance & Settings in sidebar $\rightarrow$ /settings $\rightarrow$ Connections tab (Gmail / Outlook / SMTP OAuth & keys).
• Key Features:
  • Dual-mode mailbox (CRM Contacts vs All Mailbox).
  • Instant entity linking to Quotes, Invoices, and Customers.
  • One-click unlinking.
  • Collapsible nested quote threads (··· Show quoted text).
  • Live search with active match counters.
  • Secure, sandboxed HTML email body rendering.

B. Sample Co-Pilot Responses to Common Staff Queries

Staff Question: "Where do I see emails related to Quote #1042?"

Co-Pilot Guidance: "You can view emails for Quote #1042 in two places:

1. Directly on the Quote: Go to Quotes & Invoices $\rightarrow$ open Quote #1042 $\rightarrow$ click the Messages & Emails tab. All linked correspondence, customer replies, and attachments are right there.
2. In the Central Inbox: Go to Inbox (/inbox), select the Linked tab, or search #1042 in the search bar."

Staff Question: "How do I attach a customer's email with artwork to a job?"

Co-Pilot Guidance: "1. Open Inbox from the left sidebar. 2. Click on the customer's email. 3. Click the 🔗 Link button in the top right of the message header. 4. Choose Quote / Invoice, search for the quote number (e.g. 1042), and click Link Conversation. 5. The email and all attached artwork files will now be permanently attached to Quote #1042!"

Staff Question: "I linked an email to the wrong quote by mistake. How do I fix it?"

Co-Pilot Guidance: "No problem! Open the conversation in Inbox, click the Unlink button next to the quote badge at the top of the message (or open the CRM Context Drawer on the right and click Unlink). Once unlinked, click 🔗 Link to assign it to the correct quote."

Staff Question: "Why don't I see Inbox in my sidebar at all?"

Co-Pilot Guidance: "Inbox is off by default for staff accounts - only the shop owner needs to turn it on for you. Ask the owner to go to Settings → Staff, open your profile, and enable "Access Inbox & Email Correspondence". The Inbox link will show up for you as soon as that's saved."

---

7. File Map & Code References

• Central Inbox Page: src/app/(app)/inbox/page.tsx
• Thread Viewer: src/components/inbox/InboxThreadDetail.tsx
• Email Body Frame (Sandboxed & Collapsible): src/components/inbox/EmailBodyFrame.tsx
• Search & Thread Stream: src/components/inbox/InboxThreadList.tsx
• Top Filter Bar: src/components/inbox/InboxTopBar.tsx
• Entity Linker Modal: src/components/inbox/LinkEntityDialog.tsx
• CRM Slide-Over Drawer: src/components/inbox/InboxContextSheet.tsx
• Outbound Composer: src/components/inbox/ComposeEmailDialog.tsx
• Quote Messages Tab: src/components/quotes/QuoteCorrespondencePanel.tsx
• Customer Email History Tab: src/components/customers/CustomerCorrespondenceTab.tsx
• Server Providers & Sanitizer: src/lib/server/inbox-providers.ts
• Custom SMTP Modal: src/components/settings/smtp-connection-dialog.tsx
• SMTP Server Actions: src/lib/data/smtp-actions.ts

---

8. Third-Party Email & Custom SMTP Guide (Yahoo, iCloud, Zoho, AOL, & Webmail)

While Google Workspace and Microsoft 365 connect via OAuth, shops using Yahoo Mail, Apple iCloud, Zoho, AOL, cPanel, or private webmail servers can dispatch quotes, invoices, and job alerts using the Custom SMTP Relay.

A. Quick Provider Presets in Studio

Inside Settings $\rightarrow$ Connections $\rightarrow$ Connect Custom SMTP, the modal includes built-in quick presets that automatically configure the server host, port, and security protocols:

• Yahoo Mail (@yahoo.com, @ymail.com): smtp.mail.yahoo.com, Port 587, SSL OFF
• Apple iCloud (@icloud.com, @me.com): smtp.mail.me.com, Port 587, SSL OFF
• Zoho Mail (@zoho.com / custom domain): smtp.zoho.com, Port 587, SSL OFF
• AOL Mail (@aol.com): smtp.aol.com, Port 465, SSL ON
• cPanel / Custom Domain Webmail: mail.yourdomain.com, Port 465, SSL ON
• Hostinger / Titan Email: smtp.hostinger.com / smtp.titan.email, Port 465, SSL ON
• SendGrid / Mailgun: smtp.sendgrid.net / smtp.mailgun.org, Port 587, SSL OFF

B. The 16-Character App Password Rule

Third-party mail providers (Yahoo, Apple, Zoho, AOL) strictly block normal account passwords on automated mail relays. Tenants must generate a 16-character App Password:

• Yahoo App Password: Go to login.yahoo.com/account/security $\rightarrow$ Generate app password $\rightarrow$ label it Studio.
• Apple iCloud App Password: Go to appleid.apple.com $\rightarrow$ Sign-In and Security $\rightarrow$ App-Specific Passwords.
• Zoho App Password: Go to accounts.zoho.com/home#security/app_passwords $\rightarrow$ Generate New Password.
• AOL App Password: Go to login.aol.com/account/security $\rightarrow$ Generate app password.

C. Shop Co-Pilot AI Troubleshooting Script

When a tenant asks the Shop Co-Pilot how to connect Yahoo or another third-party provider:

Co-Pilot Instruction:

1. Inform the user that Yahoo, iCloud, and Zoho require an App Password rather than their standard account password.
2. Direct them to Settings $\rightarrow$ Connections $\rightarrow$ Connect Custom SMTP.
3. Guide them to select the provider preset (e.g. Yahoo Mail) from the dropdown.
4. Instruct them to paste their 16-character App Password, save, and click "Test Email" to verify delivery.