Master Architecture & Migration Playbook: Drag ➡️ HubSpot CRM

Client: The Dog Wizard
System Class: CRM Migration & Workspace Engineering
File Location: ~/projects/03_clients/dogwizard/drag-migration/drag-to-hubspot-blueprint.md

🎯 1. Executive Summary & Objectives

This document establishes the master architectural blueprint and step-by-step technical plan to migrate The Dog Wizard operations from a legacy Drag App (Gmail Shared Board) format to a highly structured, automated, and spam-resilient HubSpot Shared Inbox Conversations & Centralized Support environment.

🌟 Unified Communications & Lead Architecture (Sales Hub Pro Optimization)

Following strategic alignment on HubSpot Sales Hub Professional capabilities and operations, we are deploying a clean architecture to separate Customer Service/Operations from High-Priority Sales Lead Flow, while keeping workflows lean and simple:

The Shared Inbox (Conversations): Collaborative triage space for the team to manage general office inquiries (office@) and location-specific group aliases (e.g., ashland@). Auto-ticketing is disabled to filter out spam and vendor noise. High-volume inbound emails are managed purely as conversational threads.
The Centralized Support Help Desk Pipeline with Help Desk “Spaces”: Standardized single Support Pipeline for all urgent, structured operational support requests (ingested from support@ or support web forms, or manually escalated from office@ threads by triage admins). Front Office agents focus on their specific location tickets using a dedicated Help Desk “Space” named “Front Office”, which provides dedicated views, sidebars, and routings for their managed locations without duplicating pipelines.
The Prospecting Workspace & Leads Object (Sales Hub Pro): Dedicated exclusively to active, high-priority pre-sale lead flow (B2C Contacts associated with pre-existing franchise Company records geographically). Reps track progress here with a clear, singular goal: Follow up, Connect, and Book an Evaluation (all post-eval payment and client management remains in PocketSuite).

📂 2. Current Drag State Analysis (Source System)

Telemetry parsed and verified from drag-dump-clean.json and UI schemas:

A. Core Active Boards

Board - FO (Front Office): The primary operating board where triage occurs.
office’s Inbox: The general ingestion pool containing raw inbound traffic and heavy spam.

B. Board Lane Configuration (Lanes)

To Do (Inbox / Triage stage)
Doing (Active administration / responses)
Done (Resolved / Archived)

🏗️ 3. Phase 1: Sandbox & Dev Email Ingestion Setup

This phase is executed at the very beginning of the project. We establish sandbox email channels to allow full end-to-end testing of the HubSpot environment during development, long before cutting over live customer traffic.

A. Sandbox & Dev Email Setup Protocol

Create Dev/Sandbox Email Aliases: Establish test aliases (e.g., [email protected] or [email protected]) in your Google Workspace Admin Console.
Connect to HubSpot Conversations: Link these test aliases to the HubSpot Shared Inbox.
Map to Location Group Emails: Add the test/dev email aliases to one or two location group email lists. This ensures we can generate real-world multi-alias inbound routing scenarios for dry-runs.
Verify Routing & Spam Filtering: Verify that:
- Inbound test emails land in the Shared Inbox as threads.
- Clicking “Create Ticket” manually on a thread properly escalates it to the Support Pipeline under the “Front Office” Space.
- Replies sent from HubSpot successfully utilize “Send-As” permissions for the test aliases.

🏗️ 4. Phase 2: HubSpot CRM Layout, Custom Properties, & Company Parent-Child Rollups

By setting up custom properties and the physical company parent-child relationships first, we establish a clean database baseline. This phase is executed immediately without waiting for any script or live cutover.

A. Core Custom Properties

We deploy 4 custom properties on standard Contact records to track PocketSuite metadata:

PS Client ID (pocket_suite_client_id): Single-line text.
PS Location ID (pocket_suite_location_id): Single-line text.
PS Location URL (pocket_suite_location_url): URL.
PS Lead Source (pocket_suite_lead_source): Single-line text.

And two custom Contact properties to track PocketSuite outreach and connections without bloated activity logging:

PS Outreach Sent (ps_outreach_sent): Boolean or Date/Timestamp, updated when outreach occurs in PocketSuite.
PS Connection Established (ps_connection_established): Boolean or Date/Timestamp, updated when an active call or dialogue happens in PocketSuite.

B. The CRM Relationship Schema: B2C Location Association (Pre-Established)

