QQueueDocs
GitHub

QQueue Project Status

Current capability and gap audit.

Summary

QQueue is a self-hosted beta ready for early technical users and undergoing launch preparation. The repository contains an implemented TypeScript monorepo with an Express API, React dashboard, BullMQ worker processes, Prisma/PostgreSQL data model, Redis queues, SMTP sending, tracking, transactional API keys, outbound webhooks, an MIT-licensed SDK package, tests, deployment files, and open-core licensing guardrails.

Following the Beta Polish + Launch Prep Sprint, QQueue now includes:

  • Authentication
  • Organizations
  • SMTP connections
  • Contacts
  • Contact lists
  • Templates
  • Campaigns
  • Transactional API
  • API keys
  • Tracking
  • Webhooks
  • Queue workers
  • Queue operations dashboard
  • Password reset
  • Rate limiting
  • SDK
  • Mailcow documentation
  • Docker smoke tests
  • Licensing and legal structure

With the core product surfaces implemented and the launch-prep gaps closed, the focus is shifting away from feature development toward:

  • documentation
  • onboarding
  • launch preparation
  • real-world testing
  • user feedback

The remaining open items are primarily commercial/cloud features, multi-user organization management, and qualified legal review — none of which block an early self-hosted beta.

Beta Readiness Assessment

Status: Self-Hosted Beta for Early Technical Users

Completed:

  • Authentication
  • Organizations
  • SMTP Connections
  • Contacts
  • Contact Lists
  • Templates
  • Campaigns
  • Transactional API
  • API Keys
  • Tracking
  • Webhooks
  • Queue Workers
  • Queue Operations Dashboard
  • Password Reset
  • Rate Limiting
  • SDK
  • Mailcow Documentation
  • Docker Smoke Tests
  • Licensing and Legal Structure

Assessment: The platform is suitable for early self-hosted beta users and real-world validation. All core self-hosted flows are implemented, the full verification suite (including a Docker-backed end-to-end smoke test) passes, and operational and abuse-control gaps from the original audit have been closed.

Repository Structure

  • apps/api: Express API. It owns HTTP routing, auth/session tokens, password reset, organization access checks, Prisma access, product modules, transactional sends, tracking endpoints, inbound ESP webhook normalization, queue operations endpoints, Redis-backed rate limiting, and queue enqueueing.
  • apps/web: Vite React dashboard. It includes login/register, password reset, dashboard, one-off send, SMTP connections, contacts, contact lists, templates, campaigns, campaign analytics, queue operations, settings/API keys/webhooks, and legal pages.
  • apps/worker: BullMQ workers. It processes campaign fan-out jobs, email sending jobs, outbound webhook delivery jobs, and startup recovery for queued work.
  • apps/cloud: proprietary managed-cloud boundary scaffold. It currently contains package metadata, README, and a commercial license draft, but no production cloud behavior.
  • packages/shared: shared TypeScript domain types and Zod schemas for auth, organizations, contacts, lists, templates, campaigns, transactional sends, API keys, webhooks, SMTP connections, cron validation, and timezones.
  • packages/email-engine: email provider abstraction, Nodemailer-backed SMTP provider, tracking URL/token helpers, and explicit placeholder provider classes for Mailcow/SES/Resend/Brevo/Postmark.
  • packages/sdk: MIT-licensed TypeScript SDK package. It currently wraps the public transactional email send endpoint.
  • apps/api/prisma: PostgreSQL schema and migrations for users, organizations, SMTP connections, contacts, contact lists, templates, campaigns, campaign runs, email jobs, email events, API keys, webhook endpoints, webhook deliveries, and password reset tokens.
  • scripts: coverage badge generation, dependency license audit, cloud boundary guardrail checks, and the Docker-backed smoke test (docker-smoke.ts).
  • .github/workflows: coverage, Phase 7 guardrails, and SDK publish workflows.
  • Deployment files: docker-compose.yml for local Postgres/Redis, docker-compose.prod.yml for Caddy/API/worker/Postgres/Redis/migrations, docker-compose.smoke.yml for the throwaway smoke-test stack, app Dockerfiles, and Caddyfile.

Completed So Far

Project Setup

  • pnpm workspace and Turborepo root.
  • TypeScript base config plus per-package configs.
  • ESLint and Prettier configuration.
  • Local Docker Compose for PostgreSQL and Redis.
  • Root scripts for dev, build, lint, typecheck, test, coverage, Prisma, license audit, cloud boundary checks, and Docker smoke test.
  • .env.example with local and production-oriented settings.
  • Root AGPL-3.0 core license.
  • Proprietary apps/cloud commercial license draft.
  • MIT SDK license and package metadata.
  • NOTICE.md and TRADEMARK.md.
  • Licensing overview docs.
  • Draft cloud Terms of Service and Privacy Policy under docs/legal.
  • Signed-off-by/CLA guardrail workflow for pull requests.
  • [~] Legal posture documented but marked as needing qualified legal review.
  • Lawyer review for commercial license, CLA, Terms, Privacy Policy, and dependency license output.

