Visual Kanban Workflow (KBN)¶

Module Purpose: Provide a visual, interactive workspace where users can manage emails as "cards" in "buckets" (columns), replacing the invisible automation of the previous MVP.

[!IMPORTANT] Implementation Strategy: We will use Plane.so as the open-source Kanban foundation. Plane provides a Linear-quality UI with full API access for custom integrations. The use cases below define the business logic and workflows—Plane handles UI rendering, while our backend handles AI classification and CRM/ERP sync.

[!TIP] Deployment: Self-hosted Docker Compose on internal infrastructure. See Prerequisites for setup details.

Use Case Quick Reference¶

ID	Title	Priority
KBN-001	View Email Board	P1
KBN-002	Manage Columns & Rules	P1
KBN-003	Drag-and-Drop Classification	P1
KBN-004	Quick Card Actions	P2
KBN-005	Automated Work Shifting	P2
KBN-006	communication Re-tagging	P1

UC-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 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¶

Tech Stack (Plane.so Integration):

Frontend: Plane.so self-hosted (React + Next.js)
Backend: Custom API bridge for email ingestion → Plane Issue creation
Sync: Plane Webhooks → Pebble Orchestrator for CRM/ERP sync

Integration Points:

Plane API	Pebble Action
`POST /issues`	Create card from classified email
`PATCH /issues/{id}`	Update card metadata (intent, priority)
`Webhook: issue.updated`	Trigger CRM sync on column change
Custom Labels	Map to `stream`, `intent_tags`, `entity_id`

UC-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: - KBN-001 – Where columns render - KBN-006 – Content detection that feeds auto-rules

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

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 (e.g., asking the HOD for technical advice, generating a quote draft, or triggering an approval flow).

Who: Sales Rep, Manager
When: Triage / Daily Workflow
Why: Replaces complex dropdown menus and status forms with a single intuitive gesture.

How It Works¶

The Move Action¶

User grabs a card from "Enquiry Pending"
System highlights valid drop zones (some columns might be restricted)
User drops card into "Pending Technical Query"

System Reaction (The Trigger)¶

Frontend: Card snaps to new column instantly (optimistic UI update)
Backend:
Updates email_status = "Pending Technical Query"
Logs: User X moved Card Y from A to B
Workflow Execution:
Detects New Column = "Pending Technical Query"
Action: Creates an "Internal Activity" assigned to Technical HOD
Email/Notification: Sends ping to HOD: "Review required for [Company Name]"

Drop Column Special Logic¶

If dropped in "Drop / Lost" column: - Block: Modal popup appears - Ask: "Reason for Loss?" (Price, Specs, Stock, Dup) - Action: Routes to Manager for approval before final closure

Edge Cases¶

What if I drag to "Quote" but product details are missing?
System opens the Quotation Create screen (QTN-001) pre-filled, but validation errors prevent saving until fixed. "You can't leave this in Quote column without a drafted quote."

What if I don't have permission?
(e.g., Sales Rep trying to move to "Finance Verification")
Card snaps back to original column. Toast Error: "Unauthorized transition."

Success Signals¶

✅ Drag action feels smooth (60fps), no lag
✅ HOD receives notification within 5 seconds of drop
✅ "Lost" reason modal forces user input
✅ Database status matches visual column position exactly

Developer Notes¶

State Management: Use optimistic updates. Update UI first, then API. If API fails, roll back UI and show error. Audit Trail: Every move must be logged in activity_log for SLA tracking.

Related UCs: - QTN-001 – Triggered by move to Quote column - WFL-002 – Approval workflow for Drop

UC-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

UC-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.

UC-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

← Back to Use Cases

Visual Kanban Workflow (KBN)¶

Use Case Quick Reference¶

UC-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¶

UC-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¶

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

What It Does¶

How It Works¶

The Move Action¶

System Reaction (The Trigger)¶

Drop Column Special Logic¶

Edge Cases¶

Success Signals¶

Developer Notes¶

UC-KBN-004: Quick Card Actions¶

What It Does¶

How It Works¶

Action Menu¶

Preview Modal¶

Create Lead Logic¶

Edge Cases¶

Success Signals¶

UC-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¶

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

What It Does¶

How It Works¶

Threading Logic¶

Semantic Re-tagging¶

Thread UI¶

Edge Cases¶

Success Signals¶