The Dog Wizard is a B2C franchise. Standard contacts are clients, and the branches represent franchise territories:

Contact-Only Client Creation: Standard HubSpot Contact records are created for incoming clients. We do not generate new customer Company records.
Franchise Location Company Association: All contacts are automatically associated with the pre-established franchise Company record (e.g., “The Dog Wizard - Coronado”, “The Dog Wizard - Clayton”) representing the local franchise entity.
Parent-Child Hierarchy for ALL Locations:
- The Standard Rollup: The corporate parent entity (“The Dog Wizard HQ”, ID 55554430014) is established as the Parent Company, and all individual franchise locations are added as Child Companies. This utilizes HubSpot’s native out-of-the-box rollup engine, allowing clean corporate rolled-up reporting.
- Front Office Tagging: To segment Chelsea’s specific front-office client pool, we tag managed branch Company records with a custom checkbox property: Managed by Front Office = True. This lets the Front Office team filter views without breaking the unified database.
Access Restrictions & Owner Assignment:
- HQ Employee Boundary: The HQ HubSpot account is strictly restricted to HQ and Front Office employees. Local branch managers and franchise owners have no login access to HubSpot.
- Contact/Company Ownership: Because local owners do not have access, only the Front Office team will own the Company or associated Contact/Lead relationships in HubSpot.

C. Company Mapping & Record ID Alignment

To resolve unmapped branch company records and establish the parent-child company hierarchy:

Export Companies CSV: Export the complete HubSpot Companies list in CSV format (including names, domains, and Record IDs).
Record ID Alignment: Match the unmapped Drag locations (Coronado, Clayton, Castlerock, etc.) to their existing Company Record IDs in HubSpot.
HQ Rollup Association: Programmatically or via bulk import, update all franchise Company records with the parent Company ID of “The Dog Wizard HQ” (55554430014) and set Managed by Front Office = True for the locations managed by the front office.

🛡️ 5. Phase 3: Geographic Custom Object Routing & Lead Generation (HubSpot Native Workflows)

Rather than paying for expensive multi-step Zaps and complex middleware logic, we offload all geographic custom object lookup, record association, and Sales Lead generation to HubSpot Native Workflows. This provides a zero-maintenance, zero-cost, and highly reliable architecture.

graph TD
    InboundGeneral[General Inbound: office@, ashland@, etc.] --> HSInbox[HubSpot Shared Inbox Conversations]
    HSInbox -->|Triage: Keep in Inbox, No Auto-Ticket| ConversationThread[Conversational Threads]
    ConversationThread -->|Urgent Support Needed| ManualTicket[Manually Create Ticket]
    
    InboundSupport[Support Intake: support@, Web Forms] -->|Auto-Create Ticket| SupportPipeline[Support Pipeline]
    ManualTicket --> SupportPipeline
    
    SupportPipeline -->|Help Desk Space: "Front Office"| FrontOfficeView[Front Office Team: Dedicated View/Sidebar]
    SupportPipeline -->|Help Desk Space: Tech Support| TechSupportView[Tech Support Team: Dedicated View/Sidebar]

    PocketSuite[Pocket Suite Leads] -->|Zapier Integration: Single Lean Step| HSCRM[Find or Create Contact in HubSpot]
    HSCRM -->|HubSpot Native Workflow: Free!| GeoMatch[Geographic Custom Object Association Lookup]
    GeoMatch -->|Auto-Associate| CompanyLocation[Established Franchise Location Company Record]
    GeoMatch -->|Auto-Generate Lead| HSLeads[Sales Hub Pro: Leads Object]
    HSLeads -->|Lanes| ProspectWorkspace[New -> Attempting -> Connected -> Qualified]

A. The Geographic Association Workflow (Native HubSpot)

When a Contact’s zip code is created or updated:

Workflow Trigger: Contact Zip Code/Postal Code is known.
Custom Object Lookup: Query the custom Zip Codes object records matching the Contact’s zip code.
Traverse Associations: Locate the parent Territory custom object record associated with that Zip Code, and then retrieve the associated franchise branch Company ID.
Auto-Associate: Automatically create the association between the Contact record and the resolved branch Company record.

B. Lead Object Creation Workflow (Native HubSpot)

When a high-priority contact is identified from PocketSuite:

Workflow Trigger: Contact property PS Client ID is known.
Action (Create Lead): Programmatically generate an active Lead record inside the Prospecting Workspace.
Association: Automatically associate the Lead with both the Contact and the geographically resolved franchise branch Company record.
Stage Placement: Initialize the Lead stage to New.

