Pitcher Platform Architecture Documentation

Overview

Pitcher is a sales enablement platform organized into several interconnected components. This document explains the architecture, data models, and dependencies between different parts of the system.

Complete Architecture - Comprehensive documentation covering all components in detail
Architecture Diagrams - Visual diagrams and data models
Pitcher Apps Deep Dive - Detailed guide to the app extensibility system

Architecture Diagram

Key Relationships

Solid arrows (→): Direct containment or strong dependency
Dotted arrows (-.->): Reference or loose coupling
Content Layer: Core content management (folders, files, canvases)
CRM Layer: Customer relationship and activity tracking
Apps Layer: Extensibility and integrations

Component Details

1. Organization

Purpose: Top-level tenant/company entity

Properties:

Organization-wide settings
Branding and configuration
Multiple instances

Dependencies:

Contains: Instances, Apps
Manages: Users, Permissions

2. Instance (Workspace)

Purpose: Isolated environment/workspace within an organization

Properties:

Instance ID
Settings and configuration
Regional data storage
Environment (dev/staging/production)

Dependencies:

Belongs to: Organization
Contains: Folders, Files, Canvases, Events
Has: Users with roles (Admin, Editor, Member)

3. Canvases (Presentations/Slide Decks)

Purpose: Main presentation container - the core content delivery mechanism

Structure:

typescript

Canvas {
  id: string
  name: string
  content: ComponentNode[]  // Pages and components
  sections: Section[]       // Embedded sections
  template: Canvas          // Source template (if created from template)
  account: Account          // Associated CRM account
  events: Event[]           // Linked sales activities
  metadata: object
  tags: string[]
  is_template: boolean      // Is this a template?
  is_section: boolean       // Is this a section?
  is_block: boolean         // Is this a reusable block?
  folder_id: string
  theme: object
}

Canvas Types:

Canvas - Standard presentation
Template - Reusable canvas structure
Section Template - Reusable content blocks
Section - Content unit that can be embedded
Block - Small reusable component

Pages & Components:

Canvases contain pages (slides)
Pages contain components (text, images, videos, apps, section lists, etc.)
Special component: SectionList - displays sections within a page
PageBreak component - separates content into slides

Dependencies:

Located in: Folders
References: Files (for media content)
Uses: Templates (optional)
Contains: Sections
Linked to: Events, Accounts
Embedded: Apps

4. Sections

Purpose: Reusable content units that can be embedded in canvases

Properties:

typescript

Section {
  id: string
  name: string
  content: ComponentNode[]
  theme: object
  metadata: object
  is_draft: boolean
}

Use Cases:

Reusable product information
Standard slides across presentations
Dynamic content that updates across all canvases

Dependencies:

Embedded in: Canvases (via SectionList component)
Can be: Templates (Section Templates)

5. Files (Content)

Purpose: Media and document storage

File Types:

Content: PDFs, Images (JPG, PNG, WebP), Videos (MP4, WebM)
Assets: Fonts (TTF, WOFF), AR content (USDZ)
Apps: Embedded application packages

Properties:

typescript

File {
  id: string
  name: string
  type: 'content' | 'asset' | 'app'
  content_type: 'pdf' | 'image' | 'video' | 'ar' | 'font' | 'web'
  folder_id: string
  metadata: object
  tags: string[]
  status: 'pending' | 'viewable' | 'failed'
  download_type: 'automatic' | 'ondemand' | 'mandatory'
  access_type: 'public' | 'restricted' | 'personal'
}

Special Features:

PDF: PSPDFKit integration for annotations
Metadata: Custom fields for organization
Tags: Categorization and search
Revisions: Version history

Dependencies:

Located in: Folders
Referenced by: Canvases
Can be: App Files

6. Folders

Purpose: Hierarchical organization of content

Special Folders:

Root Folder (per instance)
Personal Files Folder
Personal Canvases Folder
Canvas Templates Folder

Properties:

Hierarchical structure (parent/child)
Breadcrumb navigation
File and folder counts
Access control (public/private)

Dependencies:

Contains: Files, Canvases, Sub-folders
Belongs to: Instance

7. Templates

Purpose: Reusable structures for creating new content

Template Types:

Canvas Templates - Full presentation templates
Section Templates - Reusable content blocks

How Templates Work:

A Canvas with is_template: true
Used as a blueprint for new canvases
New canvas references template via template field
Changes to template can optionally update instances

