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)

Searching Database…

205 ·GitHub
ResolveHQ
Что это такое?ResolveHQ — это helpdesk, который можно развернуть у себя и который создан специально для Cloudflare; он рассчитан на небольшие команды поддержки: общий почтовый ящик с назначением заявок, статусами, приоритетами и тегами, корректное по стандартам RFC ветвление писем, базу знаний с публичным центром помощи, отчёты и AI-помощника по желанию.
Это облачный сервис, в который я регистрируюсь, или программа, которую я запускаю сам?Софт для самостоятельного размещения, но только на Cloudflare: он работает как один Worker в вашем собственном аккаунте Cloudflare — Hono обслуживает и REST API, и встроенное React-приложение. Облачной версии, в которую можно зарегистрироваться, нет, и свои серверы администрировать не нужно.
Как мне развернуть его в своём аккаунте Cloudflare?Нажмите кнопку Deploy to Cloudflare, примените миграции (если указать команду деплоя npm run deploy, каждый следующий деплой сначала прогоняет миграции) и проверьте GET /api/ready. Затем зарегистрируйтесь как владелец и добавьте правило Email Routing, которое направляет письма с вашего адреса поддержки в Worker.
Что мне нужно перед деплоем?Аккаунт Cloudflare (Queues работают на тарифе Free, для R2 нужно отдельно включить и оплатить) и домен на Cloudflare, чтобы Email Routing мог принимать входящую почту. По желанию — аккаунт Resend с подтверждённым доменом для отправки писем.
Он правда может работать на бесплатном тарифе Cloudflare?Да, поначалу — но, скорее всего, вы его перерастёте. Workers Free даёт 10 мс процессорного времени на запрос, а тестовая регистрация заняла 29 мс; Cloudflare терпит лишь редкие превышения, поэтому следите за метриками Worker'а и переходите на Workers Paid, пока очередь не стала оживлённой.
Где хранятся мои заявки и данные клиентов?Заявки и вложения остаются в вашем собственном аккаунте Cloudflare (D1 и R2). Единственный внешний шаг — исходящая почта, которая проходит через Resend; если же включить встроенную отправку Cloudflare Email Sending на Workers Paid, содержимое писем вообще не покидает ваш аккаунт.
Отправляет ли AI-функция переписку с клиентами третьей стороне?Только если администратор сам это включит: AI-помощь по умолчанию выключена и активируется для каждого воркспейса в настройках. Она может работать на Cloudflare Workers AI внутри вашего аккаунта (ключ не нужен) или через OpenAI (по умолчанию gpt-4o-mini); если не настроено ни то ни другое, функция остаётся скрытой и никаких обращений к AI не происходит.
Могут ли Claude или Cursor подключиться к моему helpdesk?Да — Claude Code, Claude Desktop и Cursor подключаются через MCP и умеют искать заявки, читать переписку, смотреть количество заявок в очереди, находить клиентов и искать по базе знаний. Доступ сделан только для чтения специально: ни один инструмент не может ответить, назначить или что-то изменить.
Что произойдёт, если клиент ответит, пока его заявка отложена?Заявка сразу возвращается в работу. Отложенные заявки уходят из рабочих очередей и никогда не считаются просроченными, пока «спят», но ответ клиента возвращает их досрочно — так что отложить вопрос честнее, чем полагаться на свою память.
Чего пока не умеет эта программа?Многоязычного интерфейса и уведомлений за пределами приложения, восстановления экспорта воркспейса изнутри самого приложения (загрузка обратно описана как пошаговая инструкция для wrangler) и записи через MCP — AI-сервер остаётся только для чтения, пока действия ассистента нельзя будет подтверждать.
What are similar projects?mailflare, cloud-mail, mail2telegram, edgeever, DoulorCloud, all-set-tw, rankme.fast, cloudflare_temp_email
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
205
Updated
CommitSep 29Releasev0.3.4Sep 28
Age
1mo
Commits · 90 Days