C. Shared Inbox vs. Help Desk: “Front Office” Space Triage

To keep HubSpot clean and prevent a massive influx of system emails, group list updates, and transactional vendor emails from flooding your ticketing system:

Disable Auto-Ticketing on General Inbound: Standard group aliases (office@, ashland@, etc.) route into the Shared Inbox with Auto-Ticket Creation turned OFF.
Triage to Central Support Pipeline: If an email is triaged and identified as an urgent customer operational issue, the front office admin manually clicks “Create Ticket” on the conversation.
Support Pipeline & “Front Office” Space:
- Operational tickets reside in the standard, pre-existing Support Pipeline.
- We configure the native Help Desk Space named “Front Office” to provide Chelsea’s team with dedicated ticket views, custom right sidebars showing relevant location-specific attributes, and custom routing rules filtered specifically for the franchise locations managed by the Front Office (Managed by Front Office = True).
- This allows the Front Office team to see and resolve only their operational tickets, while the central system keeps a single source of truth for support metrics.

🔄 6. Phase 4: Pocket Suite & Quo Integration Setup (Zapier & Native)

We establish direct integrations with PocketSuite and Quo to automate Lead stage progression based on client activity.

A. PocketSuite to Zapier Lean Ingestion

To keep Zapier costs low and avoid inflating task usage, the Zapier workflow ends immediately after contact creation:

Trigger: New Client created in PocketSuite (or Booking created/updated for Evaluations).
Action 1 (Formatter): Normalize the phone number to strict E.164 format (e.g., +11234567890). This is a critical requirement so that Quo activity logging matches flawlessly.
Action 2 (Find/Create Contact): Find or Create the Contact record in HubSpot based on email or normalized phone number.
Action 3 (Write Fields): Write the email, phone, zip code, and the 4 custom PS properties (pocket_suite_client_id, pocket_suite_location_id, etc.) to the Contact.
Zapier Ends Here (No associations or lead creation steps).

B. Quo (OpenPhone) Integration Mechanics

We re-enable the official Quo-HubSpot Integration:

Contact Match Criteria: Quo matches activities strictly by phone number or email address.
Timeline Logging: Calls and SMS messages executed in Quo are natively logged directly onto the HubSpot Contact timeline.

C. Lead Stage Automation Workflow (HubSpot Native)

High-priority leads in the Prospecting Workspace automatically progress based on activity logs and Contact properties.

Lead Stage: New
- Set when the Lead is initially created natively in HubSpot.
Lead Stage: Attempting
- Trigger A: SMS activity is logged on the Contact (e.g., natively via Quo integration), OR
- Trigger B: Contact property PS Outreach Sent is updated/True (via PocketSuite webhook).
- Action: Advance Lead stage to Attempting (if necessary, even with native HubSpot settings for pipeline automation).
Lead Stage: Connected
- Trigger A: Call activity is registered on the Contact timeline (e.g., natively via Quo integration), OR
- Trigger B: Contact property PS Connection Established is updated/True (via PocketSuite webhook).
- Action: Advance Lead stage to Connected (if necessary, even with native HubSpot settings for pipeline automation).
Lead Stage: Qualified
- Trigger: Evaluation booking is registered in PocketSuite (updating Contact record).
- Action: Advance Lead stage to Qualified. Deal generation is completely disabled.

⚙️ 7. Phase 5: Programmatic Data Migration & Historical Sync

To sync historical Drag labels and team owners, we run programmatic data sync scripts using HubSpot’s V3 APIs.

A. Drag Metadata Migration Script

Below is the core Node.js migration handler that runs in the workspace to sync historical Drag labels and team owners to HubSpot. It is updated to match Drag conversations to existing Contacts using normalized E.164 phone numbers and associate them with their respective Franchise Companies.

// ~/projects/03_clients/dogwizard/drag-migration/drag-migration.js
const fs = require('fs');
const axios = require('axios');
 
const HUBSPOT_ACCESS_TOKEN = process.env.HUBSPOT_ACCESS_TOKEN;
const CLEAN_JSON_PATH = './drag-dump-clean.json';
 
const hsClient = axios.create({
  baseURL: 'https://api.hubapi.com/',
  headers: {
    'Authorization': `Bearer ${HUBSPOT_ACCESS_TOKEN}`,
    'Content-Type': 'application/json'
  }
});
 
