Pitcher Platform - Complete Architecture Documentation

Overview

Pitcher is a comprehensive sales enablement platform with deep CRM integration, content management, and extensibility through apps. This document covers ALL components, their relationships, and how they work together.

Architecture Overview - Simplified architecture documentation focusing on core components
Architecture Diagrams - Visual diagrams and data models
Pitcher Apps Deep Dive - Detailed guide to the app extensibility system

Complete Architecture Diagram

📦 Component Deep Dive

1. 🎨 Canvases (Presentations)

The heart of Pitcher - interactive sales presentations.

Structure:

typescript

Canvas {
  id: string
  name: string
  content: ComponentNode[]      // Pages with components
  sections: Section[]           // Embedded reusable sections
  template?: Canvas             // Source template
  account?: Account             // CRM context
  events: Event[]               // Presentation sessions
  shared_link?: SharedLink      // Public sharing
  metadata: object              // Custom fields
  tags: string[]                // Categorization
  theme: object                 // Visual styling
  access_type: 'public' | 'restricted' | 'personal'
  folder_id: string
}

Component Types:

Text - Rich text with formatting
Image - Static images from Files
Video - Video players from Files
PDF Viewer - Embedded PDFs with annotations
Section List - Container for Sections
App Embed - Embedded applications
Page Break - Slide separators
Scribble/Drawing - Interactive whiteboard
Data Tables - Structured data display
Charts - Data visualizations

2. 🔌 Apps & Extensions - THE EXTENSIBILITY LAYER

Apps are the plugin system that makes Pitcher infinitely extensible. They can be embedded in various "locations" throughout the platform.

📖 For a comprehensive guide to building apps, see the Pitcher Apps Deep Dive

App Structure

typescript

AppJson {
  name: string                    // Unique identifier
  display_name: string            // Human-readable name
  icon: string                    // App icon URL
  version: string                 // Semantic version
  description: string             // What does it do?
  type: 'web'                     // App type (currently only web)

  // What capabilities does this app provide?
  provide: [
    'ui',                         // Standalone UI app
    'account_browser',            // CRM account browser
    'scheduler',                  // Meeting scheduler
    'postcall',                   // Post-call forms
    'crm_shape',                  // CRM data shapes
    'multimedia_selector'         // File/media picker
  ]

  // What does this app require?
  require: ['crm']                // Dependencies (e.g., needs CRM)

  // Module definitions for different embed locations
  module: {
    ui_app: Module                // Standalone app
    canvas: Module                // Embedded in canvas
    overlay_app: Module           // Modal opened from global search
    admin_instance: Module        // Admin panel
    canvas_section_execution: Module  // Section-level
    dsr: Module                   // Digital sales room
    // ... more locations
  }
}

App Embed Locations (Modules)

Each app can have different "modules" - versions of itself that work in different contexts:

1️⃣ UI App (`ui_app`)

Standalone full-screen application accessible from main navigation.

Examples:

Account browser (CRM data viewer)
Meeting scheduler
Content library
Analytics dashboard
Admin tools

Configuration:

typescript

{
  enabled: true,
  entry: 'index.html',
  headless: false,          // Has UI
  auto_install: true,       // Auto-available when app installed
  defaults: {
    dimensions: { width: '100%', height: '100vh' }
  }
}

2️⃣ Canvas App (`canvas`)

Embedded directly inside canvas presentations as a component.

Examples:

Interactive product configurators
ROI calculators
Pricing tools
3D model viewers
Live data dashboards
Forms and surveys

Configuration:

typescript

{
  enabled: true,
  entry: 'canvas.html',
  defaults: {
    dimensions: { width: '800px', height: '600px' },
    settings: {
      // App-specific configuration
      apiKey: 'from-settings',
      theme: 'light'
    }
  },
  shortcuts: {
    // Toolbar buttons in different modes
    fullscreen: [{ id: 'refresh', icon: 'refresh', tooltip: 'Refresh data' }],
    presentation: [{ id: 'settings', icon: 'settings' }],
    edit: [{ id: 'configure', icon: 'configure' }]
  }
}

