Node.js powers the backend API, MongoDB Atlas stores the data, and the Tickitz SDK keeps client integration simple — here's exactly how it is built.
What we're building
The backend is split into well-defined layers — each one responsible for a specific concern, deployable and scalable independently.
A modern Node.js API backend that handles queue orchestration, booking state, and MongoDB persistence with the official driver. Easy to self-host or deploy to any Node host.
All stateful data — events, customers, bookings, queue entries, tickets, and audit logs — lives in MongoDB Atlas with multi-region replication and automatic failover.
The beating heart of the system. Fairness-ordered waiting rooms with bot-resistant tokens, session-locked inventory, and configurable hold TTLs — all processed atomically via MongoDB transactions.
The SDK wraps the backend API so developers never touch raw fetch calls. Full TypeScript types, managed polling loops, webhook verification helpers, and auto-retry on transient failures.
@tickitz/sdkArchitecture
Your app talks to the SDK. The SDK calls the Node.js backend. The backend reads and writes MongoDB and emits webhooks back to your server. Each layer has a single responsibility and a clean boundary.
How integration works
Stand up a Node.js backend, install the SDK, configure your keys, and start calling the API. The queue and booking workflows are handled server-side with MongoDB persistence.
Install the official package from npm. Works in Node.js, browser apps, and server-rendered environments.
Pass your API key — generated in the Tickitz dashboard — to the constructor. Point the SDK at your backend API endpoint.
Define tiers, capacity, and schedule. Tickitz persists the event in MongoDB Atlas and returns a live public URL.
For high-demand drops, customers join the waiting room. The SDK manages the polling loop — you just handle position updates in your UI.
Once inventory is locked, confirm the booking against your Stripe payment intent. Tickets are auto-issued and QR codes generated instantly.
Register your endpoint in the dashboard. The backend delivers HMAC-signed events — booking confirmations, fraud alerts, queue readiness — with automatic retries.
Backend API
The Tickitz backend runs on Node.js, exposes REST endpoints for queue operations and bookings, and uses the official MongoDB driver for atomic state transitions. Authentication, queue locking, and webhook delivery all live in the same server layer.
// Node.js backend — queue join handler import express from "express"; const app = express(); app.post("/queue/join", async (req, res) => { // 1. Authenticate API key const apiKey = req.headers.get("x-api-key"); const org = await env.KV.get(`key:${apiKey}`); if (!org) return new Response("Unauthorized", { status: 401 }); // 2. Parse and validate body const body = await req.json(); const { eventId, customerId, items } = body; // 3. Atomic queue insert via MongoDB const entry = await db.queue.insertOne({ eventId, customerId, items, token: signToken(customerId, env.SECRET), joinedAt: new Date(), }); // 4. Return position return Response.json({ token: entry.token, position: await db.queue.countDocuments({ eventId, joinedAt: { $lt: entry.joinedAt } }), }); } };
MongoDB Atlas
Atlas provides the persistence layer for every object in the Tickitz system. Multi-document transactions prevent race conditions during queue confirms and booking creation. Indexes are tuned for high-concurrency event drops.
eventId + joinedAt for O(1) position queries
// MongoDB collection schemas // events collection interface EventDoc { _id: ObjectId; orgId: string; title: string; slug: string; // unique index status: "draft" | "live" | "ended"; tiers: TierDoc[]; capacity: number; soldCount: number; // atomic $inc startsAt: Date; } // queue collection — TTL index on expiresAt interface QueueDoc { _id: ObjectId; eventId: string; customerId: string; token: string; // HMAC-signed joinedAt: Date; // compound index status: "waiting" | "ready" | "expired"; expiresAt: Date; // TTL index bookingId?: string; } // bookings collection interface BookingDoc { _id: ObjectId; eventId: string; customerId: string; status: "pending" | "confirmed" | "refunded"; totalCents: number; fraudScore: number; tickets: TicketDoc[]; }
Request flow
From SDK method call to confirmed booking, here is every hop your request makes — and how the system ensures consistency even under concurrent load at event drop time.
Request lifecycle docs →Roadmap
The backend integration is being built in phases. Here is exactly where each piece stands — and what is coming next in the queue.
Get notified when it ships →The SDK is live on npm today. Backend API endpoints are in active development — get notified the moment they ship.
npm install @tickitz/sdk