Core Platform

  • Express app setup with CORS, JSON body parsing, request logging, health route, v1 router, and error handling.
  • Module structure with route/controller/service separation.
  • Prisma client integration.
  • PostgreSQL schema and migrations.
  • Organization membership helper and role checks.
  • Redis-backed rate limiting on auth and public sending paths.

Auth

  • Register creates a user and first organization.
  • Login returns user organizations and auth tokens.
  • Refresh token endpoint exists.
  • Password hashing and JWT token helpers are tested.
  • Auth middleware protects dashboard routes.
  • Password reset flow (request, token, confirm).
  • Password reset email delivery (sent via the organization's SMTP connection).
  • Password reset token invalidation.
  • [~] Still lacks email verification, MFA, and session/device management.

Security

  • Redis-backed rate limiting covering:
    • register
    • login
    • refresh token
    • password reset requests
    • transactional send endpoint
  • Encrypted SMTP credentials at rest.
  • HMAC-signed tracking tokens and signed outbound webhook deliveries.

Operations

  • Queue operations dashboard (web page).
  • Queue summaries (queued, processing, failed counts).
  • Failed job visibility with attempt counts and failure reasons.
  • Retry failed jobs.
  • Queue monitoring API.
  • Queue operations access restricted to OWNER/ADMIN roles.

Documentation

Organizations

  • Organization model and membership model exist.
  • Organization CRUD routes/services exist.
  • Access and role helpers exist.
  • [~] Organization members beyond initial owner are modeled but no invitation or member-management UI/workflow exists yet.

SMTP Connections

  • SMTP connection CRUD exists.
  • Credentials are encrypted before storage.
  • Create/update verifies SMTP connectivity with Nodemailer.
  • Default SMTP connection selection is implemented.
  • Dashboard page exists.
  • Dedicated Mailcow setup documentation.

Contacts, Templates, and Campaigns

  • Contacts CRUD exists.
  • Contact lists CRUD and contact membership exist.
  • Templates CRUD exists.
  • Campaign drafts, duplicate, delete, send now, one-shot schedule, recurrence, pause, resume, and analytics exist.
  • Dashboard pages exist for contacts, contact lists, templates, campaigns, and analytics.
  • [~] Template variables are simple string replacement.

Queues and Workers

  • Redis/BullMQ queue definitions exist for email sending, campaign processing, and webhook delivery.
  • API enqueues sends/campaigns/webhook deliveries.
  • Worker sends email through SMTP and records events.
  • Campaign worker expands active contacts into queued email jobs.
  • Webhook worker delivers signed outbound webhooks.
  • Worker startup recovers queued email jobs, scheduled campaigns, recurring campaigns, and pending/failed webhook deliveries.
  • Queue operations dashboard and API for queue summaries, failed jobs, and retries.

Transactional API

  • API key model, creation, listing, revocation, hashing, and auth exist.
  • Public transactional send endpoint accepts API keys.
  • Dashboard JWT flow can also use transactional send with organization ID.
  • Direct content and template-based sends exist.
  • Delayed sends with scheduledAt exist.
  • Stable { id, status } response and machine-readable error codes exist.
  • Transactional API docs and SDK examples exist.
  • Redis-backed rate limiting on the send endpoint.
  • [~] Idempotency keys and usage tracking are not yet implemented.

Tracking and Webhooks

  • Open tracking pixel and click redirect endpoints exist.
  • HMAC-signed tracking tokens exist.
  • Tracking injection rewrites absolute links and appends a pixel.
  • Inbound normalized ESP webhook endpoint exists for delivered, bounced, and complained events.
  • Outbound webhook endpoints, signed deliveries, delivery history, and manual retry exist.
  • [~] Provider-specific inbound webhook adapters are not implemented; docs describe mapping provider payloads through a relay/function.

SDK

  • qqueue-sdk package exists with MIT license.
  • QQueueClient.sendEmail wraps the transactional send endpoint.
  • SDK error class exposes HTTP status and optional error code.
  • README, changelog, release checklist, npm publish workflow, and package tarball are present.
  • [~] SDK scope is narrow: no clients for templates, contacts, campaigns, webhooks, or API keys.

Admin / Dashboard

  • Dashboard shell and session context exist.
  • Operational pages exist for the main self-hosted flows.
  • Queue operations page for OWNER/ADMIN members.
  • Settings page includes organization creation, API keys, and webhook endpoint/delivery management.
  • [~] Admin capabilities are product-level but not full hosted-operations admin: no billing dashboard, tenant ops dashboard, deliverability admin, or abuse review tools.

Cloud / Proprietary Setup

  • apps/cloud fenced package exists.
  • Cloud README and license boundary docs exist.
  • Script prevents core packages from depending on @qqueue/cloud.
  • CI runs cloud boundary checks.
  • Billing, usage metering, hosted onboarding, managed sending infrastructure, cloud admin dashboards, and tenant operations are not started.

Tests

  • Vitest configs exist for API, web, worker, shared, email-engine, and SDK.
  • API service/middleware/lib/app tests exist.
  • Worker lib/worker tests exist.
  • Web component/page/lib/route tests exist.
  • Shared, email-engine, and SDK tests exist.
  • Queues are stubbed in API tests, eliminating Redis noise from the suite.
  • Docker-backed integration smoke test (pnpm test:smoke:docker).
  • End-to-end smoke test: register → SMTP → transactional send → worker processing.
  • Coverage thresholds are documented in the README.

CI / Scripts

  • Coverage workflow runs install, Prisma generate, coverage tests, badge generation, and badge commit on main.
  • Phase 7 guardrail workflow runs cloud boundary, dependency license audit, and Signed-off-by checks.
  • SDK publish workflow verifies tag/version alignment and runs SDK checks before npm publish.
  • Coverage badge generation script exists.
  • Dependency license audit script exists.
  • Cloud boundary script exists.
  • Docker smoke-test script (scripts/docker-smoke.ts) exists.

Current Capabilities

End-to-end, the app can currently support a self-hosted operator who:

  1. Starts PostgreSQL and Redis locally or runs the production Docker Compose stack behind Caddy.
  2. Registers a user and creates the first organization.
  3. Logs into the React dashboard.
  4. Recovers an account through the password reset flow.
  5. Creates and verifies an SMTP connection.
  6. Creates contacts, contact lists, and templates.
  7. Sends a one-off transactional email from the dashboard or API key.
  8. Creates campaigns, sends now, schedules one-shot campaigns, configures recurring campaigns, pauses/resumes campaigns, and views campaign analytics.
  9. Records queued, sent, delivered, opened, clicked, bounced, complained, and failed events where the matching flow emits them.
  10. Monitors queues, inspects failed jobs, and retries them from the queue operations dashboard (OWNER/ADMIN only).
  11. Creates outbound webhook endpoints, receives signed webhook deliveries, views recent attempts, and manually retries failed deliveries.
  12. Uses the SDK to call the transactional send API.

Known Gaps

Product

  • Organization invitation flow
  • Member management UI
  • Usage metrics dashboard
  • Transactional send idempotency keys
  • Provider-specific inbound webhook adapters
  • Expanded SDK functionality beyond sendEmail

UX

  • Hide Queue Operations navigation for non-admin members
  • Improve password reset experience when no SMTP connection exists

Cloud / Commercial

  • Billing
  • Plans and subscriptions
  • Usage quotas
  • Hosted onboarding
  • Managed infrastructure
  • Deliverability tooling
  • Cloud admin dashboards
  • Lawyer review of commercial license
  • Lawyer review of Terms of Service
  • Lawyer review of Privacy Policy
  • Review dependency license audit output

Public Beta Checklist

  • Mailcow guide.
  • Password reset.
  • Rate limiting for auth and public transactional send endpoints.
  • Queue operations dashboard for failed/queued/retry state.
  • Docker-backed integration smoke test (API + Postgres + Redis + worker).
  • Legal docs draft (Terms, Privacy Policy, licenses, trademark notice).
  • Verification suite passing (lint, typecheck, build, test, test:smoke:docker, license:audit, cloud:boundary).
  • Verify production Docker Compose from a clean checkout on a fresh host.
  • Review legal docs, CLA, commercial license, trademark notice, and dependency license output with qualified counsel before commercial use.
  1. Create landing page at qqueue.app.
  2. Record demo video using the Demo walkthrough.
  3. Open-source public release preparation.
  4. Gather first beta users.
  5. Add organization invitations.
  6. Add member management.
  7. Add usage metrics dashboard.
  8. Expand SDK functionality.
  9. Improve onboarding UX.
  10. Collect feedback from real installations.

Verification

Verified with the following commands on 2026-06-11:

  • pnpm lint passed.
  • pnpm typecheck passed.
  • pnpm build passed.
  • pnpm test passed: 62 test files and 536 tests passed across API, web, worker, shared, email-engine, and SDK packages.
  • pnpm test:smoke:docker passed: a throwaway Postgres + Redis stack ran the full register → SMTP connection → transactional send → worker processing flow and confirmed the job reached SENT.
  • pnpm license:audit passed. The audit reported reviewed license tokens including MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause, ISC, MPL-2.0, CC-BY-4.0, BlueOak-1.0.0, MIT-0, and Python-2.0.
  • pnpm cloud:boundary passed.

Notes:

  • Password reset emails are now delivered through the organization's SMTP connection (preferring the default connection) rather than a separate system mailer.
  • Queue operations are restricted to OWNER/ADMIN roles via requireOrgRole.
  • Redis noise in the API test suite has been eliminated through global queue stubbing in apps/api/src/test/setup.ts.
  • No production credentials or destructive commands were used.