Overview

This case study uses a real-world HubSpot–Salesforce integration to demonstrate a framework for organising Salesforce diagrams and solution architecture documentation. The approach combines both system-centric and process-centric perspectives, to tailor to different stakeholders. I’ve referenced ****my metadata dictionary template which now includes a Systems Interactions Database that creates a single source of truth for integration specifications and their related business processes.

Built on the Salesforce Well-Architected framework, the case study includes the **following Salesforce Diagrams Components:

System Capability Map** establishing strategic context 2. System Landscape Diagrams showing integration relationships 3. Solution Architecture Specifications detailing technical implementations
Interaction Flow Diagrams connecting solutions to business processes

</aside>

The Documentation Challenge in Enterprise Salesforce Architecture

The latest Salesforce Architect Report (2025) from SalesforceBen positions diagramming as the most critical skill for solution architects, a recognition that visual communication has become fundamental to our practice. Yet, my experience has been that most companies and Salesforce teams suffer from the same documentation challenges: technically accurate diagrams that fail to serve their primary purpose of enabling decision-making and ends up becoming outdated.

SF Ben Salesforce Architect Survey Results 2025: Download Now! | Salesforce Ben

The Salesforce Well-Architected Framework provides essential foundational guidance on diagram types: Capability Maps, System Landscapes, Solution Architectures, and Interaction Flows. However, it provides no guidance in three critical components that distinguish between documentation that exists versus documentation that is used:

Organisational Methodology: No systematic approach to structure relationships between diagram types
Contextual Navigation: Insufficient guidance on drill-down architectures that serve multiple stakeholder perspectives
Maintenance Strategy: Lack of integration with metadata management practices that ensure long-term documentation accuracy.

Salesforce Architects | How to Build Salesforce Diagrams

This case study presents a metadata-(dictionary) driven organisational framework that addresses these gaps while preserving the Well-Architected Foundation's conceptual strengths.

Architectural Documentation Frameworks: System-Centric vs Process-Centric

Most enterprise documentation follows usually a system-centric approach (organising around technical components) at the expense of a process-centric approach (organising around business workflows). This creates an artificial separation that can force architects to optimise for technical audiences over business stakeholders.

The Well-Architected Framework's diagram repository demonstrates this limitation. While technically comprehensive, the examples from their diagram repository favour system-centric perspectives, making them less accessible to business stakeholders who ultimately are those making architectural decisions (such as technology providers or business rules definition).

Salesforce Architects

Proposition for a Unified Approach: Dual-Perspective Architecture Documentation

Could the solution lies not in choosing between framework, but in designing documentation architectures that serve both perspectives simultaneously? This would require:

System-Centric Foundation: Stable technical artefacts that capture integration patterns, data flows, and dependency relationships
Process-Centric Visualisation: Dynamic views that presents system-centric information according to business rules and workflows
Metadata Linkage: Structured connections that maintain consistency between perspectives without duplication

Case Study: A Complex HubSpot-Salesforce Integration

This case study analyses a real-world scenario adapted for clarity and instructional value.

</aside>

Case Overview

<aside> 🔎

The system capability map below highlights a critical architectural component: HubSpot appears across multiple capabilities and business units, indicating its evolution from departmental tool to cross-company strategic application.

This illustrates the evolution of marketing processes into a pillar of modern RevOps processes. As a result, marketing automation platforms like HubSpot now serves as integration hubs rather than isolated functional tools.

</aside>

Untitled