3️⃣ Overlay App (`overlay_app`)

Opens in a modal over the app shell when launched from a global search result.

Configuration:

typescript

{
  enabled: true
}

Popup placement and per-mode visibility (app_options.placement, app_options.mode_config) are top-level manifest keys read only for popup app_types (canvas-popup, ui-global-popup), not overlay_app settings.

4️⃣ Admin Instance (`admin_instance`)

Extensions to the admin panel for configuration and management.

Examples:

CRM sync configuration
Custom metadata field managers
User management extensions
Analytics viewers
License management

5️⃣ Canvas Section Execution (`canvas_section_execution`)

Opened per section from a SectionList in collapsibles mode: a status button next to each section opens the app in a modal.

Examples:

Section-specific analytics
Dynamic content loading
Interactive quizzes per section
Section engagement tracking

6️⃣ Canvas Drawer (`canvas_drawer`)

Side panel that opens during canvas viewing/editing.

Examples:

File browser
Asset library
Template selector
Version history

App Settings & Configuration

Apps can define custom settings that users configure per instance:

typescript

{
  settings: {
    sections: [
      {
        label: 'API Configuration',
        fields: [
          {
            type: 'text',
            name: 'api_key',
            label: 'API Key',
            help_text: 'Your API key from the provider',
            is_required: true
          },
          {
            type: 'select',
            name: 'environment',
            label: 'Environment',
            options: [
              { label: 'Production', value: 'prod' },
              { label: 'Sandbox', value: 'sandbox' }
            ]
          },
          {
            type: 'checkbox',
            name: 'enable_logging',
            label: 'Enable Debug Logging'
          }
        ]
      }
    ]
  }
}

Field Types:

text - Text input
checkbox - Checkbox
select - Dropdown
multi-select - Multiple selection
number - Numeric input
date - Date picker
html - HTML content

App Communication (Pitcher SDK)

Apps use the Pitcher JavaScript SDK to interact with the platform:

typescript

import { useApi } from '@pitcher/js-api'

const api = useApi()

// Get platform info
const env = await api.getEnv()
// { mode: 'WEB' | 'IOS' | 'MACOS' | 'WINDOWS' | 'ANDROID', pitcher: { user, instance, access_token, ... } }
// WEB = browser; every other mode is a native shell — use isNativeHost(env.mode), never mode === 'IOS', unless you mean iPad hardware

// Open files
await api.open({ fileId: 'file-123' })

// Open canvas in overlay (UI API and admin API only)
await api.openCanvasOverlay({ id: 'canvas-456', fullscreen: true })

// CRM integration (SOQL queries via jsforce)
const result = await api.crmQuery({
  query: 'SELECT Id, Name FROM Account LIMIT 10'
})
console.log(result.records)

// Data persistence (AppsDB, localStorage or REST API)
await api.appsDbUpsertEntry({ type: 'myapp-data', data: { key: 'value' } })

// Broadcast events (multipeer connectivity on iOS)
api.broadcast({
  type: 'CUSTOM_EVENT',
  body: { customData: 'value' }
})

// Listen to events
api.on('canvas_opened', (data) => {
  console.log('Canvas opened:', data.body.canvas_id)
})

App Distribution

Apps are packaged as Files in the system:

Upload - ZIP file containing app code (HTML/JS/CSS)
Manifest - app.json defining capabilities and modules
Installation - Install app to Instance
Configuration - Admin configures app settings
Usage - Users access app in defined locations

App File Structure:

my-app.zip
├── app.json              # Manifest
├── index.html            # UI App entry
├── canvas.html           # Canvas module entry
├── overlay.html          # Overlay module entry
├── assets/
│   ├── icon.png
│   └── ...
└── js/
    └── app.js

Collaboration

Share content with users or groups with specific roles.

typescript

Collaboration {
  id: number
  file?: File               // Share a file
  folder?: Folder           // Share a folder
  canvas?: Canvas           // Share a canvas
  user?: User               // Share with user
  content_distribution_group?: ContentDistributionGroup  // Share with group
  role: 'viewer' | 'editor' | 'owner'
}

