EspoCRM Architecture

EspoCRM is the primary CRM interface where users manage content, guests, and publishing workflows.

Overview

Container Details

Property	Value
Container	mediamagic-espocrm
Port	8080
Image	espocrm/espocrm
PHP Version	8.2
Database	MySQL 8.0

Custom Entities

MediaMagic extends EspoCRM with custom entities:

Directory Structure

espocrm/custom/
├── setup-entities.js       # Entity setup script
├── seed-espocrm.sh         # Sample data seeding
│
├── Espo/Custom/            # Backend PHP customizations
│   ├── Classes/            # Custom classes
│   ├── Controllers/        # API controllers
│   ├── Hooks/              # Entity lifecycle hooks
│   ├── Resources/          # Metadata, layouts
│   └── Services/           # Business logic
│
└── client/                 # Frontend customizations
    ├── src/
    │   ├── controllers/    # Frontend controllers
    │   ├── handlers/       # Event handlers
    │   └── views/          # Custom views
    ├── css/                # Custom styles
    └── js/                 # Utility scripts

Custom Views

Video Editor

A powerful text-based video editor accessible from CVideo records:

Features:

• Transcript-based editing (Descript-style)
• Multi-layer NLE timeline with waveforms
• AI-powered edit assistant
• Word search across transcripts
• Undo/Redo with full history

Location: client/src/views/modals/video-editor.js

Boxcast Integration

Grid view with card layout for Boxcast broadcasts:

Features:

• Card-based grid display
• Status indicators
• Quick actions
• Live preview integration

Location: client/src/views/boxcast-broadcast/

Media Preview

Hover-to-preview video playback in grid views:

Features:

• Hover to play preview
• Thumbnail filmstrips
• Duration display
• Click to open full view

Webhooks Configuration

EspoCRM sends webhooks to Bridge on entity changes:

Entity	Events	Endpoint
GuestBooking	Create, Update	/webhooks/guest-*
ContentProduction	Create, Update	/webhooks/content-*
PlatformPublish	Create, Update	/webhooks/platform-*
Clip	Create, Update	/webhooks/clip-*
SocialPost	Create, Update, Delete	/webhooks/social-*

Webhook Setup

1. Admin → Webhooks → Create
2. Set URL: http://bridge:3100/webhooks/{event-name}
3. Select Entity Type
4. Select Event (After Create, After Update, etc.)
5. Activate

Entity Setup Script

The setup-entities.js script configures all custom entities:

cd espocrm/custom
npm install

ESPOCRM_URL=http://localhost:8080 \
ESPOCRM_ADMIN_USER=admin \
ESPOCRM_ADMIN_PASSWORD=your_password \
node setup-entities.js

What it creates:

• Entity definitions
• Fields and relationships
• Layouts (list, detail, edit)
• Default views

API Access

EspoCRM provides a full REST API:

Authentication

# Using API Key (recommended)
curl http://localhost:8080/api/v1/ContentProduction \
  -H "X-Api-Key: YOUR_API_KEY"

# Using Basic Auth
curl http://localhost:8080/api/v1/ContentProduction \
  -u "username:password"

Common Operations

# List entities
GET /api/v1/{Entity}

# Get single entity
GET /api/v1/{Entity}/{id}

# Create entity
POST /api/v1/{Entity}
Content-Type: application/json
{"name": "New Item", ...}

# Update entity
PUT /api/v1/{Entity}/{id}
Content-Type: application/json
{"status": "Published"}

# Delete entity
DELETE /api/v1/{Entity}/{id}

Customization Best Practices

Use Hooks for Logic

Place business logic in Hooks rather than Controllers for reusability.

Extend, Don't Modify Core

Always extend core classes rather than modifying them directly.

Test After Updates

After EspoCRM updates, test custom functionality thoroughly.

Backup Before Changes

Always backup before modifying custom code or running setup scripts.

Related

• ContentProduction Entity
• PlatformPublish Entity
• Webhooks API
• Bridge Architecture