Module Purpose: Provide a visual, interactive workspace where users can manage internal business signals (Emails, Leads) as "cards" in functional status columns.

[!IMPORTANT] Implementation Strategy: This module uses a Hybrid Plane.so model. We use Plane.so for the visual triage UI and the Pebble Backend as an industrial broker for state validation and CRM synchronization. For details on license mitigation and API flow, see the Kanban OSS Trade-Off Analysis.

Use Case Quick Reference¶

ID	Title	Priority
US-KBN-001	View Email Board	P1
US-KBN-012	Native Lead State Management	P0
US-KBN-003	Drag-and-Drop Override	P1
Kanban-CRM Bridge	Functional Sync Logic	P1
US-KBN-012	Native Lead State Management	P0
Kanban-CRM Bridge	Functional Sync Logic	P1

US-KBN-001: View Email Board¶

What It Does¶

Renders the real-time Kanban board where enquiry emails appear as cards. It allows sales teams to visualize their workload, filter by hierarchy (team view vs personal view), and identify urgent actions via visual indicators.

Who: Sales Rep, Manager, Email Delegator
When: Daily start-of-day and continuous monitoring
Why: Emails buried in Outlook folders get missed. A board visualizes the backlog and flow.

How It Works¶

Board Initialization¶

User logs in and navigates to /kanban
System loads cards based on user's role:
Sales Rep: Shows only leads assigned to them
Manager: Shows leads assigned to their hierarchy + unassigned leads
Admin: Shows global view
Default Filter: "My Inbox" (Active leads, last 30 days)

Card Rendering (The "Face" of the Email)¶

Each card displays minimal but critical info: - Header: Email Subject (truncated) - Badges: High Priority (red), Sample Requested (blue) - Meta: Sender Name, Company Name (from Prelead match) - Aging: "2 days ago" (Color coded: Red if > 48h) - Visuals: Abstract thumbnail if PDF/Image attached

Real-Time Sync¶

WebSocket Connection: The board subscribes to mailbox.{user_id} channel
New Email: When US-EML-001 detects a new email, a card "flies in" to the first column
Status Change: If another user moves a card, it updates instantly on all screens

Edge Cases¶

What if a user has 5000+ emails?
System implements Infinite Scroll per column. Loads first 20 cards. As user scrolls down, fetches next 20. "Load More" button appears at bottom.

What if WebSocket disconnects?
Banner appears: "Connection lost. Trying to reconnect..." Board freezes to prevent stale state edits.

What if an email belongs to multiple potential columns?
Business Rule: Single Status Truth. An email can only be in ONE column at a time defined by email_status field.

Success Signals¶

Board renders in < 1.5 seconds
New emails appear instantly without page refresh
Manager can switch view to see subordinate's board
"High Priority" cards visually distinct (red border/badge)
Scroll position maintained when clicking into a card and returning

Developer Notes¶

Frontend: Custom React board with optimized drag-and-drop.
Backend: Native CRM state machine for lead lifecycle.
Sync: Internal event bus for Activity-Stream updates.

US-KBN-002: Manage Kanban Columns¶

What It Does¶

Allows administrators to create, rename, reorder, and configure operational status columns on the Kanban board, including setting up automated rules that move cards based on email content patterns.

Who: Admin, Board Owner
When: During board setup OR ongoing maintenance
Why: Different teams have different workflows - customizable columns ensure the board matches real operational statuses

How It Works¶

Creating a New Column¶

Admin clicks "+ Add Column" button in board header
System shows inline editor with fields:
Column Name (e.g., "Waiting for Lab Results")
Color tag (pick from palette: red, blue, green, yellow, purple)
Position (drag handle to place between existing columns)
Admin saves → Column appears immediately in all users' boards
Empty column shows message: "Drag cards here when waiting for lab results"

Auto-Move Rules (Optional)¶

Admin can set up intelligent automation:

Example Rule: "Auto-move to 'Waiting for Samples'" - Trigger: Email subject OR body contains "sample" - Action: Move card to this column automatically - Notification: Send alert to Lab Manager

System Behavior: - Scans incoming email content using keyword matching - If match found: Card auto-moves + notification fires - User sees: "🤖 Auto-moved by rule: 'sample' keyword detected"

Reordering Columns¶

Admin enables "Edit Mode" (🎨 button in header)
Drag column headers left/right to reorder
Changes save instantly, affect all users
Common order: Pending → Query → Docs → Samples → Quote → Drop

Edge Cases¶

What if user drags column during active drag?
System blocks: "Cannot reorder columns while cards are being moved. Try again."

What if auto-rule creates infinite loop?
Example: Rule 1 moves to Column A if "urgent", Rule 2 moves to Column B if in Column A
System detects: Max 2 auto-moves per card per day, then flags for manual review

Success Signals¶

✅ New column appears across all user boards within 2 seconds
✅ Auto-rules trigger correctly on keyword match
✅ Column reordering persists after browser refresh
✅ Color changes apply to all cards in that column

Developer Notes¶

Backend: - Store column config in kanban_columns table with board_id, position, color, auto_rules JSON - Auto-rule engine: Run regex on email subject + body

