GHL Architect

Documentation Lookup Strategy

1. Built-in references first — check this skill's reference files
2. Context7 for unknowns — if the topic isn't covered or may be outdated, use Context7:

   Context7:resolve-library-id → libraryName: "GoHighLevel"
   Context7:query-docs → query: "<specific question>"
   

3. web_search fallback — if Context7 is unavailable, search marketplace.gohighlevel.com/docs/ and help.gohighlevel.com
4. Inform the user — flag when info came from web search vs. built-in reference

Architecture Decision Framework

When a user asks to build something in GHL, follow this decision sequence:

1. Threat Model First

Before designing any workflow, API integration, or customization:

• What data flows through this system? (PII, financial, health — triggers compliance requirements)
• Who has access? (Map roles → minimum required permissions)
• What happens if this breaks? (Identify blast radius, design rollback)
• What external systems touch this? (Each integration = attack surface)

2. Choose the Right Integration Pattern

3. Security-by-Design Checklist

Every GHL implementation should satisfy these before going live:

Authentication & Authorization

• OAuth2 tokens or Private Integration Tokens (PITs) used — NOT legacy API keys
• If OAuth2: token refresh flow automated (tokens expire ~24hrs — handle gracefully)
• If PIT: token stored securely and rotation scheduled (PITs don't expire but are long-lived credentials)
• Minimum required scopes selected (least privilege)
• Webhook signatures verified on every inbound webhook
• API credentials stored in environment variables or vault (never in workflow JSON)
• Sub-account access scoped to location (no agency-wide tokens for location-specific work)

Data Protection

• PII fields identified and tagged in custom field taxonomy
• Data retention policy configured (especially for Loi 25 / PIPEDA compliance)
• Contact deletion workflow supports DSAR (Data Subject Access Request) automation
• Webhook payloads don't leak sensitive data to unnecessary endpoints
• Conversation/call recordings have documented retention and access controls

Workflow Security

• No hardcoded credentials in workflow actions or custom webhook bodies
• Error branches exist on every workflow (failures don't silently drop contacts)
• Workflow-per-stage architecture prevents contacts from being in multiple active sequences
• Rate limits respected (200k/day/location) with backoff logic in external integrations
• Test contacts use a dedicated tag — never production data in test workflows

Audit & Monitoring

• Webhook delivery failures monitored (GHL retries 3x then drops)
• API error rates tracked (429s, 401s, 500s)
• Workflow execution logs reviewed on a schedule
• Contact tag changes logged for compliance audit trail

Core Platform Concepts

API Architecture (v2)

• Base URL: https://services.leadconnectorhq.com
• Auth: OAuth2 Bearer token or Private Integration Token (PIT), with Version: 2021-07-28 header
• Rate Limits: 200,000 requests/day/location AND 100 requests/10 seconds (burst). Both limits apply — the burst limit often bites first in batched operations.
• Pagination: Cursor-based (startAfter parameter), max 100 per page
• Scopes: Granular per resource (contacts, opportunities, calendars, conversations, etc.)
• V1 Deprecation: V1 APIs are end-of-support. All new integrations must use V2 with OAuth2 or PITs.

Workflow Engine

GHL's visual workflow builder supports triggers (form submit, tag added, pipeline stage change, appointment events, custom webhook inbound) and actions (send SMS/email, add tag, create opportunity, HTTP webhook out, conditional branch, wait, math operations on custom fields).

Key constraint: Workflows are per-location (sub-account). Agency-level automation requires cross-location patterns — see references/agency_governance.md.

Custom Fields & Values

Custom fields are the backbone of any serious GHL implementation. They store lead scores, lifecycle stages, compliance flags, and integration sync IDs.

Field types: text, number, date, dropdown, checkbox, textarea, phone, monetary, file upload.

Naming convention (enforced in this skill):

{domain}_{entity}_{attribute}

Examples:

• security_consent_date — when the contact gave marketing consent
• integration_n8n_sync_id — unique ID for n8n dedup
• scoring_lead_score — behavioral lead score
• compliance_dsar_requested — DSAR flag for Loi 25

Webhook Architecture

GHL supports both inbound (external → GHL via Custom Webhook trigger) and outbound (GHL → external via Custom Webhook action) webhooks.

Outbound webhook payloads include contact data plus trigger-specific data (appointment, opportunity, etc.). The payload structure uses {{contact.field}} template variables — see references/api_reference.md for full payload schemas.

Inbound webhooks require the workflow to have a Custom Webhook trigger, which generates a unique URL. External systems (n8n, Zapier) POST JSON to this URL to trigger the workflow.

Quick-Reference Patterns

Pattern: Secure Webhook Pipeline (GHL → n8n)

GHL Workflow Trigger (e.g., Opportunity Stage Change)
  ↓
Custom Webhook Action → POST to n8n webhook URL
  Headers: X-GHL-Signature (Ed25519 — see security_patterns.md)
  Body: { contact, opportunity, location, timestamp }
  ↓
n8n Webhook Node receives POST (native webhook auth or header validation)
  ↓
n8n Code Node: Process payload (no crypto in v2.0 sandbox — signature verified at webhook level)
  ↓
n8n processes data (enrich, route, sync to external system)
  ↓
(Optional) n8n HTTP Request → GHL API to update contact/tag

Pattern: Idempotent Contact Sync (n8n → GHL)

n8n receives data from external source
  ↓
Generate deterministic sync_id (hash of source + external_id)
  ↓
GHL API: Search contact by custom field "integration_n8n_sync_id"
  ↓
If exists → PUT /contacts/{id} (update)
If not → POST /contacts/ (create with sync_id in custom fields)
  ↓
Log operation for audit trail

Pattern: DSAR Automation (Loi 25 / PIPEDA)

GHL Form: "Data Access Request" submitted
  ↓
Workflow: Tag contact "compliance_dsar_pending"
  ↓
Custom Webhook → n8n
  ↓