A multi-event management platform built for large-scale events with up to 60,000 attendees and 10,000 concurrent users. QR-based entry control, configurable food distribution tracking, real-time admin dashboards, and bulk SMS invitations with custom card designs.
- Multi-event support — create and manage multiple events with independent configurations
- Event lifecycle — draft, active, live, completed, archived status tracking
- Configurable QR strategy — unified (single QR for entry + food) or separate QRs per event
- Configurable food tracking — guest-linked mode (per-person limits) or anonymous mode (volume tracking)
- Bulk import — CSV and Excel (.xlsx) file import for guest lists up to 60K
- Manual entry — add individual guests with name, phone, and category assignment
- Guest categories — admin-configurable categories (VIP, General, Staff, etc.) with different food/access privileges
- Full-text search — search guests by name or phone number across events
- Status tracking — invited, SMS sent, SMS delivered, checked in
- Batch generation — async QR code generation for entire guest lists via background workers
- HMAC-signed payloads — cryptographically signed QR data prevents forgery
- CDN-hosted images — pre-generated QR images stored in Cloudflare R2, served via CDN
- Progress tracking — real-time generation progress with percentage and ETA
- Visual editor — canvas-based drag-and-drop editor built with Fabric.js
- Template system — upload background designs, position and resize QR overlay
- Batch compositing — async card generation overlaying guest-specific QR codes onto templates
- CDN delivery — final card images stored in R2 and served via Cloudflare CDN
- Bulk sending — send SMS invitations to entire guest lists or filtered segments
- Progress tracking — real-time delivery status (queued, sending, sent, delivered, failed)
- Retry logic — automatic retries for failed deliveries with exponential backoff
- Provider abstraction — swappable SMS provider interface (SMS.net.bd default)
- Entry scanning — QR-based guest check-in at entry gates with duplicate detection
- Food scanning — QR-based food distribution tracking at vendor stalls
- Zero-credential vendor sessions — device-based sessions, no login required for operators
- Offline resilience — local queue with automatic sync when connection restores
- Idempotent processing — duplicate scans are safely rejected without race conditions
- Lua-scripted Redis operations — atomic scan validation with zero race conditions at 10K concurrent
- Live attendance — real-time guest check-in counter via SSE (Server-Sent Events)
- Food consumption analytics — per-stall and per-category consumption tracking
- Vendor activity — active scanning stations, scan rates, last activity timestamps
- Atomic counters — Redis-backed counters for instant aggregates (no COUNT queries)
- Vendor hierarchy — vendor types (entry, food) > categories (biryani, fuchka) > stalls (stall-1, stall-2)
- Food rules engine — configurable per-category limits (e.g., "1 fuchka per guest regardless of stall")
- Session management — admin can view active sessions and revoke device access
- Email/password auth — via Better Auth with Convex adapter
- Role-based access — admin (full access) and event manager (scoped to assigned events)
- Event permissions — granular per-event read/edit permissions for event managers
- First-user auto-admin — first registered user automatically becomes admin
graph TB
subgraph Clients["Clients"]
Admin["Admin Dashboard<br/><i>React · TanStack Router · Query</i>"]
Scanner["Vendor Scanner<br/><i>React · Zustand · IndexedDB offline queue</i>"]
end
subgraph Convex["Convex — CRUD & Real-time"]
ConvexDB[("Convex DB")]
Auth["Better Auth<br/><i>email/password · RBAC</i>"]
CRUD["Mutations & Queries<br/><i>events · guests · vendors<br/>stalls · food rules · categories</i>"]
Sync["Sync Endpoints<br/><i>/internal/sync/guest-checkin<br/>/internal/sync/food-consumption<br/>/internal/sync/guest-card</i>"]
AdminGW["Admin Gateway<br/><i>HMAC-signed calls to Go</i>"]
end
subgraph Go["Go Backend"]
API["API Server — chi v5<br/><i>scan validation · SSE broker<br/>device sessions · task dispatch</i>"]
Worker["Worker — asynq<br/><i>QR generation · card compositing<br/>SMS delivery · R2 upload</i>"]
end
subgraph Data["Data Layer"]
Redis[("Redis 8<br/><i>Lua scripts · atomic counters<br/>pub/sub · scan cache · job queue</i>")]
PG[("PostgreSQL 17<br/>via PgBouncer<br/><i>entry_scans · food_scans<br/>event_counters</i>")]
R2[("Cloudflare R2<br/><i>QR images · card images<br/>zero-egress CDN</i>")]
SMS["SMS Provider<br/><i>sms.net.bd</i>"]
end
Admin -- "Convex React subscriptions<br/>(real-time CRUD)" --> CRUD
Admin -- "SSE<br/>(live counters)" --> API
Scanner -- "HTTP POST<br/>(scan requests)" --> API
Scanner -- "offline queue → sync on reconnect" --> API
CRUD --> ConvexDB
Auth --> ConvexDB
AdminGW -- "HMAC POST<br/>/api/v1/qr/generate<br/>/api/v1/cards/composite<br/>/api/v1/sms/send" --> API
API -- "Lua scripts<br/>(atomic check-in & food rules)" --> Redis
API -- "publish counter updates" --> Redis
API -- "asynq enqueue" --> Worker
API -- "PG durability write" --> PG
Worker -- "progress tracking" --> Redis
Worker -- "upload images" --> R2
Worker -- "send SMS" --> SMS
Worker -- "HMAC sync<br/>(guest-checkin, food-consumption, guest-card)" --> Sync
Sync --> ConvexDB
style Clients fill:#e0f2fe,stroke:#0284c7
style Convex fill:#fef3c7,stroke:#d97706
style Go fill:#dcfce7,stroke:#16a34a
style Data fill:#f3e8ff,stroke:#9333ea
Convex excels at real-time subscriptions and CRUD with zero-config. But QR scan processing at 10K concurrent writes needs Redis Lua scripts for atomic validation and PostgreSQL for durable storage. Each system does what it does best.
sequenceDiagram
participant A as Admin Dashboard
participant C as Convex
participant G as Go API Server
participant W as Go Worker (asynq)
participant R as Redis
participant S3 as Cloudflare R2
participant SMS as SMS Provider
Note over A,C: 1. Event & Guest Setup (Convex CRUD)
A->>C: Create event, configure food rules
A->>C: Import guests (CSV/Excel, up to 60K)
A->>C: Configure guest categories & vendor stalls
Note over A,SMS: 2. Go Live — Sync to Go Backend
A->>C: Set event status → "live"
C->>G: HMAC POST /api/v1/sync/event<br/>(full dataset: guests, stalls, rules, categories)
G->>R: Bulk-load event config, guests, stalls,<br/>food rules, categories into Redis hashes
Note over A,S3: 3. QR Generation
A->>C: Trigger QR generation
C->>G: HMAC POST /api/v1/qr/generate<br/>(eventId, qrStrategy, foodQrMode)
G->>W: Enqueue TaskQRGenerateBatch
W->>W: Fan-out: one task per guest
W->>S3: Upload QR images to R2
W->>C: HMAC sync guest.qrUrls
W->>R: Update qr:progress:{eventId}
A-->>G: Poll GET /api/v1/qr/generate/{id}/progress
Note over A,S3: 4. Card Compositing
A->>C: Design card template (Fabric.js editor)
A->>C: Trigger card compositing
C->>G: HMAC POST /api/v1/cards/composite<br/>(eventId, templateId, overlay config)
G->>W: Enqueue card:composite:batch
W->>W: Fan-out: overlay QR onto template per guest
W->>S3: Upload card images to R2
W->>C: HMAC POST /internal/sync/guest-card
Note over A,SMS: 5. SMS Delivery
A->>C: Trigger SMS send
C->>G: HMAC POST /api/v1/sms/send<br/>(guest list with card URLs)
G->>W: Enqueue sms:batch
W->>W: Split into batches of 100, rate-limited
W->>SMS: Send SMS with card image links
W->>R: Update sms:{eventId}:sent/failed counters
sequenceDiagram
participant S as Vendor Scanner
participant G as Go API Server
participant R as Redis
participant PG as PostgreSQL
participant C as Convex
participant D as Admin Dashboard
Note over S,G: 1. Session Creation (zero-credential)
S->>G: POST /api/v1/session<br/>{stallId, eventId, vendorType}
G->>R: HSET session:{token} → session metadata
G-->>S: {token} → stored in localStorage
Note over S,C: 2. Entry Scan (Lua-atomic)
S->>G: POST /api/v1/scan/entry<br/>Authorization: Bearer {token}<br/>{qr_payload, additional_guests}
G->>G: HMAC-verify QR payload
G->>R: HGETALL guest:{eventId}:{guestId}
G->>R: Execute Lua check-in script atomically:<br/>SISMEMBER checkedin:{eventId} → duplicate?<br/>SADD guestId to checkedin set<br/>HSET checkin details<br/>HINCRBY attendance counter
alt Duplicate scan
G-->>S: 409 Conflict (original scan details)
G->>R: HINCRBY scans_duplicate
else Valid scan
G-->>S: 200 OK (guest info + scan result)
G->>R: PUBLISH event:{eventId}:scans → counter update
G->>PG: asynq → INSERT INTO entry_scans (durable)
G->>C: asynq → HMAC POST /internal/sync/guest-checkin
end
Note over S,C: 3. Food Scan (Lua-atomic with rules)
S->>G: POST /api/v1/scan/food<br/>{qr_payload}
G->>R: Execute Lua food scan script atomically:<br/>HGET foodrules:{eventId} → get limit<br/>Check current count vs limit<br/>HINCRBY consumption if allowed<br/>LPUSH to foodlog (last 50)
alt Limit reached
G-->>S: 200 {status: "limit_reached", history}
else Allowed
G-->>S: 200 {status: "valid", consumption}
G->>R: PUBLISH counter update
G->>PG: asynq → INSERT INTO food_scans
G->>C: asynq → HMAC POST /internal/sync/food-consumption
end
Note over D,R: 4. Real-time Dashboard (SSE)
D->>G: GET /api/v1/events/{eventId}/live (SSE)
G->>R: HGETALL counters:{eventId} → initial snapshot
G-->>D: SSE event: "snapshot" (full counter state)
G->>R: SUBSCRIBE event:{eventId}:scans
loop On each scan
R-->>G: Pub/Sub message (counter update)
G-->>D: SSE event: "counters" (delta)
end
Note over S,S: 5. Offline Resilience
S->>S: Network lost → queue scans in IndexedDB
S->>S: Network restored → replay pending scans
S->>G: Sequential POST for each queued scan
graph LR
subgraph Redis["Redis 8 — Hot Path (in-memory)"]
R1["Lua Scripts<br/><i>atomic check-in dedup<br/>food rule enforcement</i>"]
R2a["Atomic Counters<br/><i>HINCRBY attendance, food served<br/>per-category, per-stall</i>"]
R3["Pub/Sub<br/><i>event:{eventId}:scans<br/>→ SSE broker → dashboard</i>"]
R4["Scan Cache<br/><i>guest profiles, check-in state<br/>food consumption, food rules</i>"]
R5["Job Queue<br/><i>asynq: QR gen, cards,<br/>SMS, PG writes, Convex sync</i>"]
R6["Sessions<br/><i>session:{token}<br/>device → event+stall scope</i>"]
end
subgraph PG["PostgreSQL 17 — Durable Storage"]
P1["entry_scans<br/><i>idempotency_key UNIQUE<br/>event_id, guest_id, stall_id<br/>status, additional_guests</i>"]
P2["food_scans<br/><i>idempotency_key UNIQUE<br/>food_category_id, consumption_count<br/>is_anonymous, guest_category</i>"]
P3["event_counters<br/><i>attendance, scans_total<br/>per-category breakdowns</i>"]
P4["PgBouncer<br/><i>150 pool size<br/>10K max client connections</i>"]
end
subgraph ConvexDB["Convex — Canonical Source"]
C1["events<br/><i>config, status lifecycle<br/>draft→active→live→completed</i>"]
C2["guests<br/><i>qrUrls, cardImageUrl<br/>status: invited→checkedIn</i>"]
C3["vendors · stalls · categories<br/><i>hierarchy: type→category→stall</i>"]
C4["foodRules<br/><i>per-category limits<br/>guest category × food category</i>"]
C5["smsDeliveries · cardTemplates<br/><i>delivery tracking, template config</i>"]
end
style Redis fill:#fef3c7,stroke:#d97706
style PG fill:#dcfce7,stroke:#16a34a
style ConvexDB fill:#e0f2fe,stroke:#0284c7
| Path | Speed | Guarantee | How |
|---|---|---|---|
| Scan → Redis | Sub-ms | Atomic (Lua script) | Single Redis transaction, no race conditions |
| Redis → PostgreSQL | Async (~100ms) | Eventual, idempotent | asynq task with ON CONFLICT DO NOTHING |
| Redis → Convex | Async (~200ms) | Eventual, HMAC-verified | asynq task with retry (5 attempts) |
| Convex → Redis | On "go live" | Full sync | Bulk-load entire event dataset to Redis hashes |
| Scanner → Go (offline) | On reconnect | Sequential replay | IndexedDB queue, idempotency keys prevent dupes |
| Layer | Technology | Purpose |
|---|---|---|
| Frontend | React 19, Vite 8, TailwindCSS 4.2 | SPA with responsive scanner UI |
| Routing | TanStack Router | Type-safe file-based routing |
| State | TanStack Query, Zustand, Convex React | Server state, UI state, real-time subscriptions |
| Canvas | Fabric.js | Invitation card template editor |
| Auth | Better Auth + Convex adapter | Email/password with role-based access |
| CRUD / Real-time | Convex | Event/guest/vendor CRUD, live subscriptions |
| Scan Processing | Go 1.25, chi v5 | High-concurrency QR scan validation |
| Database | PostgreSQL 17 + PgBouncer | Scan data with connection pooling (10K connections) |
| Cache / Counters | Redis 8 | Atomic counters, pub/sub, scan caching |
| Background Jobs | Asynq (Redis-backed) | QR generation, card compositing, SMS delivery |
| Object Storage | Cloudflare R2 | QR/card images with zero-egress CDN |
| Real-time Push | SSE (dashboard), WebSocket (scanner) | Live event updates |
| SMS | SMS.net.bd (swappable) | Bulk invitation delivery |
| Testing | Vitest, Playwright, Go testing, testcontainers | Unit, E2E, integration |
| Infrastructure | Docker, Docker Compose | Containerized local dev and deployment |
| Tool | Version | Install |
|---|---|---|
| Node.js | 20+ | nodejs.org or nvm install 20 |
| pnpm | 10+ | corepack enable && corepack prepare pnpm@latest --activate |
| Go | 1.25+ | go.dev/dl |
| Docker | 24+ | docs.docker.com/get-docker |
| Docker Compose | v2+ | Included with Docker Desktop, or install separately |
| golang-migrate | v4 | go install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@latest |
| sqlc | v1 | go install github.com/sqlc-dev/sqlc/cmd/sqlc@latest |
Optional tools:
| Tool | Purpose | Install |
|---|---|---|
| Playwright | E2E testing | cd frontend && pnpm exec playwright install |
| k6 | Load testing | k6.io/docs/get-started/installation |
git clone https://github.com/EhsanulHaqueSiam/Eventarc.git
cd Eventarc
# Install root + Convex dependencies
pnpm install
# Install frontend dependencies
cd frontend && pnpm install && cd ..
# Install Go dependencies
cd backend && go mod download && cd ..cp .env.example .envOpen .env and fill in the required values. At minimum for local development:
# Generate an HMAC secret (required, minimum 32 bytes)
openssl rand -hex 32
# Paste the output as HMAC_SECRET in .envSee .env.example for full documentation on every variable.
docker compose up -dThis starts PostgreSQL 17, PgBouncer, and Redis 8. Wait for healthy status:
docker compose ps
# All services should show "healthy"migrate -path backend/migrations \
-database "postgres://eventarc:dev_password@localhost:5432/eventarc?sslmode=disable" upNote: Migrations run against PostgreSQL directly (port 5432), not through PgBouncer.
# First time: creates a new Convex project and deploys schema + functions
npx convex devThis populates CONVEX_DEPLOYMENT and VITE_CONVEX_URL in .env.local.
Set the required environment variables in the Convex Dashboard under Settings > Environment Variables:
| Variable | Value |
|---|---|
GO_API_URL |
http://localhost:8080 (or your Go backend URL) |
HMAC_SECRET |
Same value as in your .env |
SITE_URL |
http://localhost:5173 |
NODE_ENV |
development |
# Terminal 1 — API server
cd backend && go run ./cmd/server
# Terminal 2 — Background worker (QR generation, card compositing, SMS)
cd backend && go run ./cmd/workercd frontend && pnpm devThe app is now running at http://localhost:5173.
- Open http://localhost:5173
- Register with email and password
- The first registered user automatically becomes an admin
- Create your first event from the dashboard
eventarc/
+-- backend/ # Go microservice
| +-- cmd/
| | +-- server/ # HTTP API server entrypoint
| | +-- worker/ # Asynq background worker entrypoint
| +-- internal/
| | +-- config/ # Environment config loading
| | +-- handler/ # HTTP handlers (QR, cards, SMS, sync, sessions)
| | +-- middleware/ # CORS, HMAC auth, rate limiting, logging
| | +-- scan/ # Scan processing (entry + food), Lua scripts
| | +-- card/ # Card compositing (QR overlay on templates)
| | +-- r2/ # Cloudflare R2 client (S3-compatible)
| | +-- sms/ # SMS delivery worker
| | +-- sse/ # Server-Sent Events broker
| | +-- convexsync/ # Go -> Convex HTTP sync client
| | +-- model/ # Shared types (session, scan records)
| | +-- worker/ # Asynq task handlers
| +-- migrations/ # PostgreSQL migrations (golang-migrate)
+-- convex/ # Convex backend
| +-- schema.ts # Database schema
| +-- auth.ts # Better Auth configuration
| +-- events.ts # Event CRUD mutations/queries
| +-- guests.ts # Guest management
| +-- stalls.ts # Vendor stall management
| +-- foodRules.ts # Food distribution rules
| +-- cardTemplates.ts # Card template CRUD
| +-- smsDeliveries.ts # SMS tracking
| +-- sync.ts # Go backend sync endpoints
| +-- http.ts # HTTP router (auth + internal sync)
+-- frontend/ # React SPA
| +-- src/
| | +-- routes/ # TanStack Router file-based routes
| | +-- components/ # React components
| | +-- hooks/ # Custom hooks (scanner, sessions, offline)
| | +-- lib/ # API client, auth, Convex setup
| +-- e2e/ # Playwright E2E tests
+-- docker-compose.yml # Local dev infrastructure
+-- docker-compose.staging.yml# Production-tuned overrides
+-- .env.example # Environment variable template
cd backend
# Unit tests
go test ./...
# Integration tests (requires Docker — uses testcontainers)
go test -tags=integration ./...cd frontend
# Unit tests
pnpm exec vitest
# E2E tests (requires running app + infrastructure)
pnpm test:e2e
# E2E with browser UI
pnpm test:e2e:ui| Service | Image | Port | Purpose |
|---|---|---|---|
postgres |
postgres:17 |
5432 | Primary database |
pgbouncer |
edoburu/pgbouncer:1.25.1 |
6432 | Connection pooling (150 pool, 10K max clients) |
redis |
redis:8-alpine |
6379 | Cache, atomic counters, pub/sub, job queue |
worker |
Built from backend/ |
-- | Background job processor (QR, cards, SMS) |
For production-scale local testing:
docker compose -f docker-compose.yml -f docker-compose.staging.yml up -dThis applies tuned PostgreSQL settings (shared_buffers, work_mem), PgBouncer pool sizing, Redis memory limits, and Go runtime constraints (GOMAXPROCS, GOMEMLIMIT).
See .env.example for the complete reference with inline documentation.
| Variable | Required | Where | Description |
|---|---|---|---|
HMAC_SECRET |
Yes | Go + Convex | Request signing key (min 32 bytes) |
DATABASE_URL |
Yes | Go | PostgreSQL connection via PgBouncer |
REDIS_URL |
Yes | Go | Redis connection |
PG_PASSWORD |
Yes | Docker | PostgreSQL password |
R2_ACCOUNT_ID |
For QR/cards | Go | Cloudflare account ID |
R2_ACCESS_KEY_ID |
For QR/cards | Go | R2 API access key |
R2_SECRET_ACCESS_KEY |
For QR/cards | Go | R2 API secret key |
R2_BUCKET_NAME |
For QR/cards | Go | R2 bucket name |
R2_PUBLIC_URL |
For QR/cards | Go | CDN base URL |
CONVEX_DEPLOYMENT |
Yes | Convex CLI | Deployment identifier |
VITE_CONVEX_URL |
Yes | Frontend | Convex API endpoint |
VITE_CONVEX_SITE_URL |
Yes | Frontend | Convex site URL for auth |
VITE_API_URL |
Yes | Frontend | Go backend URL |
SMS_PROVIDER_API_KEY |
For SMS | Go | SMS provider API key |
SITE_URL |
Yes | Convex | Frontend URL for auth redirects |
ALLOWED_ORIGINS |
Production | Go | CORS allowed origins |
These are set in the Convex web dashboard, not in .env:
| Variable | Description |
|---|---|
GO_API_URL |
Go backend URL for Convex -> Go HTTP calls |
HMAC_SECRET |
Shared signing secret (same as Go backend) |
SITE_URL |
Frontend URL for auth redirects |
CONVEX_SITE_URL |
Convex site URL for email verification links |
NODE_ENV |
development or production |
Three options, from easiest to most manual:
| Method | HTTPS | Effort | Best For |
|---|---|---|---|
| Dokploy | Auto (Traefik) | Lowest | Teams wanting a web UI for deploys |
| VPS + Caddy | Auto (Let's Encrypt) | Low | Any VPS with Docker |
| Manual | You configure | Medium | Custom infrastructure |
Quick deploy (VPS with Docker):
git clone https://github.com/EhsanulHaqueSiam/Eventarc.git && cd Eventarc
cp .env.production.example .env # Fill in your values
./deploy.sh # Auto-detects Dokploy vs standaloneSee docs/DEPLOY.md for the full guide.
- Deployment Guide — Dokploy, VPS, and manual deployment instructions
- AI Deployment Prompt — Copy-paste prompt for Claude/ChatGPT/Codex to deploy for you
- Infrastructure Sizing Guide — Server configurations and cost estimates by event scale
Private. All rights reserved.