Related UCs: - US-KBN-001 – Where columns render - US-KBN-006 – Content detection that feeds auto-rules

US-KBN-003: Drag-and-Drop Classification¶

PHASE: 2 (MOM Jan 25 Agreement)

What It Does¶

Enables users to update email enquiry status by simply dragging cards between columns. The drop action acts as a "Trigger" that fires off stage-specific workflow activities.

Technical Dependency¶

Requires bidirectional webhook synchronization with the Plane.so API to ensure status updates in the UI are reflected in the backend database.

[!NOTE] For Phase 1 (POC), status updates are handled via Manual In-place Edits within the card detail view to reduce technical overhead and align with the ₹11L budget.

Technical Implementation (Plane.so + AI Labelling)¶

Bridge Logic: When an email is ingested, Pebble calls the Plane.so API to create a card.
AI Labelling: AI applies specialized labels to the Plane card (e.g., GST: Active, Cat: Pharma, Margin: OK).
Deep Linking: Each Plane card includes a "View Industrial Details" link in the description, which opens the Pebble CRM Sidecar for regulatory and costing tasks.
Sync: In Phase 2, dragging a card in Plane sends a webhook to Pebble to update the Lead status in the CRM Core.

Detailed Acceptance Criteria¶

Manual Override: (Phase 1) Users can change status via a dropdown in the card detail view.
Bi-Directional Sync: (Phase 2) Dragging a card in Plane MUST update the CRM lead status within <5 seconds.
Metadata Propagation: AI labels (colored) and deep links to email threads MUST appear on the Plane card face.

US-KBN-004: Quick Card Actions¶

What It Does¶

Provides one-click actions directly on the card face or context menu (right-click) to perform high-frequency tasks like Preview, Archive, or Convert to Lead without opening the detailed view.

Who: Sales Rep, Manager
When: Rapid Triage / Board Scanning
Why: Speed. Clicking into every email to archive it is too slow for 100+ emails/day.

How It Works¶

Trigger: Right-click card OR click the ⋮ menu icon.

Options: 1. Preview: Opens quick-view modal (read-only email body) 2. Archive: Removes from board (Soft delete / Hide) 3. Create Lead: Converts raw email intent to CRM Lead 4. Dialer Sync: Checks phone number, schedules call task 5. Recall: (Only if shifted) Reclaim ownership

Shows email body (sanitized HTML)
"Reply" button (opens Outlook/Composer)
"Close" (Esc key)

Create Lead Logic¶

Scrapes: From Name, Domain, Subject
Pre-fills: First Name, Company, Requirement
API Call: POST to CRM lead endpoint
Success: Card icon changes to 👤 (Lead)

Edge Cases¶

What if email is already a lead?
"Create Lead" option is disabled/hidden.

What if Preview fails?
Fallback to "Open in Outlook" link.

Dialer Sync outside hours?
Schedules task for next business day 10 AM.

Success Signals¶

✅ Context menu opens instantly
✅ Archive action has "Undo" toast (5s duration)
✅ Create Lead pre-fills 80%+ of available data fields

US-KBN-005: Automated Work Shifting (11:30 AM)¶

What It Does¶

Ensures business continuity by automatically detecting absent employees at 11:30 AM and shifting their high-priority "Due Today" cards to a backup owner or HOD.

Who: System Background Job (Cron)
When: Daily at 11:30 AM (configurable)
Why: Sales enquiries rot quickly. If a rep is sick, the customer shouldn't wait 24h.

How It Works¶

Detection Phase¶

Time Check: Clock strikes 11:30 AM
Login Check: System queries user_session table
"Has User X logged in today?"
No: User X is marked "Absent / Late"

Shifting Phase¶

Query Workload: Find cards owned by User X where:
Status != Closed
Priority = High OR Last_Interaction > 24h
Identify Target: Look up User X's backup_owner_id (e.g., Bob)
If Bob is also absent -> Escalate to manager_id
Execution:
Update assigned_user_id = Bob
Add Tag: SHIFTED_FROM_JANE
Send Email to Bob: "Jane is away. 5 High Priority leads moved to you."

Recall Phase (The "I'm Here!" Moment)¶

If Jane logs in at 12:00 PM:
System detects late login
Popup: "Values were shifted to Bob. Recall?"
Action: Jane clicks "Recall All" -> Cards move back.

Edge Cases¶

What if everyone is absent? (e.g., Holiday)
System checks Holiday_Master. If today is holiday, Job skips.

What if Bob is overwhelmed?
(Future) Load balancing check: If Bob has > 50 cards, shift to Round Robin pool instead.

Partial Recall?
Jane sees list of shifted items. Can select specific ones to recall, leave others with Bob.

Success Signals¶

✅ Job runs reliably at 11:30 AM
✅ Only High Priority items move (Low priority waits)
✅ Hierarchy fallbacks work (Backup -> HOD -> Admin)
✅ Recall function restores original ownership cleanly

Developer Notes¶

Scheduler: Use BullMQ / Quartz / Cron. Audit: Log every shift event (AUTO_SHIFT, MANUAL_RECALL) in activity timeline. Performance: Batch updates. Don't fire 50 separate DB calls for 50 cards.

