ResolveHQ README

The project's README from github.com/mirza-rizvi/ResolveHQ. As one markdown file: README.md.

ResolveHQ

CI Release License: source-available Runs on Cloudflare Workers

ResolveHQ is a Cloudflare-native, self-hostable helpdesk for small support teams.

Requirements: a Cloudflare account and a domain on Cloudflare (for Email Routing). Runs on the Free plan for small teams.

Deploy to Cloudflare

Screenshots

The three-pane inbox, showing a ticket thread with an internal note and a queued reply:

Inbox with a ticket open, showing the queue list and conversation thread
Dashboard with open, unassigned, and urgent ticket counts, plus recent tickets and activity Overview dashboard Reports page showing ticket volume, response times, and breakdowns by status and priority Reports
Knowledge base article list with draft and published articles Knowledge base Public help center page listing published articles by category Public help center
Automations page with two rules and their conditions and actions Automations Inbox in dark mode with the same ticket thread open Dark mode

More screenshots, including the mobile view and the customer and settings pages, are in docs/images/.

What you can do

Interface

The workspace uses a Slack-inspired aubergine sidebar, self-hosted Lato typography, Lucide icons, and Radix UI primitives. Theme-aware controls and status colors support light and dark workspaces. On mobile, bottom navigation and a keyboard-accessible workspace drawer keep all destinations available; ticket columns adapt to preserve subject readability.

Use Cmd/Ctrl+K to jump between pages. The sidebar dock contains notifications, theme switching, and account actions.

How it works

ResolveHQ runs as a single Cloudflare Worker in your own account. Hono serves both the REST API and the built React application. Cloudflare D1 holds tickets and customers, Cloudflare R2 holds attachments, and Cloudflare Queues carry inbound and outbound mail jobs. Cloudflare Email Routing delivers incoming mail to the Worker, and Resend sends outgoing mail. Tickets and attachments are stored in your Cloudflare account; outbound email content passes through Resend. On Workers Paid you can send natively through Cloudflare Email Sending instead, and no mail content leaves your account.

How much does it cost?

ResolveHQ can run on Cloudflare's Free plan for getting started and light use, provided usage stays within the current limits for Workers, D1, R2, Queues, Cron Triggers, and Email Routing. Expect to outgrow Free. Workers Free allows 10 ms of CPU per request; a signup on one Free deployment measured 29 ms, and several other paths also ran over 10 ms on an empty workspace. Cloudflare tolerates a Worker that exceeds the limit infrequently, which is why that deployment works, but the margin shrinks as tickets, customers and notifications accumulate. Measure CPU time under your Worker's Metrics and move to Workers Paid before the queue gets busy. Queues are available on Workers Free. R2 requires account activation and billing setup separately. Resend handles outbound email under its own limits. See the Free-plan audit.

Deploy

The easiest way to get started is with the Deploy to Cloudflare button above. You will need:

Check the deployment before signing up. GET /api/ready answers without a session:

curl https://<your-worker>/api/ready   # {"ok":true,"database":"ready"}

If it reports "database":"unmigrated", apply the migrations once and re-check:

npx wrangler login          # if this machine is not already authenticated
npm run db:migrate:remote   # wrangler d1 migrations apply DB --remote

Setting the Worker's Deploy command to npm run deploy in the Cloudflare dashboard makes every later deploy migrate first. See the deployment guide.

To check a deployment end to end, including the parts that only fail on real Cloudflare infrastructure:

npm run smoke -- https://<your-worker>            # read-only checks
npm run smoke -- https://<your-worker> --signup   # also creates one throwaway workspace

After that, open your ResolveHQ URL and sign up as the owner, giving an optional support email that becomes your default inbox. In the Cloudflare dashboard, add an Email Routing rule sending that address to the deployed Worker, then send a test email to confirm it arrives in the inbox.

See the deployment guide for what the deploy flow provisions, required configuration, first-run setup, and manual deployment.

Local development

npm install
cp .dev.vars.local.example .dev.vars
npm run db:migrate:local
npm run db:seed:local
npm run dev

npm run dev starts a single Vite dev server on http://localhost:5173. The @cloudflare/vite-plugin runs worker.ts inside the Workers runtime behind it, so the SPA and /api share one origin and there is no proxy and no second port. The React app hot-reloads; editing Worker code reloads the Worker.

