# mirza-rizvi/resolvehq architecture

> Architecture diagram of the GitHub repository mirza-rizvi/resolvehq, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mirza-rizvi/resolvehq
- Repository: https://github.com/mirza-rizvi/resolvehq

## Overview

ResolveHQ is a self-hostable, Cloudflare-native helpdesk. Agents work tickets in the shared inbox; the Worker API applies tenant-aware ticket operations, persists workspace data, and coordinates mail and other side effects. The product also includes customer and knowledge-base management, reporting, automations, SLAs, surveys, integrations, backups, and privacy workflows. The README documents the Cloudflare services and major capabilities; source excerpts show selected ticket and frontend wiring, so unsampled subsystem links are omitted rather than inferred.

Main entry points: [`src/server/tickets/routes.ts`](https://github.com/mirza-rizvi/resolvehq/blob/dev/src/server/tickets/routes.ts) (Ticket operations), [`src/server/db/schema.ts`](https://github.com/mirza-rizvi/resolvehq/blob/dev/src/server/db/schema.ts) (D1 workspace data), [`src/web/main.tsx`](https://github.com/mirza-rizvi/resolvehq/blob/dev/src/web/main.tsx) (Web application), [`src/server/mail/queue.ts`](https://github.com/mirza-rizvi/resolvehq/blob/dev/src/server/mail/queue.ts) (Mail processing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Workspace interface"]
  node_browser["Web application<br/>[main.tsx]"]
  node_inbox["Shared inbox<br/>[inbox.tsx]"]
  node_customer_ui["Customer workspace<br/>[customers.tsx]"]
  node_knowledge_ui["Knowledge interface<br/>[knowledge-base.tsx]"]
end

subgraph group_core["Helpdesk operations"]
  node_ticket_api["Ticket operations<br/>[routes.ts]"]
  node_ticket_service["Ticket service<br/>[service.ts]"]
  node_customer_api["Customer operations<br/>[routes.ts]"]
  node_auth["Authentication<br/>[middleware.ts]"]
end

subgraph group_workspace["Workspace capabilities"]
  node_knowledge_api["Knowledge base<br/>[routes.ts]"]
  node_automation["Automations<br/>[service.ts]"]
  node_sla["SLA policies<br/>[service.ts]"]
  node_reporting["Reports<br/>[routes.ts]"]
  node_satisfaction["Customer ratings<br/>[routes.ts]"]
  node_mcp["Read-only assistant tools<br/>[tools.ts]"]
  node_webhooks["Outbound webhooks<br/>[outbound.ts]"]
  node_privacy["Privacy workflows<br/>[service.ts]"]
  node_backups["Workspace backups<br/>[service.ts]"]
end

subgraph group_platform["Runtime and storage"]
  node_worker["Cloudflare Worker<br/>[worker.ts]"]
  node_app["HTTP application<br/>[app.ts]"]
  node_database[("D1 workspace data<br/>[schema.ts]")]
  node_attachments[("R2 attachments<br/>[routes.ts]")]
  node_mail["Mail processing<br/>[queue.ts]"]
end

subgraph group_integrations["External services"]
  node_email_routing["Cloudflare Email Routing"]
  node_resend["Resend email"]
  node_ai_provider["AI provider<br/>[ai.ts]"]
  node_slack_telegram["Slack or Telegram"]
end

node_agent(("Support agent"))
node_customer(("Customer"))
node_customer_mail(("Customer email client"))

node_agent -->|"uses"| node_browser
node_browser -->|"routes to"| node_inbox
node_browser -->|"routes to"| node_customer_ui
node_browser -->|"routes to"| node_knowledge_ui
node_inbox -->|"requests tickets"| node_ticket_api
node_customer_ui -->|"manages customers"| node_customer_api
node_knowledge_ui -->|"manages articles"| node_knowledge_api
node_customer -->|"receives replies"| node_customer_mail
node_customer_mail -->|"replies to tickets"| node_ticket_api
node_ticket_api -->|"delegates updates"| node_ticket_service
node_ticket_api -->|"gets targets"| node_sla
node_ticket_api -->|"applies rules"| node_automation
node_ticket_api -->|"emits events"| node_webhooks
node_ticket_api -->|"reads and writes"| node_database
node_ticket_api -->|"dispatches mail"| node_mail
node_auth -.->|"resolves tenant"| node_database
node_worker -->|"serves API"| node_app
node_app -.->|"routes requests"| node_ticket_api
node_email_routing -->|"delivers inbound mail"| node_worker
node_worker -->|"handles queue jobs"| node_mail
node_mail -->|"sends mail"| node_resend
node_mail -->|"receives mail"| node_email_routing
node_ticket_api -.->|"supports attachments"| node_attachments
node_ticket_api -.->|"offers ratings"| node_satisfaction
node_mcp -.->|"reads helpdesk data"| node_database
node_ticket_api -.->|"drafts replies"| node_ai_provider
node_webhooks -.->|"notifies channels"| node_slack_telegram
node_privacy -.->|"exports or erases"| node_database
node_backups -.->|"exports tables"| node_database
node_reporting -.->|"queries metrics"| node_database

click node_browser "https://github.com/mirza-rizvi/resolvehq/blob/dev/src/web/main.tsx"
click node_inbox "https://github.com/mirza-rizvi/resolvehq/blob/dev/src/web/pages/inbox.tsx"
click node_customer_ui "https://github.com/mirza-rizvi/resolvehq/blob/dev/src/web/pages/customers.tsx"
click node_knowledge_ui "https://github.com/mirza-rizvi/resolvehq/blob/dev/src/web/pages/knowledge-base.tsx"
click node_ticket_api "https://github.com/mirza-rizvi/resolvehq/blob/dev/src/server/tickets/routes.ts"
click node_ticket_service "https://github.com/mirza-rizvi/resolvehq/blob/dev/src/server/tickets/service.ts"
click node_customer_api "https://github.com/mirza-rizvi/resolvehq/blob/dev/src/server/customers/routes.ts"
click node_auth "https://github.com/mirza-rizvi/resolvehq/blob/dev/src/server/auth/middleware.ts"
click node_knowledge_api "https://github.com/mirza-rizvi/resolvehq/blob/dev/src/server/knowledge-base/routes.ts"
click node_automation "https://github.com/mirza-rizvi/resolvehq/blob/dev/src/server/automations/service.ts"
click node_sla "https://github.com/mirza-rizvi/resolvehq/blob/dev/src/server/sla/service.ts"
click node_reporting "https://github.com/mirza-rizvi/resolvehq/blob/dev/src/server/reports/routes.ts"
click node_satisfaction "https://github.com/mirza-rizvi/resolvehq/blob/dev/src/server/csat/routes.ts"
click node_mcp "https://github.com/mirza-rizvi/resolvehq/blob/dev/src/server/mcp/tools.ts"
click node_webhooks "https://github.com/mirza-rizvi/resolvehq/blob/dev/src/server/webhooks/outbound.ts"
click node_privacy "https://github.com/mirza-rizvi/resolvehq/blob/dev/src/server/privacy/service.ts"
click node_backups "https://github.com/mirza-rizvi/resolvehq/blob/dev/src/server/backups/service.ts"
click node_worker "https://github.com/mirza-rizvi/resolvehq/blob/dev/worker.ts"
click node_app "https://github.com/mirza-rizvi/resolvehq/blob/dev/src/server/app.ts"
click node_database "https://github.com/mirza-rizvi/resolvehq/blob/dev/src/server/db/schema.ts"
click node_attachments "https://github.com/mirza-rizvi/resolvehq/blob/dev/src/server/attachments/routes.ts"
click node_mail "https://github.com/mirza-rizvi/resolvehq/blob/dev/src/server/mail/queue.ts"
click node_ai_provider "https://github.com/mirza-rizvi/resolvehq/blob/dev/src/server/providers/ai.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_browser,node_inbox,node_customer_ui,node_knowledge_ui,node_customer_mail toneBlue
class node_ticket_api,node_ticket_service,node_customer_api,node_auth toneAmber
class node_knowledge_api,node_automation,node_sla,node_reporting,node_satisfaction,node_mcp,node_webhooks,node_privacy,node_backups toneMint
class node_worker,node_app,node_database,node_attachments,node_mail toneRose
class node_email_routing,node_resend,node_ai_provider,node_slack_telegram,node_agent,node_customer toneIndigo
```

## Components

### Workspace interface

- [Web application](https://github.com/mirza-rizvi/resolvehq/blob/dev/src/web/main.tsx): `src/web/main.tsx`
- [Shared inbox](https://github.com/mirza-rizvi/resolvehq/blob/dev/src/web/pages/inbox.tsx): `src/web/pages/inbox.tsx`
- [Customer workspace](https://github.com/mirza-rizvi/resolvehq/blob/dev/src/web/pages/customers.tsx): `src/web/pages/customers.tsx`
- [Knowledge interface](https://github.com/mirza-rizvi/resolvehq/blob/dev/src/web/pages/knowledge-base.tsx): `src/web/pages/knowledge-base.tsx`

### Helpdesk operations

- [Ticket operations](https://github.com/mirza-rizvi/resolvehq/blob/dev/src/server/tickets/routes.ts): `src/server/tickets/routes.ts`
- [Ticket service](https://github.com/mirza-rizvi/resolvehq/blob/dev/src/server/tickets/service.ts): `src/server/tickets/service.ts`
- [Customer operations](https://github.com/mirza-rizvi/resolvehq/blob/dev/src/server/customers/routes.ts): `src/server/customers/routes.ts`
- [Authentication](https://github.com/mirza-rizvi/resolvehq/blob/dev/src/server/auth/middleware.ts): `src/server/auth/middleware.ts`

### Workspace capabilities

- [Knowledge base](https://github.com/mirza-rizvi/resolvehq/blob/dev/src/server/knowledge-base/routes.ts): `src/server/knowledge-base/routes.ts`
- [Automations](https://github.com/mirza-rizvi/resolvehq/blob/dev/src/server/automations/service.ts): `src/server/automations/service.ts`
- [SLA policies](https://github.com/mirza-rizvi/resolvehq/blob/dev/src/server/sla/service.ts): `src/server/sla/service.ts`
- [Reports](https://github.com/mirza-rizvi/resolvehq/blob/dev/src/server/reports/routes.ts): `src/server/reports/routes.ts`
- [Customer ratings](https://github.com/mirza-rizvi/resolvehq/blob/dev/src/server/csat/routes.ts): `src/server/csat/routes.ts`
- [Read-only assistant tools](https://github.com/mirza-rizvi/resolvehq/blob/dev/src/server/mcp/tools.ts): `src/server/mcp/tools.ts`
- [Outbound webhooks](https://github.com/mirza-rizvi/resolvehq/blob/dev/src/server/webhooks/outbound.ts): `src/server/webhooks/outbound.ts`
- [Privacy workflows](https://github.com/mirza-rizvi/resolvehq/blob/dev/src/server/privacy/service.ts): `src/server/privacy/service.ts`
- [Workspace backups](https://github.com/mirza-rizvi/resolvehq/blob/dev/src/server/backups/service.ts): `src/server/backups/service.ts`

### Runtime and storage

- [Cloudflare Worker](https://github.com/mirza-rizvi/resolvehq/blob/dev/worker.ts): `worker.ts`
- [HTTP application](https://github.com/mirza-rizvi/resolvehq/blob/dev/src/server/app.ts): `src/server/app.ts`
- [D1 workspace data](https://github.com/mirza-rizvi/resolvehq/blob/dev/src/server/db/schema.ts): `src/server/db/schema.ts`
- [R2 attachments](https://github.com/mirza-rizvi/resolvehq/blob/dev/src/server/attachments/routes.ts): `src/server/attachments/routes.ts`
- [Mail processing](https://github.com/mirza-rizvi/resolvehq/blob/dev/src/server/mail/queue.ts): `src/server/mail/queue.ts`

### External services

- **Cloudflare Email Routing**
- **Resend email**
- [AI provider](https://github.com/mirza-rizvi/resolvehq/blob/dev/src/server/providers/ai.ts): `src/server/providers/ai.ts`
- **Slack or Telegram**

### Other components

- **Support agent**
- **Customer**
- **Customer email client**

## Connections

- Support agent → Web application: uses
- Web application → Shared inbox: routes to (evidence: `src/web/main.tsx`)
- Web application → Customer workspace: routes to (evidence: `src/web/main.tsx`)
- Web application → Knowledge interface: routes to (evidence: `src/web/main.tsx`)
- Shared inbox → Ticket operations: requests tickets
- Customer workspace → Customer operations: manages customers
- Knowledge interface → Knowledge base: manages articles
- Customer → Customer email client: receives replies
- Customer email client → Ticket operations: replies to tickets
- Ticket operations → Ticket service: delegates updates (evidence: `src/server/tickets/routes.ts`)
- Ticket operations → SLA policies: gets targets (evidence: `src/server/tickets/routes.ts`)
- Ticket operations → Automations: applies rules (evidence: `src/server/tickets/routes.ts`)
- Ticket operations → Outbound webhooks: emits events (evidence: `src/server/tickets/routes.ts`)
- Ticket operations → D1 workspace data: reads and writes (evidence: `src/server/tickets/routes.ts`)
- Ticket operations → Mail processing: dispatches mail (evidence: `src/server/tickets/routes.ts`)
- Authentication → D1 workspace data: resolves tenant
- Cloudflare Worker → HTTP application: serves API
- HTTP application → Ticket operations: routes requests
- Cloudflare Email Routing → Cloudflare Worker: delivers inbound mail
- Cloudflare Worker → Mail processing: handles queue jobs (evidence: `worker.ts`)
- Mail processing → Resend email: sends mail
- Mail processing → Cloudflare Email Routing: receives mail
- Ticket operations → R2 attachments: supports attachments
- Ticket operations → Customer ratings: offers ratings
- Read-only assistant tools → D1 workspace data: reads helpdesk data
- Ticket operations → AI provider: drafts replies
- Outbound webhooks → Slack or Telegram: notifies channels
- Privacy workflows → D1 workspace data: exports or erases
- Workspace backups → D1 workspace data: exports tables
- Reports → D1 workspace data: queries metrics
