# Support Ticketing — ERPNext Helpdesk

**Last updated:** 2026-03-29

## Overview

ERPNext's Issue DocType provides all helpdesk ticketing. There is no separate
ticketing system — everything runs inside the same CRM that manages orders
and invoices.

- Web widget on performancewest.net -> Express API -> ERPNext Issue
- Contact form -> Express API -> ERPNext Issue
- Monitor script alerts -> ERPNext Issue
- Formation worker errors -> ERPNext Issue
- Customer portal: clients can view/reply to their issues

## How Tickets Are Created

### 1. Website Support Widget (SupportWidget.astro)
The floating help button on every page submits to `POST /api/v1/tickets`.
The Express API creates an ERPNext Issue with the ticket data.

Categories map to ERPNext Issue Types:
| Widget Category | ERPNext Issue Type |
|----------------|-------------------|
| question | Sales Inquiry |
| support | Support |
| issue | Bug |
| service_request | Feature Request |
| quote | Sales Inquiry |

### 2. Contact Page Form
Same flow as the support widget — submits to `POST /api/v1/tickets`.

### 3. Monitor Script Alerts (alert.py)
When Reddit monitors, formation workers, or other scripts encounter errors,
they call `alert_account_broken()` which creates an ERPNext Issue with
priority "High" and issue_type "Bug".

### 4. Formation Worker Errors
When automation fails (state portal down, CAPTCHA, payment failure), the
worker creates an ERPNext Issue linking to the Formation Order.

## ERPNext Issue Fields

| Field | Description |
|-------|-------------|
| subject | Ticket title |
| description | Full message |
| issue_type | Sales Inquiry, Support, Bug, Feature Request |
| priority | Low, Medium, High, Urgent |
| status | Open, Replied, Resolved, Closed |
| customer | Linked Customer (if known) |
| raised_by | Email of the person who submitted |

## Ticket Workflow

```
Open -> Replied -> Resolved -> Closed
         ^          |
         +-- Reopened +
```

- Admin views open issues in ERPNext desk
- Responds via ERPNext (email sent to customer automatically)
- Customer can reply via email (auto-linked to issue)
- Admin resolves when done
- Auto-close after 7 days with no reply

## DNS

There is no separate `support.performancewest.net` domain.
Tickets are managed at `crm.performancewest.net` (ERPNext).

## Configuration

No separate ticketing configuration needed. ERPNext Issue is a core
DocType — just needs email integration for customer notifications:

1. ERPNext -> Settings -> Email Account -> configure outgoing email
2. ERPNext -> Settings -> Email Account -> configure incoming email (for auto-reply-to-issue)
3. ERPNext -> Desk -> Issue -> create Issue Types if needed

## Canada CRTC Client Email Monitoring

`client_email_processor.py` monitors inbound email for each Canada CRTC
client domain. Each client gets 14 standard mailboxes provisioned via
HestiaCP on cp.carrierone.com:

| Mailbox | Priority |
|---------|----------|
| regulatory@ | High |
| crtc@ | High |
| ccts@ | High |
| corpadmin@ | Medium |
| registeredoffice@ | Medium |
| accounting@ | Medium |
| billing@ | Medium |
| abuse@ | High |
| noc@ | High |
| postmaster@ | Medium |
| info@ | Low |
| admin@ | Medium |
| sales@ | Low |
| support@ | Low |

### How It Works

1. `client_email_processor.py` connects to each mailbox via IMAP
2. New messages are parsed (sender, subject, body, attachments)
3. An ERPNext Issue is created with:
   - Subject from the email
   - Priority based on the mailbox type (see table above)
   - Customer linked to the CRTC client
   - Issue Type: "CRTC Correspondence"
4. **High-priority items** (regulatory@, crtc@, ccts@, abuse@, noc@)
   trigger an immediate alert to both the client and the PW admin team
5. Lower-priority items are batched into a daily digest for the client

The processor runs on a 5-minute polling interval via cron.

## Accounting Support Conversation Monitor

`conversation_monitor.py` scans active accounting support Issue threads in
ERPNext for bypass attempts — situations where a client tries to move the
conversation off-platform or bypass payment.

### Detection Patterns

The monitor flags messages containing:
- **Personal contact info:** phone numbers, personal email addresses,
  physical addresses shared in thread
- **Messaging platforms:** references to WhatsApp, Telegram, Signal,
  Discord, Slack DMs, or similar
- **Payment bypass:** requests to pay outside the platform, mentions of
  Venmo, Zelle, Cash App, direct wire, or crypto wallet addresses

### Response Actions

1. **Warning injection:** An automated reply is posted to the Issue thread
   reminding the client that all communication and payments must go through
   the platform for their protection and ours
2. **Admin alert:** A separate ERPNext Issue is created (type: "Compliance
   Alert", priority: High) notifying the admin team of the flagged message
3. **Escalation on repeat:** If the same client is flagged more than once,
   the admin alert is marked Urgent and the client's accounting support
   access is temporarily suspended pending review

The monitor runs as a background job every 15 minutes, scanning Issues
with type "Accounting Support" and status "Open" or "Replied".