Skip to content

🎫 Frappe Helpdesk & Agent Collaboration Hub

The Frappe Helpdesk instance (https://rewards.cpl.com.pg/helpdesk) serves as the centralized ticketing, task coordination, inter-agent collaboration, and knowledge management hub for the CPL Group Real Rewards Loyalty platform.

1. System Architecture & Dual-Access Model

The system separates Human Access (enterprise SSO over HTTPS) from Agent Access (zero-latency local loopback over HTTP):

flowchart TD
    Human["CPL Management & Staff"] -->|"HTTPS / Port 443<br/>https://rewards.cpl.com.pg/helpdesk"| Nginx["Nginx Reverse Proxy<br/>(Let's Encrypt SSL)"]
    Nginx -->|"Proxy Pass /helpdesk"| FrappeContainer["Frappe Helpdesk Container<br/>(Host Port 8088 / Internal 8000)"]

    subgraph Local_Agent_Sandbox ["Local Autonomous Agent Network"]
        Agents["Agent Crew (CrewAI / AGY)<br/>Orchestrator, Coder, QC, Doc, Gatekeeper"]
        Agents -->|"Local REST API<br/>http://127.0.0.1:8088<br/>Individual Bot API Keys"| FrappeContainer
    end

    subgraph Corporate_SSO ["Enterprise Identity"]
        Entra["Microsoft Entra ID (Azure AD)<br/>@cpl.com.pg Tenant"]
        FrappeContainer -.->|"OAuth 2.0"| Entra
    end

2. Dedicated Agent Accounts & Security Profiles

Each agent persona in the engineering crew is provisioned with a dedicated Frappe user account and credentials to guarantee an immutable audit trail:

Agent Persona Account Email Frappe Role Responsibilities on Tickets
Project Orchestrator orchestrator@agent.cpl.com.pg Helpdesk Manager Decomposes feature requests, creates tickets, assigns agents, and requests human review.
Python Coder python_coder@agent.cpl.com.pg Helpdesk Agent Implements code on dev branch, posts commit SHAs, and tags QC.
Quality Control (QC) qc_agent@agent.cpl.com.pg Helpdesk Agent Runs automated Playwright test suites on Staging, attaches logs and screenshot proof.
Document Manager doc_manager@agent.cpl.com.pg Knowledge Base Manager Authors mandatory KB articles, links them to tickets, and dual-publishes to MkDocs.
Release Gatekeeper gatekeeper@agent.cpl.com.pg Helpdesk Auditor Verifies human sign-off before authorizing code promotion to main.

3. End-to-End Inter-Agent Collaboration Workflow

sequenceDiagram
    autonumber
    actor Lead as Human Lead / Manager
    participant Orchestrator as Orchestrator Agent
    participant Helpdesk as Frappe Helpdesk (/helpdesk)
    participant Coder as Python Coder Agent
    participant QC as QC & Test Agent
    participant Doc as Document Manager Agent

    Lead->>Orchestrator: Assign new task or bug report
    Orchestrator->>Helpdesk: 1. Create Ticket (Status: Open)
    Orchestrator->>Helpdesk: 2. Assign to Python Coder
    Coder->>Helpdesk: 3. Comment: "Starting work on dev branch..."
    Note over Coder: Implements fix on Staging
    Coder->>Helpdesk: 4. Comment: Post commit SHA & tag @QC-Agent
    QC->>Helpdesk: 5. Execute Playwright headless visual test suite
    QC->>Helpdesk: 6. Comment: Attach screenshot evidence & log
    QC->>Helpdesk: 7. Comment: Tag @Doc-Manager for KB generation
    Doc->>Helpdesk: 8. Author mandatory KB article & dual-publish to /docs
    Doc->>Helpdesk: 9. Link KB Article ID to Ticket
    Orchestrator->>Helpdesk: 10. Update Status: 'Pending Review'
    Lead->>Helpdesk: 11. Inspect comments, visual screenshots & KB
    Lead->>Helpdesk: 12. Sign off & mark Ticket: 'Closed'

4. Mandatory Knowledge Base (KB) Rule

In accordance with project governance: 1. Zero Undocumented Tickets: Every ticket resolved by the agent crew must have an associated Knowledge Base article before it can be closed. 2. Resolution-Time Authoring: The Document Manager agent drafts and finalizes the KB article once code and Playwright tests pass on Staging. 3. Dual-Publishing Architecture: * Published to Frappe Helpdesk under the appropriate service category. * Converted into Markdown and published to the authenticated Material for MkDocs system manual (/docs).

5. Strict Human Review Close-Out Gate

To prevent rogue agent actions: * Agents are strictly prohibited from setting any ticket to Closed. * Agents may only transition tickets up to Pending Review. * Only an authenticated human lead or manager logging in via Microsoft SSO can review the ticket thread and mark it Closed.