Skip to content

PRD: Plane.so Kanban Integration

Introduction

This PRD defines the integration strategy for Plane.so, an open-source project management tool, as the Visual Kanban foundation for the Pebble Business Orchestrator. Plane replaces custom Kanban UI development, providing a Linear-quality interface with full API access for custom integrations.

[!CAUTION] License: AGPL-3.0 - Plane.so is licensed under the GNU Affero General Public License v3.0. This means: - Internal Use: No restrictions. - SaaS Deployment: If Pebble is offered as a hosted SaaS to external customers, source code disclosure may be required. - Mitigation: Use strict API isolation (Plane as separate service) and avoid modifying Plane's codebase.

See Kanban OSS Trade-off Analysis for full details.

Goals

  • Rapid Deployment: Self-hosted Docker deployment in < 1 day.
  • Email-to-Card Bridge: Automatically create Plane Issues from classified emails.
  • Bi-Directional Sync: Plane column changes trigger CRM/ERP sync via webhooks.
  • Custom Metadata: Map AI classification results to Plane labels and custom fields.

Use Case Mapping

This PRD covers the implementation of: - KBN-001: View Email Board - KBN-002: Manage Kanban Columns - KBN-003: Drag-and-Drop Classification

User Stories

US-001: Self-Hosted Plane Deployment

Description: As a DevOps engineer, I want to deploy Plane.so via Docker Compose so that the team has a production-ready Kanban within hours.

Acceptance Criteria:

  • Clone Plane repository and configure docker-compose.yml with production settings.
  • Configure PostgreSQL, Redis, and MinIO for persistent storage.
  • Set WEB_URL and API_URL environment variables for internal domain.
  • Enable HTTPS via reverse proxy (Nginx/Caddy).
  • Verification: Access https://kanban.internal.pebble.io and create a test project.

US-002: Email-to-Issue API Bridge

Description: As a system, I want to create a Plane Issue whenever a new email is classified so that it appears on the Kanban board.

Acceptance Criteria:

  • Create API service that listens to email.classified events from the classification engine.
  • Call POST /api/v1/workspaces/{workspace}/projects/{project}/issues with payload:
  • name: Email subject (truncated to 100 chars)
  • description_html: Email body preview + link to full thread
  • priority: Mapped from AI urgency field (High=2, Medium=1, Low=0)
  • labels: Array of AI intent_tags (e.g., "Sample_Req", "Price_Query")
  • Store plane_issue_id in the emails.metadata JSONB field for bi-directional linking.
  • Verification: Send a test email and confirm Issue appears in Plane within 30 seconds.

US-003: Column Change Webhook Handler

Description: As a system, I want to be notified when a user moves a card to a new column so that I can trigger CRM/ERP sync.

Acceptance Criteria:

  • Configure Plane webhook for issue.updated events pointing to /api/webhooks/plane.
  • Extract state_id (column) from webhook payload.
  • Map Plane columns to business states:
  • "Inbox" → status: new
  • "In Progress" → status: active, trigger CRM sync
  • "Closed Won" → status: closed, trigger ERP order creation
  • "Archived" → status: archived
  • Log all state transitions in activity_log.
  • Verification: Drag a card from "Inbox" to "In Progress" and confirm CRM record is created.

US-004: Custom Labels for AI Metadata

Description: As a user, I want to see AI-generated tags as visual labels on cards so I can quickly identify intent.

Acceptance Criteria:

  • Pre-create Plane labels via API during workspace setup: Enquiry, Complaint, Sample_Req, PO, Urgent.
  • Assign label colors: Enquiry=Blue, Complaint=Red, Sample_Req=Green, PO=Purple, Urgent=Orange.
  • When creating Issue, attach labels based on metadata.intent_tags.
  • Verification: Confirm classified email shows correct colored labels in Plane UI.

Description: As a user, I want to click a card and see the full email thread so I can take action.

Acceptance Criteria:

  • Store email_thread_url in Issue description as clickable link.
  • Optionally embed email body preview in Issue description (first 500 chars).
  • For attachments, store MinIO presigned URLs for PDFs/images.
  • Verification: Click Issue, verify email link opens in new tab.

Functional Requirements

  • FR-1: Plane MUST be deployed on internal infrastructure (no SaaS dependency).
  • FR-2: All email-to-card creation MUST complete within 30 seconds of classification.
  • FR-3: Webhook handler MUST be idempotent (handle duplicate events gracefully).
  • FR-4: API bridge MUST use Plane API v1 with Bearer token authentication.

Non-Goals

  • No customization of Plane's core UI (use out-of-the-box).
  • No direct database access to Plane (API-only integration).
  • No mobile app for Plane (web-only for POC).
  • No Custom Fields (Enterprise-only feature). Use Labels + Description metadata instead.

Technical Considerations

  • Plane Version: Latest stable (v0.20+)
  • Deployment: Docker Compose on dedicated VM or Kubernetes
  • Storage: PostgreSQL 15+, Redis 7+, MinIO for attachments
  • Networking: Internal DNS (e.g., kanban.internal.pebble.io)
  • Metadata Strategy: Since custom fields are Enterprise-only, store AI classification data using:
  • Labels: Stream:CRM, Stream:ERP, Intent:Enquiry, Priority:High
  • Description Footer: Append JSON metadata block to issue description

Success Metrics

  • 100% of classified emails appear as Plane Issues within 30 seconds.
  • Zero manual Issue creation required for email-sourced leads.
  • Column-change-to-CRM-sync latency < 5 seconds.

Open Questions

  • Should we enable Plane's native time tracking for SLA monitoring?
  • Do we need multi-workspace for multi-entity or is label-based filtering sufficient?