Dependencies:

Stored as: Canvases (with special flag)
Used to create: New Canvases/Sections

8. Apps (Extensions)

Purpose: Embedded applications that extend platform functionality

📖 For detailed information about apps, see the Pitcher Apps Deep Dive

App Structure:

typescript

App {
  name: string
  type: 'web'
  module: {
    ui_app: Module           // Standalone UI app
    canvas: Module           // Embedded in canvas
    overlay_app: Module      // Overlay on canvas
    admin_instance: Module   // Admin panel extension
    canvas_section_execution: Module  // Section-level app
    // ... other modules
  }
  provide: ['ui', 'scheduler', 'crm_shape', ...]
  require: ['crm']  // Dependencies
}

App Capabilities:

UI Apps: Standalone features (account browser, scheduler)
Canvas Apps: Embedded interactive content
CRM Integrations: Connect to external systems
Multimedia Selectors: Content pickers
Post-call Forms: Data capture after presentations

Dependencies:

Stored as: Files (app type)
Installed in: Instances
Embedded in: Canvases, Admin UI
Can integrate with: CRM systems

Related Guides:

App Types - Overview of different app module types
Getting Started - Build your first app
app.json Reference - Complete manifest specification

9. Events (Sales Activities)

Purpose: Track meetings, presentations, and customer interactions

Properties:

typescript

Event {
  id: string
  status: 'planned' | 'executed' | 'canceled'
  start_at: datetime
  end_at: datetime
  canvas: Canvas              // Associated presentation
  subject: string
  external_objects: ExternalObject[]  // CRM links
  attendees: Contact[]        // Meeting participants
  metadata: object
}

Presentation Tracking:

Tracks which canvas was presented
Records presentation history
Captures page/slide duration
Content ratings per page

Dependencies:

Links to: Canvases (presentation used)
Links to: Accounts (customer visited)
Includes: Contacts (attendees)
Syncs with: External CRM (Salesforce events)

10. Accounts (CRM Data)

Purpose: Customer/client information from external CRM

Note: CRM integration is optional and available upon request. The platform works fully without CRM connectivity.

Properties:

typescript

Account {
  id: string           // External CRM ID
  name: string
  // CRM-specific fields (from Salesforce, etc.)
}

Integration:

External systems: Salesforce, other CRMs (optional)
Linked to: Events (customer meetings)
Associated with: Canvases (customer presentations)
Contains: Contacts

Dependencies:

Synced from: External CRM systems
Associated with: Canvases, Events
Contains: Contacts

11. Contacts (People)

Purpose: Individual people from CRM

Properties:

Basic info (name, email, phone)
Associated with Accounts
Can be Event attendees

Dependencies:

Belongs to: Accounts
Participates in: Events

Data Flow & Relationships

Content Creation Flow

1. User creates/uploads FILES → stored in FOLDERS
2. User creates CANVAS from TEMPLATE (optional)
3. User adds SECTIONS to CANVAS
4. User references FILES in CANVAS (images, videos, PDFs)
5. User embeds APPS in CANVAS for interactivity
6. User associates CANVAS with ACCOUNT (customer context)

Presentation Flow

1. User schedules EVENT with ACCOUNT and CONTACTS
2. User selects CANVAS for EVENT
3. During presentation:
   - CANVAS displays SECTIONS
   - SECTIONS contain FILES (media)
   - APPS provide interactive features
   - System tracks page duration and engagement
4. After presentation:
   - EVENT captures presentation history
   - Data syncs with CRM

Template Usage Flow

1. Admin creates CANVAS marked as TEMPLATE
2. Admin adds SECTIONS (which may also be templates)
3. User creates new CANVAS from TEMPLATE
4. New CANVAS inherits structure and SECTIONS
5. User customizes content while maintaining template link

Key Concepts

Content vs Structure

Structure: Canvases, Sections, Templates (how content is organized)
Content: Files (the actual media - PDFs, images, videos)
Behavior: Apps (interactive functionality)

Reusability

Sections: Reuse content blocks across canvases
Templates: Reuse entire canvas structures
Files: Single file used in multiple canvases

Metadata & Organization

Tags: Cross-cutting categorization
Metadata: Structured custom fields (via metadata templates)
Folders: Hierarchical organization

Access Control