US-KBN-006: Communication Re-tagging & Threads¶

What It Does¶

Analyzes incoming emails (replies/forwards) to automatically tag cards (e.g., "Sample Requested", "Negotiation") and groups them into a single chronological thread, ensuring context isn't lost.

Who: AI Engine / NLP Service
When: On Email Ingest
Why: A single enquiry might have 50 email exchanges. They should be 1 card, not 50.

How It Works¶

Threading Logic¶

Header Analysis: Check In-Reply-To and References headers.
Subject Analysis: Remove "Re:", "Fwd:", match simplified subject string.
Match: If match found -> Attach outgoing email to Existing Card. DO NOT create new card.
Bump card to top of column (Sort by Last Updated)

Semantic Re-tagging¶

Scan Content: AI scans body text for intent keywords.
"Please send sample" -> Tag: Sample Req
"Too expensive" -> Tag: Negotiation
"PFA Purchase Order" -> Tag: PO Received -> Auto-move to "Order" column
Update UI: Add colored badge to card face.

Thread UI¶

Card shows "💬 5" indicator.
Clicking opens Timeline View (Chat style interface) showing all emails in order.

Edge Cases¶

False Positive Threading
Customer sends new enquiry with same subject "Enquiry".
Logic: Check timestamp. If > 30 days gap, treat as new enquiry (New Card).

Conflicting Tags
Email 1: "Send sample". Email 2: "Cancel sample".
Logic: Newest intent wins or adds "Conflict" flag for human review.

Success Signals¶

✅ Threaded replies attach to parent card 99% of time
✅ Keywords trigger correct tags (Sample, PO, Quote)
✅ Visual Thread view renders HTML emails correctly

US-KBN-012: Native Lead State Management¶

Purpose: Ensure that moving a card on the Kanban board (e.g., from "New" to "Qualified") automatically updates the internal lead status in the CRM Core. This is an internal atomic transaction within the Pebble database.

Who: System Integration Engine
When: Real-time via Webhooks

Functional Bridge: CRM Core¶

The Kanban-CRM Bridge is the industrial heart of the platform. While users interact with the visual simplicity of the Kanban board, the Pebble CRM Core acts as the authoritative "Logic Master".

How It Works: The Industrial Broker¶

Board as Ingestion View: Every card in Plane.so corresponds to a ActivityStream event in the Pebble Database.
The Sync Loop:
- Plane → Pebble: When a user drags a card to "Qualified", a webhook hits the Pebble Backend.
- Logic Check: The Backend verifies if the CRM record has a valid CIN/PAN/GST (from MST-002).
- Atomic Commit: If valid, the Lead's commercial_status is updated. If invalid, the card is "snapped back" to the previous column with an error badge.
Deep Sidecar Integration:
- Each Kanban card contains a unique Industrial Detail URL.
- Clicking this opens the CRM Sidecar UI directly on top of the board, allowing for 8-tab management (Contacts, Products, COA) without losing board context.

Event Type	Kanban Visual	CRM Core Action
New Ingest	Card in "New"	Create `Prelead` master
Stage Promotion	Drag to "Enquiry"	Prompt for Price Discovery (MST-011)
High Urgency	Red Border	Escalate in `Manager Triage` view
Assignment	Assignee Icon	Map to `Allocated Account Owner`

[!IMPORTANT] Data Integrity: The Kanban board is ephemeral; all permanent records reside in PostgreSQL. If the Kanban board is deleted, it can be fully rebuilt in <5 minutes from the Pebble CRM Activity Stream.

← Back to Use Cases

Use Case Quick Reference¶

US-KBN-001: View Email Board¶

What It Does¶

How It Works¶

Board Initialization¶

Card Rendering (The "Face" of the Email)¶

Real-Time Sync¶

Edge Cases¶

Success Signals¶

Developer Notes¶

US-KBN-002: Manage Kanban Columns¶

What It Does¶

How It Works¶

Creating a New Column¶

Auto-Move Rules (Optional)¶

Reordering Columns¶

Edge Cases¶

Success Signals¶

Developer Notes¶

US-KBN-003: Drag-and-Drop Classification¶

What It Does¶

Technical Dependency¶

Technical Implementation (Plane.so + AI Labelling)¶

Detailed Acceptance Criteria¶

US-KBN-004: Quick Card Actions¶

What It Does¶

How It Works¶

Action Menu¶

Preview Modal¶

Create Lead Logic¶

Edge Cases¶

Success Signals¶

US-KBN-005: Automated Work Shifting (11:30 AM)¶

What It Does¶

How It Works¶

Detection Phase¶

Shifting Phase¶

Recall Phase (The "I'm Here!" Moment)¶

Edge Cases¶

Success Signals¶

Developer Notes¶

US-KBN-006: Communication Re-tagging & Threads¶

What It Does¶

How It Works¶

Threading Logic¶

Semantic Re-tagging¶

Thread UI¶

Edge Cases¶

Success Signals¶

US-KBN-012: Native Lead State Management¶

Functional Bridge: CRM Core¶

How It Works: The Industrial Broker¶