Architecture

Helpdesk is a TypeScript monorepo built with Turborepo and pnpm. Everything that must survive a restart lives in PostgreSQL and in S3-compatible storage; there is no other state store.

Parts

Part	Role
api	Hono on Node.js: REST API, authentication, role checks, server-sent events for live updates, the public web form and the portal API
web	Astro with Svelte islands and Tailwind: the agent interface, settings, the contact form page and the customer portal
worker-imap	Reads mailboxes over IMAP (IDLE), runs the inbound filter chain, threads mails into tickets
worker-mailer	Sends queued outgoing mail over SMTP, signs it with DKIM, logs deliveries
packages/db	Drizzle ORM schema and migrations, the selector engine, SLA calculation
packages/types	Types shared between the apps

Queue and transactions

Jobs run through pg-boss, a queue that lives in the same PostgreSQL database. That covers inbound and outbound mail, trigger events, scheduler jobs, the SLA sweep, webhook deliveries and privacy deletion.

Creating a ticket, updating it and posting a message each run in one database transaction. The outgoing mail job is queued inside that transaction, and live events are sent only after the commit, so a failed request leaves neither a half-written ticket nor a lost or duplicated mail.

Mail in and out

Incoming mails pass an ordered filter chain before they become tickets: bounces, the system’s own address, notification loops, auto-replies, out-of-office replies and follow-ups. Matching mails are dropped. Mails that fail processing are kept in a table that admins can list, replay or delete in the settings.

Threading uses In-Reply-To and References. A ticket number in the subject ([#10423]) is a fallback, accepted only when the sender is the ticket’s customer or a known participant.

Storage

Attachments go to S3-compatible storage: MinIO for local development, and in production for example Cloudflare R2, AWS S3 or any other S3 API. The database is plain PostgreSQL and compatible with managed offerings such as Supabase.

Deployment shape

The reference deployment is Docker Compose behind Nginx, with a managed PostgreSQL. See the deployment guide.