Use Cases:

Share presentation with sales team (editor access)
Distribute content to regional teams (via CDG)
Collaborate on canvas editing

Content Distribution Groups (CDG)

Groups of users for bulk content distribution.

typescript

ContentDistributionGroup {
  id: string
  name: string                  // e.g., "West Coast Sales Team"
  size: number                  // Member count
  auto_add_new_users: boolean   // Auto-add new instance users
  members: User[]
}

Features:

Share once to entire group
Auto-enrollment for new hires
Managed by admins

Shared Links

Public URLs for external sharing without login.

typescript

SharedLink {
  url: string                   // Full URL
  short_url?: string            // Shortened version
}

Attached to:

Canvases (share presentation externally)
Files (share documents publicly)

4. 📊 Metadata & Organization

Metadata Templates

Define custom structured fields for files.

typescript

MetadataTemplate {
  id: string
  instance: Instance
  file?: File                   // Attached to which file
  sections: [
    {
      label: 'Product Information',
      fields: [
        {
          type: 'text' | 'number' | 'date' | 'select' | 'multi-select' | 'checkbox' | 'html',
          name: 'product_category',
          label: 'Product Category',
          is_required: true,
          options: [...]
        }
      ]
    }
  ]
}

Usage:

Organize files with custom fields (Product, Region, Department, etc.)
Filter and search by metadata
Bulk update metadata across files

5. 🔗 Connected Services (CRM Integration)

Note: CRM integration is optional and available upon request. Organizations can use Pitcher fully without CRM connectivity.

typescript

ConnectedService {
  connection_id: string         // Unique connection ID
  type: string                  // 'crm' for CRM connections
  name: string                  // User-friendly name
  provider: string              // 'salesforce' or 'microsoft' (Dynamics)
  access_token: string          // OAuth token
  user_id: string               // External user ID
  urls: Record<string, string>  // CRM URLs: query, profile, sobjects, rest,
                                // custom_domain, api_url, resource_uri, instance_url
}

Capabilities (when enabled):

Authenticate with CRM via OAuth
Sync Accounts, Contacts, Events
Link External Objects to Pitcher entities
Bi-directional data sync

External Objects

Link Pitcher entities to CRM records.

typescript

ExternalObject {
  content_type: 'account' | 'event' | 'opportunity' | 'other'
  connection_id: string         // Which CRM connection
  external_content_type: string // e.g., 'Account', 'Lead'
  external_object_id: string    // CRM record ID
  name: string
  description: string
}

Examples:

Link Event to Salesforce Event
Link Account to Salesforce Account
Link Canvas to Salesforce Opportunity

6. 📈 Analytics

File Analytics

Track file usage and engagement.

typescript

FileAnalytics {
  file_id: string
  views: number                 // Total views
  unique_viewers: number        // Unique users
  average_duration: number      // Avg view time
  downloads: number
  shares: number
  period: '7d' | '30d' | '12w'
}

Instance Analytics

Overall instance usage metrics.

typescript

InstanceAnalytics {
  instance_id: string
  current_period: {
    total_presentations: number
    total_files_viewed: number
    active_users: number
    top_files: FileAnalyticsResult[]
  }
  change_percentages: {
    presentations: number       // % change vs previous period
    file_views: number
    active_users: number
  }
  inactive_users: User[]       // Users who haven't logged in
}

🔄 Complete Data Flow Examples

Example 1: Product Launch Campaign

Example 2: Custom CRM Integration via App

🗂️ File System Hierarchy

Organization
└── Instance (Workspace)
    ├── Root Folder
    │   ├── Sales Materials/
    │   │   ├── Product Presentations (canvas)
    │   │   ├── Brochures (files)
    │   │   └── Videos (files)
    │   ├── Marketing/
    │   └── Training/
    ├── Personal Files Folder (per user)
    │   └── My Drafts/
    ├── Personal Canvases Folder (per user)
    │   └── My Presentations/
    └── Canvas Templates Folder
        ├── Standard Pitch Template
        ├── Product Demo Template
        └── Quarterly Review Template

