Developer
Architecture

Architecture

Pipedrive Utilities runs on Cloudflare Workers with Hono as the web framework and Cloudflare D1 (serverless SQLite) as the database. It serves two iframes embedded in Pipedrive – a deal sidebar panel and a settings page – and exposes webhook endpoints for external integrations.

Component Diagram

graph TB subgraph Pipedrive iframe_panel[Panel iframe] iframe_settings[Settings iframe] pd_api[Pipedrive API v1/v2] pd_automations[Pipedrive Automations] end subgraph "Cloudflare Workers" worker[Worker - Hono Routes] d1[(D1 Database)] assets[Static Assets] cron[Cron Scheduler] end subgraph "External Services" gads[Google Ads API] formidable[Formidable Forms API] ccs[Campus Cloud SIS API] smtp2go[SMTP2GO Email API] end iframe_panel -->|fetch| worker iframe_settings -->|fetch| worker worker --> assets worker --> d1 worker --> pd_api worker --> gads worker --> formidable worker --> ccs worker --> smtp2go pd_automations -->|webhook| worker formidable -->|webhook| worker cron --> worker

Frontend

Three entry points are bundled by esbuild as IIFE globals (see build.js):

Bundle	Source	Global	Purpose
`static/panel-bundle.js`	`src/panel.js`	`PanelApp`	Deal sidebar panel UI – search, preview, merge, duplicate detection
`static/settings-bundle.js`	`src/settings.js`	`SettingsApp`	Settings page – webhook config, field mapping, Google Ads, general admin
`static/field-modal-bundle.js`	`src/field-modal.js`	`FieldModalApp`	Full-screen field comparison modal for merge previews

HTML source files live in public/ and are copied to static/ at build time with path rewriting. Both panel and settings use @pipedrive/app-extensions-sdk for iframe communication, falling back to standalone mode when the SDK cannot initialize (not embedded in an iframe).

Documentation is built with docmd from the docs/ directory into static/docs/.

Worker

The worker (src/worker.js) is a Hono app exported as the Cloudflare Workers entry point with both fetch and scheduled handlers.

Middleware Stack

CORS – allows cross-origin requests from Pipedrive iframes with credentials.
CSP – sets frame-ancestors to permit embedding by *.pipedrive.com.
D1 binding – attaches token, settings, log, and queue stores to the request context.
Session – D1-backed cookie sessions (src/session.js) with proxy-based dirty detection and probabilistic cleanup of expired sessions.

Route Groups

OAuth (/auth/*) – Pipedrive OAuth2 flow with automatic token refresh; Google Ads OAuth as a separate flow.
API proxy (/api/*) – All protected by requireAuth middleware. Proxies Pipedrive API calls, manages settings, serves logs, and handles merge operations.
Webhooks (/webhook/*) – Unauthenticated inbound endpoints for Formidable Forms and Google Ads Automations. These use the automation user’s token for Pipedrive API access.
Pages – Serves static HTML for /panel, /settings, /field-modal, /help, and /docs/.
Cron – The scheduled export processes the retry queue on a timer.

Session Restoration

Sessions can be restored via a companyId query parameter passed by Pipedrive. The /auth/status endpoint looks up tokens by company ID if no active session exists, enabling cross-context authentication in iframes where third-party cookies may be blocked.

Database

Cloudflare D1 with a factory function createDB(d1) in src/db.js that returns async store objects. See Database Schema for full table definitions.