npm run preview builds nothing on its own — run npm run build first — and then serves the built output in the Workers runtime on http://localhost:4173, which is the closest local match to production.

Handlers that have no HTTP route of their own are triggered through the runtime's handler URLs:

# Run the cron handler once (the schedule itself does not fire locally)
curl "http://localhost:5173/cdn-cgi/handler/scheduled?cron=*/5+*+*+*+*"

# Deliver a raw RFC822 message to the email handler
curl -X POST --data-binary @message.eml \
  "http://localhost:5173/cdn-cgi/handler/[email protected]&[email protected]"

Queue producers and consumers run locally as well; messages are delivered by the local queue simulator. Workers AI has no local simulator, so with the ai binding uncommented the dev server needs wrangler login or CLOUDFLARE_API_TOKEN.

Documentation

Optional configuration

Not yet implemented

License

See LICENSE.

ResolveHQ (mirza-rizvi/ResolveHQ)

cloudflare-d1
Searching Database…

206 ·GitHub
ResolveHQ
What is this?ResolveHQ is a self-hostable, Cloudflare-native helpdesk for small support teams: a shared inbox with ticket assignment, statuses, priorities and tags, RFC-correct email threading, a knowledge base with a public help center, reports and an opt-in AI assistant.
Is this a hosted SaaS I sign up for, or something I run myself?Self-hosted software, but Cloudflare-only: it runs as a single Worker in your own Cloudflare account — Hono serves both the REST API and the built React app. There is no hosted version to sign up for, and no servers of your own to manage.
How do I actually deploy it to my Cloudflare account?Use the Deploy to Cloudflare button, apply migrations (setting the deploy command to npm run deploy makes every later deploy migrate first) and check GET /api/ready. Then sign up as the owner and add an Email Routing rule pointing your support address at the Worker.
What do I need before deploying?A Cloudflare account (Queues work on Free, R2 needs separate activation and billing) and a domain on Cloudflare so Email Routing can deliver inbound mail. Optionally a Resend account with a verified sending domain for outgoing mail.
Can it really run on Cloudflare's Free plan?Yes, at first — but expect to outgrow it. Workers Free allows 10 ms of CPU per request and a measured signup took 29 ms; Cloudflare only tolerates infrequent overshoot, so watch your Worker's Metrics and move to Workers Paid before the queue gets busy.
Where does my ticket and customer data end up?Tickets and attachments stay in your own Cloudflare account (D1 and R2). The one external hop is outbound mail, which passes through Resend — unless you enable native Cloudflare Email Sending on Workers Paid, then no mail content leaves your account.
Does the AI feature send customer conversations to a third party?Only if an admin opts in: AI assistance is off by default and enabled per workspace in Settings. It can run on Cloudflare Workers AI inside your own account (no key needed) or via OpenAI (default gpt-4o-mini); with neither configured the feature stays hidden and no AI calls are made.
Can Claude or Cursor connect to my helpdesk?Yes — Claude Code, Claude Desktop and Cursor connect over MCP to search tickets, read threads, check queue counts, look up customers and search the knowledge base. It is read-only on purpose: no tool can reply, assign or change anything.
What happens if a customer replies while their ticket is snoozed?The ticket comes back immediately. Snoozed tickets leave the working queues and never count as overdue while they sleep, but a customer reply returns them early — so deferring something is honest rather than a bet on your memory.
What can it not do yet?Multi-language interface and notifications outside the app, restoring a workspace export from inside the app (loading one back is a documented wrangler runbook instead), and write access over MCP — the AI server stays read-only until assistant actions can be approved.
What are similar projects?mailflare, opendesk, cloud-mail, mail2telegram, edgeever, DoulorCloud, all-set-tw, rankme.fast
Which topics is it in?customer-support, hono, cloudflare-r2, cloudflare-d1, drizzle-orm, webhooks, cloudflare-workers, email, cloudflare, knowledge-base, mcp-server, react
Creator
mirza-rizvi
Size
3.6 MB
Stars
206
Updated
CommitSep 29Releasev0.3.4Sep 28
Age
1mo
Commits · 90 Days