🎯 Summary

Pitcher is a comprehensive sales enablement ecosystem where:

Core Components

Canvases = Interactive presentations
Files = Content (PDFs, media)
Sections = Reusable content blocks
Templates = Reusable structures

Extensibility

Apps = Infinite extensibility via embedded applications
SDK = Rich JavaScript API for app development
Modules = Apps work in multiple contexts (canvas, UI, overlays, admin)

Collaboration

Collaboration = Share with users/groups
Content Distribution Groups = Bulk distribution
Shared Links = Public access

CRM Integration

Connected Services = OAuth integration with CRMs
External Objects = Link Pitcher ↔ CRM records
Events = Tracked sales activities
Accounts/Contacts = Synced customer data

Organization

Metadata Templates = Custom structured fields
Tags = Categorization
Folders = Hierarchical organization
Instance Assignment Groups = User grouping

Insights

File Analytics = Content performance
Instance Analytics = Platform usage
Event Tracking = Presentation engagement

All orchestrated within Instances (workspaces) inside Organizations (tenants), creating a powerful, flexible, and deeply integrated sales platform! 🚀

Pitcher Platform - Complete Architecture Documentation ​

Overview ​

Related Documentation ​

Complete Architecture Diagram ​

📦 Component Deep Dive ​

1. 🎨 Canvases (Presentations) ​

2. 🔌 Apps & Extensions - THE EXTENSIBILITY LAYER ​

App Structure ​

App Embed Locations (Modules) ​

1️⃣ UI App (ui_app) ​

2️⃣ Canvas App (canvas) ​

3️⃣ Overlay App (overlay_app) ​

4️⃣ Admin Instance (admin_instance) ​

5️⃣ Canvas Section Execution (canvas_section_execution) ​

6️⃣ Canvas Drawer (canvas_drawer) ​

App Settings & Configuration ​

App Communication (Pitcher SDK) ​

App Distribution ​

3. 🤝 Collaboration & Sharing ​

Collaboration ​

Content Distribution Groups (CDG) ​

Shared Links ​

4. 📊 Metadata & Organization ​

Metadata Templates ​

Tags ​

5. 🔗 Connected Services (CRM Integration) ​

External Objects ​

6. 📈 Analytics ​

File Analytics ​

Instance Analytics ​

🔄 Complete Data Flow Examples ​

Example 1: Product Launch Campaign ​

Example 2: Custom CRM Integration via App ​

🗂️ File System Hierarchy ​

🎯 Summary ​

Core Components ​

Extensibility ​

Collaboration ​

CRM Integration ​

Organization ​

Insights ​

Pitcher Platform - Complete Architecture Documentation

Overview

Related Documentation

Complete Architecture Diagram

📦 Component Deep Dive

1. 🎨 Canvases (Presentations)

2. 🔌 Apps & Extensions - THE EXTENSIBILITY LAYER

App Structure

App Embed Locations (Modules)

1️⃣ UI App (`ui_app`)

2️⃣ Canvas App (`canvas`)

3️⃣ Overlay App (`overlay_app`)

4️⃣ Admin Instance (`admin_instance`)

5️⃣ Canvas Section Execution (`canvas_section_execution`)

6️⃣ Canvas Drawer (`canvas_drawer`)

App Settings & Configuration

App Communication (Pitcher SDK)

App Distribution

3. 🤝 Collaboration & Sharing

Collaboration

Content Distribution Groups (CDG)

Shared Links

4. 📊 Metadata & Organization

Metadata Templates

Tags

5. 🔗 Connected Services (CRM Integration)

External Objects

6. 📈 Analytics

File Analytics

Instance Analytics

🔄 Complete Data Flow Examples

Example 1: Product Launch Campaign

Example 2: Custom CRM Integration via App

🗂️ File System Hierarchy

🎯 Summary

Core Components

Extensibility

Collaboration

CRM Integration

Organization

Insights