async function migrateDragMetadata() {
  console.log("Loading cleaned Drag metadata dump...");
  const rawData = fs.readFileSync(CLEAN_JSON_PATH, 'utf8');
  const dump = JSON.parse(rawData);
 
  // 1. Extract Labels/Tags from the sharedLabel/all API response
  const labelResponse = dump.responses.find(r => r.url.includes('sharedLabel/all'));
  if (labelResponse && labelResponse.response) {
    const labels = JSON.parse(labelResponse.response).list;
    console.log(`Found ${labels.length} historical Drag labels. Syncing taxonomy to HubSpot properties...`);
    
    for (const label of labels) {
      console.log(`Syncing Drag Label: "${label.Name}" (Board: ${label.BoardName})`);
    }
  }
 
  // 2. Extract Team Members / Board Invitations to map owners
  const invitationResponse = dump.responses.find(r => r.url.includes('teamBoard/invitation/list'));
  if (invitationResponse && invitationResponse.response) {
    const members = JSON.parse(invitationResponse.response);
    console.log(`Found ${members.length} team members associated with Drag boards:`);
    members.forEach(member => {
      console.log(` - User: ${member.Name} (${member.InviteEmail || member.UserEmail})`);
    });
  }
 
  console.log("Migration metadata synchronization complete!");
}
 
migrateDragMetadata().catch(console.error);

🏗️ 8. Phase 6: Google Workspace Infrastructure Cutover (Go-Live)

This phase represents the very end of the project. We will not route live mail to HubSpot until the CRM, custom properties, and Zapier pipelines have been completely built, tested, and verified using our sandbox setup.

A. The Live Cutover Protocol (Final Step)

Once all sandbox tests are 100% successful, we execute the go-live cutover:

Backup & Archival: Log in to Google Admin Console (admin.google.com). Navigate to Users > [email protected]. Run a Google Takeout export or use the Google Data Migration Tool to archive all historical emails to an archival inbox (e.g., [email protected]).
Rename Old Mailbox: Rename the [email protected] user account to [email protected].
Create Live Google Group: Immediately create a new Google Group with the email address [email protected] so that external senders hitting the address do not bounce. Set access to Public (External Senders can post).
Add Forwarding Routing: Add the HubSpot fallback ingestion address ([unique-id]@inbox.hubspot.com) and team backup emails as members of the new group.
Verify Live Performance: Confirm that live inbound emails stream into HubSpot, and then deprovision/delete the office-temp user mailbox to save licensing costs.

🏁 9. Technical Validation Checklist

Phase 1: Sandbox & Dev Email Setup

Create test/sandbox email aliases in Google Workspace Admin.
Connect sandbox aliases to HubSpot Shared Inbox.
Add sandbox aliases to location group email lists for testing.
Verify thread routing, manual ticket creation, and outbound Send-As capabilities in the sandbox.

Phase 2: HubSpot CRM Setup, Custom Properties, & Rollups

Phase 3: HubSpot Native Geographic Routing & Leads Workflows

Build geographic custom object lookup and auto-association workflow (Zip Code ➡️ Territory ➡️ Franchise Company) inside HubSpot.
Build Lead creation workflow inside HubSpot (creates Lead in New stage when Contact has PS Client ID).

Phase 4: Pocket Suite & Quo Integration Setup (Zapier & Native)

Re-enable official HubSpot-Quo integration.
Build a single-action Zapier workflow to trigger on new Client in PocketSuite, formatting phone numbers to strict E.164 and writing them directly to the Contact record.
Setup HubSpot Lead Stage Automation Workflow to auto-update Lead stage to Attempting on SMS activity/property, and Connected on Call activity/property (if necessary, even with native HubSpot settings for pipeline automation).

Phase 5: Programmatic Data Migration

Execute programmatic data migration script (drag-migration.js) to sync historical Drag labels and team owners to HubSpot.

Phase 6: Go-Live Cutover (End of Project)

Complete Google Takeout / archive backup of [email protected] user mailbox.
Rename the office@ user account to office-temp@ in Admin Console.
Create Google Group named [email protected] with Public (External Senders) access enabled.
Add HubSpot Fallback email address ([id]@inbox.hubspot.com) and team members as members of the new group.
Confirm live inbound/outbound routing passes flawlessly, and safely deprovision/delete the office-temp@ user mailbox.

Quartz 5

Explorer

drag-to-hubspot-blueprint