Instance-level: User roles (Admin, Editor, Member)
Content-level: Access types (Public, Restricted, Personal)
Collaboration: Shared access to specific canvases/files

Common Scenarios

Scenario 1: Product Launch Presentation

1. Marketing creates CANVAS TEMPLATE with:
   - Company intro SECTION
   - Product features SECTION (template)
   - Demo video FILE
   - Interactive product configurator APP

2. Sales reps create CANVASES from template
3. Each rep customizes for their ACCOUNT
4. During EVENT, system tracks:
   - Which SECTIONS were shown
   - How long on each page
   - APP interactions

Scenario 2: Regulatory Compliance Update

1. Compliance team updates SECTION TEMPLATE (legal disclaimer)
2. All CANVASES using that SECTION automatically show updated content
3. Audit trail tracks which version was shown in each EVENT

Scenario 3: CRM Integration

1. User schedules meeting in Salesforce
2. EVENT syncs to Pitcher with ACCOUNT and CONTACTS
3. User selects customer-specific CANVAS
4. After presentation, activity syncs back to Salesforce

Technical Architecture

Frontend Structure

packages/client: Vue applications (Admin & Impact)
- Admin: Content management, analytics
- Impact: Sales presentation interface
packages/libs/canvas-ui: Shared Vue component library
- Canvas builder/viewer
- Component library (CButton, CCard, etc.)
packages/next-core: Next.js application
packages/nuxt-sharing: Public sharing interface

Component Hierarchy

Canvas Builder
├── Canvas (Container)
│   ├── Pages (computed from content)
│   │   ├── Components (Text, Image, Video, etc.)
│   │   ├── SectionList (displays sections)
│   │   └── PageBreak (slide separator)
│   ├── Sections (embedded content)
│   └── Theme (styling)

State Management

Pinia stores for Vue apps
Canvas state (useCanvas composable)
Page navigation (useCanvasPages composable)
API integration (OpenAPI generated SDK)

API Structure

All entities are exposed via RESTful API:

/api/v1/canvases/ - Canvas CRUD
/api/v1/files/ - File management
/api/v1/folders/ - File Folder operations
/api/v1/apps/ - App management
/api/v1/instances/ - Instance configuration

Conclusion

The Pitcher platform is built around Canvases as the primary content delivery mechanism. Canvases combine:

Files (media content)
Sections (reusable content blocks)
Apps (interactive functionality)
Events (sales activities)
Accounts (CRM integration)

This creates a flexible, powerful system for creating, managing, and delivering sales presentations with deep CRM integration and robust tracking capabilities.

Pitcher Platform Architecture Documentation ​

Overview ​

Related Documentation ​

Architecture Diagram ​

Key Relationships ​

Component Details ​

1. Organization ​

2. Instance (Workspace) ​

3. Canvases (Presentations/Slide Decks) ​

4. Sections ​

5. Files (Content) ​

6. Folders ​

7. Templates ​

8. Apps (Extensions) ​

9. Events (Sales Activities) ​

10. Accounts (CRM Data) ​

11. Contacts (People) ​

Data Flow & Relationships ​

Content Creation Flow ​

Presentation Flow ​

Template Usage Flow ​

Key Concepts ​

Content vs Structure ​

Reusability ​

Metadata & Organization ​

Access Control ​

Common Scenarios ​

Scenario 1: Product Launch Presentation ​

Scenario 2: Regulatory Compliance Update ​

Scenario 3: CRM Integration ​

Technical Architecture ​

Frontend Structure ​

Component Hierarchy ​

State Management ​

API Structure ​

Conclusion ​

Pitcher Platform Architecture Documentation

Overview

Related Documentation

Architecture Diagram

Key Relationships

Component Details

1. Organization

2. Instance (Workspace)

3. Canvases (Presentations/Slide Decks)

4. Sections

5. Files (Content)

6. Folders

7. Templates

8. Apps (Extensions)

9. Events (Sales Activities)

10. Accounts (CRM Data)

11. Contacts (People)

Data Flow & Relationships

Content Creation Flow

Presentation Flow

Template Usage Flow

Key Concepts

Content vs Structure

Reusability

Metadata & Organization

Access Control

Common Scenarios

Scenario 1: Product Launch Presentation

Scenario 2: Regulatory Compliance Update

Scenario 3: CRM Integration

Technical Architecture

Frontend Structure

Component Hierarchy

State Management

API Structure

Conclusion