helpdesk/LLM.md

Hanzo Help Center (hanzoai/helpdesk)

Fork of frappe/helpdesk deployed as a Hanzo platform service at help.hanzo.ai. Second Frappe app after hanzoai/erp, proving the one Frappe-core -> all Frappe apps thesis: the same recipe (bench + the hanzoai/frappe SQLite driver) is reused; only the app layer swaps.

Hanzo-specific additions (vs upstream)

• Dockerfile — self-contained, on-cluster build (arcd/BuildKit, never GitHub builders). Builds a bench against hanzoai/frappe (carries the experimental SQLite driver), installs telephony + helpdesk, builds SPA assets, and snapshots the built sites/ tree as an image template (assets = code).
• deploy/entrypoint.sh — starts in-pod redis (cache/queue/socketio), restores code assets over the data-only volume, creates a per-org SQLite site (org == tenant), wires IAM SSO, and serves the Frappe WSGI app under gunicorn with /assets and /files in process (no nginx — hanzoai/ingress terminates TLS + routes the host). The Werkzeug development server, with its debugger and reloader, is not in the request path.
• helpdesk/hanzo_sso.py — idempotently provisions a Frappe Social Login Key for hanzo.id OAuth2. Client credentials come from env (KMS-backed k8s secret help-secrets), never hardcoded.
• deploy/help.service.yaml — operator-native Service CR (hanzo.ai/v1).
• deploy/help.ingress.yaml — ingress (help.hanzo.ai) + PVC (help-app-db).

Data model

org == tenant (IAM owner). One SQLite site per org on the mounted volume (Hanzo Base/SQLite). No MariaDB / Postgres / external DB.

IAM SSO

IAM application: hanzo-helpdesk on hanzo.id. IAM_CLIENT_ID=hanzo-helpdesk. OAuth2 redirect URI to register: https://help.hanzo.ai/api/method/frappe.integrations.oauth2_logins.custom/hanzo Endpoints (authoritative — from hanzo.id /.well-known/openid-configuration): authorize /v1/iam/oauth/authorize, token /v1/iam/oauth/token, userinfo /v1/iam/oauth/userinfo, jwks /v1/iam/.well-known/jwks. hanzo_sso.setup also DISABLES native signup (Website Settings disable_signup) and forces SSO-only login (System Settings disable_user_pass_login, v15+), so IAM is the ONE identity authority — no second signup path.

Multi-tenant isolation (org == tenant)

One SQLite site (== one DB) per org, resolved by the Host header: primary org (HANZO_ORG) -> SITE_NAME (help.hanzo.ai); any other org <org> -> <org>.<SITE_NAME>. Provision list = HANZO_ORGS (comma-separated). Isolation is structural: org A's tickets live in a different SQLite file than org B's, so A's tickets are never visible to B.

Build & deploy (one lifecycle)

1. arcd BuildKit Job -> ghcr.io/hanzoai/helpdesk:<semver> (context = github.com/hanzoai/helpdesk#<ref>, filename=Dockerfile).
2. Pin the semver tag in hanzoai/universe; operator reconciles the help Service CR + ingress in ns hanzo (context do-sfo3-hanzo-k8s).
3. Secrets in KMS -> help-secrets (ADMIN_PASSWORD, ENCRYPTION_KEY, IAM_CLIENT_ID, IAM_CLIENT_SECRET).