Introduction

revento is a multi-tenant event RSVP, ticketing, and onsite redemption platform. Organizations run invite-only events end to end: tenants and admins manage campaigns from an internal dashboard, invitees RSVP through a public landing page and receive a QR ticket, and onsite officers validate and redeem those tickets from a mobile PWA — with email / WhatsApp notifications and a full activity log behind it all.

What revento does

Quick start

Run revento locally against a Supabase project.

Prerequisites

• Node.js 20+
• A Supabase project (Postgres)
• npm (a package-lock.json is committed)

Setup

# 1. Install dependencies
npm install

# 2. Configure environment — create .env.local (see Environment variables)

# 3. Apply database migrations to your Supabase project
#    (Supabase CLI or SQL editor — see supabase/migrations/)

# 4. Run the dev server
npm run dev

Open http://localhost:3000.

Demo accounts

The demo seed provisions a sample tenant + campaign and an account for every role.

Architecture

revento is a single Next.js 16 (App Router) application on React 19, TypeScript, and Tailwind CSS v4, backed by Supabase (Postgres). Safety-critical domain logic is written with Effect as typed, tagged-error pipelines.

How requests flow

• The Dashboard uses React Server Components + Server Actions for all CRUD. src/proxy.ts (Next 16 middleware) verifies the JWT session cookie before any /admin/* request reaches a page.
• Public RSVP and the Officer PWA call Route Handlers under /api/*; the dashboard's report export hits /api/admin/:slug/report.
• Core business logic lives in a service layer. RSVP submission and officer redemption are Effect pipelines that map cleanly to HTTP status codes; plain async services handle PDF report assembly and AI insight.
• The most safety-critical write (RSVP → ticket) is a single Postgres RPC (submit_rsvp) that locks the invitee row, is idempotent on re-submit, and creates the RSVP + ticket + activity log atomically.

Tech stack

The four surfaces

revento is one app with deliberately separate front-end surfaces. They do not share a shell — this separation is a hard rule in the codebase.

Data model

Core entities live in Supabase Postgres — 15 tables. DB rows (snake_case) are mapped to TS shapes (camelCase) in src/lib/db/mappers.ts; domain types live in src/lib/types/domain.ts.

Key relationships

• tenants own campaigns and configure notification_channel_options.
• campaigns have invitees and are staffed by officers.
• An invitee submits one rsvp, which mints one ticket.
• A ticket is redeemed via redemptions performed by officers.
• Every flow writes to activity_logs, notification_logs, or scan_attempt_logs.

Full table list

tenants, campaigns, invitees, rsvps, tickets, officers, officer_sessions, redemptions, scan_attempt_logs, admins, magic_link_tokens, notification_channel_options, notification_logs, activity_logs, app_settings.

Roles & RBAC

canAdminAccessCampaign(admin, campaign) (src/lib/auth/rbac.ts) enforces scope.

The /admin/rbac page renders a role × menu matrix over the menu keys dashboard, tenant, campaign, admin, rbac, setting.

State machines

Campaign status

scheduled → active → paused → active → closed → archived

A campaign moves from scheduled to active, can be paused and resumed, then closed and finally archived.

Ticket status

active ─┬→ redeemed   (officer redeems)
        ├→ revoked    (admin revokes)
        └→ expired    (window passes)

Campaigns

Campaigns are created from /admin/campaigns/new with a guided wizard. Each campaign owns its slug, event window, venue + map, RSVP window, redemption window, landing assets, and notification templates.

Wizard steps

1. Basics — name, unique slug, tenant, event date window.
2. Venue — address and map coordinates.
3. Windows — RSVP open/close and redemption open/close.
4. Notifications — rich-text email subject + body templates (alignment, font size/weight) with parameter-tag chips.
5. Landing — landing theme, logos, and assets (uploaded via the assets API).

RSVP & ticketing

An invitee opens the per-campaign landing page (/{slug}), enters their referral code, and a valid referral within the RSVP window mints a booking code + QR ticket.

The submit_rsvp RPC

POST /api/public/rsvp runs the submitRsvpEffect pipeline, which calls the submit_rsvp Postgres RPC. The RPC:

• validates campaign status and the RSVP window,
• locks the invitee row FOR UPDATE,
• creates the RSVP + ticket + activity log in one transaction.

Re-submitting the same referral returns the existing ticket instead of duplicating — safe against double-clicks and retries. See the full contract in Public API.

Ticket view

The minted ticket is viewable at /{slug}/ticket/{ticket_token}. The URL token is signed server-side; the human-readable booking code is shown inside the ticket and remains valid for officer scan/manual redemption.

Officer redemption

Officers open the mobile PWA at /officer/{slug}, log in with a 6-digit PIN, then scan a QR or type a booking code.

Flow

Offline mode

On login, the PWA syncs the campaign manifest (booking codes, guest names, quantities, and a redeemed snapshot) into IndexedDB. While offline, scans are checked against that manifest for a real VALID / INVALID verdict; codes already redeemed on the same device in the current offline session are flagged as duplicates immediately. Offline redeems are queued locally and re-validated against the server on reconnect, which remains the source of truth. A ticket redeemed on another device while this device is offline cannot be detected until the queue syncs.

Notifications

revento sends transactional messages on three events: invitation, RSVP response, and redeem-complete. Channels are resolved per tenant via notification_channel_options; every send is recorded in notification_logs with per-channel delivery status.

The per-tenant channel mode is one of email_only or email_whatsapp; per-channel delivery status is success, failed, or skipped.

Scheduled invitation sends are processed by the GitHub Actions workflow .github/workflows/scheduled-invitations.yml, which calls /api/admin/notifications/scheduled-invitations. Production must define CRON_SECRET, and the same value must be stored as the GitHub repository secret CRON_SECRET. Invitation emails for a drain batch are sent via Resend's batch endpoint (up to 100 emails per call); if a batch call fails outright, every job in that batch is retried with the existing backoff/dead-letter policy. One-off transactional emails (RSVP confirmation, redeem complete, magic links) still use the single-send endpoint.

Email template defaults

Default email bodies for all three transactional events are editable at Settings → Notification Templates. Templates are stored per-tenant in app_settings under the key campaign_notification_templates and pre-fill Step 4 of the campaign wizard when a new campaign is created. Each template supports a rich-text body editor with inline selection formatting, subject field, live preview, and parameter tag chips ({{invitee_name}}, {{campaign_name}}, etc.). Onboarding email templates (admin / officer magic-link flows) are managed separately at Settings → Onboarding Messages.

Campaign report

From the campaign dashboard, the AI Report CTA exports an official campaign report PDF via GET /api/admin/:slug/report.

How it works

• The route is admin-guarded and runs on the Node.js runtime (force-dynamic).
• Metrics are aggregated in campaign-report.ts from active invitees.
• An optional insight is fetched from ai-insight.ts (OpenAI-compatible, server-only).
• The document is rendered to a PDF buffer by components/reports/campaign-report-document.tsx using @react-pdf/renderer.
• The PDF excludes the activity timeline table so exported reports stay concise.

API Reference

Overview

revento exposes HTTP route handlers under /api for the public RSVP surface, the officer PWA, and a few admin operations. All dashboard CRUD goes through Server Actions, not these endpoints.

Authentication

Two independent cookie-based sessions, plus single-use magic-link tokens.

• Admin sessions are JWT (HS256, signed with AUTH_SECRET). src/proxy.ts verifies the cookie for every /admin/* request and admin API routes call requireAdminSession().
• Officer endpoints (except login/logout) require the revento-officer-session cookie; a missing cookie returns 401 session_invalid.
• Magic links back admin onboarding, admin password reset, and officer PIN reset; tokens are superseded on re-issue.

Public API

Unauthenticated endpoints used by the public RSVP landing page.

POST/api/public/rsvp

Submit a referral code to mint (or re-fetch) a ticket. Idempotent per referral.

Request body

{
  "campaignId": "f2c1e0a4-...",
  "referralCode": "DEMO01"
}

200 OK

{
  "bookingCode": "RV-7QK2-9F3D",
  "qrPayload": "rv:tkt:f2c1...:RV-7QK2-9F3D",
  "quantity": 2,
  "inviteeName": "Andi Wijaya",
  "alreadySubmitted": false
}

alreadySubmitted is true when the referral was already used and the existing ticket is returned.

Errors

GET/api/public/campaigns/:slug

Fetch the public campaign record for a landing page by slug.

200 OK

Returns the full Campaign object (see Data schemas → Campaign). Abridged example:

{
  "id": "f2c1e0a4-...",
  "tenantId": "9a0b-...",
  "name": "Indonesia Investment & Mining Expo 2026",
  "slug": "IIMX2026",
  "status": "active",
  "eventStartAt": "2026-05-23T02:00:00.000Z",
  "eventEndAt": "2026-05-23T10:00:00.000Z",
  "venueName": "JCC Senayan, Jakarta",
  "rsvpStartAt": "2026-05-01T00:00:00.000Z",
  "rsvpEndAt": "2026-05-22T17:00:00.000Z",
  "redemptionStartAt": "2026-05-23T01:00:00.000Z",
  "redemptionEndAt": "2026-05-23T11:00:00.000Z",
  "landingLogoUrl": "https://.../logos/...",
  "landingBannerUrls": ["https://.../banners/..."],
  "landingThemeKey": "corporate",
  "ticketQuantityPerRsvp": 2,
  "notificationMode": "email_whatsapp",
  "updatedAt": "2026-06-04T06:00:00.000Z"
}

Errors

Officer API

Mobile PWA endpoints. All except login / logout require the revento-officer-session cookie.

POST/api/officer/:slug/login

Authenticate an officer with a 6-digit PIN; sets the session cookie.

Request body

{ "pin": "123456" }

200 OK

Sets revento-officer-session (httpOnly, 8h) and returns:

{
  "campaign": { "id": "f2c1...", "name": "IIMX 2026", "slug": "IIMX2026" },
  "officer":  { "id": "0b7e...", "name": "Budi", "email": "budi@revento.id" },
  "expiresAt": "2026-05-23T10:00:00.000Z",
  "source": "db"
}

Errors

POST/api/officer/:slug/logout

Clear the officer session cookie. Always succeeds.

200 OK

{ "ok": true }

POST/api/officer/:slug/validate-code

Validate a booking code / QR before redeeming. Returns a discriminated result union without changing ticket state.

Request body

{ "bookingCode": "RV-7QK2-9F3D", "method": "qr" }

200 OK — result variants

// valid
{ "result": "valid", "source": "db", "ticketId": "...",
  "name": "A. Wijaya", "bookingCode": "RV-7QK2-9F3D", "quantity": 2 }

// duplicate (already redeemed)
{ "result": "duplicate", "source": "db", "ticketId": "...",
  "name": "A. Wijaya", "bookingCode": "RV-7QK2-9F3D",
  "redeemedAt": "2026-05-23T03:11:00.000Z", "prevOfficer": "Budi" }

// invalid (unknown code)
{ "result": "invalid", "source": "db",
  "bookingCode": "RV-0000-0000", "message": "Ticket not found" }

// blocked (paused/closed/out-of-window)
{ "result": "blocked", "source": "db", "bookingCode": "RV-7QK2-9F3D",
  "reason": "redemption_closed", "message": "Redemption window is closed" }

Errors

POST/api/officer/:slug/redeem

Redeem a ticket. Same request body and result union as validate-code; on success the ticket status becomes redeemed and the attempt is logged. Duplicate / invalid / blocked attempts are also recorded.

{ "bookingCode": "RV-7QK2-9F3D", "method": "manual" }

Errors are identical to validate-code.

GET/api/officer/:slug/history

Recent scan attempts for the signed-in officer's campaign, plus aggregate stats.

200 OK

{
  "entries": [
    {
      "id": "re_01...",
      "name": "A. Wijaya",
      "bookingCode": "RV-7QK2-9F3D",
      "time": "2026-05-23T03:11:00.000Z",
      "inputMethod": "qr",
      "officer": "Budi",
      "status": "success"
    }
  ],
  "stats": { "success": 12, "duplicate": 1, "invalid": 0, "blocked": 2 }
}

status is one of success, duplicate, invalid, blocked. Errors match the other authenticated officer endpoints.

GET/api/officer/:slug/manifest

The full list of valid booking codes for the signed-in officer's campaign, with a redeemed snapshot at sync time. The PWA caches this response in IndexedDB on login to support offline validation.

200 OK

{
  "entries": [
    { "bookingCode": "RV-7QK2-9F3D", "name": "A. Wijaya", "quantity": 2, "redeemed": false }
  ],
  "syncedAt": "2026-06-14T07:45:48.885Z"
}

Errors match the other authenticated officer endpoints.

Admin API

Admin-guarded endpoints. Require a valid revento-admin-session cookie (enforced by requireAdminSession()).

GET/api/admin/:slug/report

Render the official campaign report as a PDF (with optional AI insight). Runs on the Node.js runtime, never cached.

200 OK

Body is the binary PDF.

Errors

POST/api/admin/assets

Upload landing / campaign image assets to Supabase Storage (bucket campaign-assets) and get back public URLs.

Request — multipart/form-data

200 OK

{
  "urls": [
    "https://<project>.supabase.co/storage/v1/object/public/campaign-assets/logos/1717.....png"
  ]
}

Errors

Error codes

JSON endpoints fail with { "error": "<code>" } and an HTTP status. Consolidated reference:

In addition, redemption results carry a blocked reason in the 200 body (e.g. redemption_not_open, redemption_closed) rather than an HTTP error.

Data schemas

TypeScript domain shapes (camelCase) returned by the API. Source: src/lib/types/domain.ts.

Campaign

Ticket

Enumerations

Reference

Routing map

Any unauthenticated /admin/* request is redirected to /login?next=… by src/proxy.ts.

SEO & search policy

The canonical production origin is https://revento.online. Shared SEO helpers live in src/lib/seo.ts so canonical URLs, absolute image URLs, trimmed descriptions, and campaign RSVP share text stay consistent across metadata routes. The root favicon is served from the stable /favicon.ico metadata convention, with square brand icons for browser tabs, touch icons, and Google Search appearance.

Environment variables

Create .env.local with:

Scripts

E2E tests are organized by scenario (tests/scenarios/<domain>/<action>.spec.ts); the canonical runs use --workers=1 because fixtures are shared and self-cleaning around the IIMX2026 campaign.

Releases & versioning

revento follows Semantic Versioning (MAJOR.MINOR.PATCH). The version is bumped on every production deploy (dev → main merge), sized to the PR scope.

The number is single-sourced from package.json and surfaced in the UI via src/lib/constants/version.ts (APP_VERSION) — shown in the dashboard sidebar footer and the marketing footer. Full history lives in CHANGELOG.md.

Language per surface

revento keeps language tied to audience. Internal dashboard and documentation copy stay English. Invitee/officer-facing surfaces (Public RSVP and Officer PWA) stay Bahasa Indonesia, as do campaign notification templates. Shared copy maps live under src/lib/i18n/ to keep this convention visible and testable.

Documentation versioning

This documentation carries its own version — currently v1.6.2 — independent of the app APP_VERSION. It is single-sourced from src/app/documentation/version.ts (DOCS_VERSION) and shown in the docs topbar and footer. Bump it on meaningful content or structure changes, not on every app deploy.

Documentation changelog

• v1.6.2 — documented the stable root favicon convention and the Search Console follow-up for sitemap submission and homepage indexing after SEO/search-appearance fixes.
• v1.6.1 — synced the marketing-site documentation with the current implementation: the landing page still uses lenis for smooth scroll, but most reveals and ambient motion now run through CSS plus lightweight viewport observers instead of landing-page motion wrappers.
• v1.6.0 — documented Officer PWA offline validation: the manifest sync on login, offline VALID / INVALID / duplicate verdicts, and the new GET /api/officer/:slug/manifest endpoint.
• v1.5.1 — noted that NEXT_PUBLIC_SENTRY_DSN also enables Sentry Session Replay, captured only on errors (replaysSessionSampleRate: 0, replaysOnErrorSampleRate: 1.0) to stay within the free-tier quota.
• v1.5.0 — documented SENTRY_DSN and NEXT_PUBLIC_SENTRY_DSN for server- and client-side error monitoring (Sentry, Playbook 1).
• v1.4.0 — documented NEXT_PUBLIC_POSTHOG_KEY and NEXT_PUBLIC_POSTHOG_HOST for the admin-dashboard product analytics integration (PostHog, Playbook PA-1).
• v1.3.5 — added environment variable reference rows for the delivery-status webhook endpoints (RESEND_WEBHOOK_SECRET, WHATSAPP_WEBHOOK_VERIFY_TOKEN,WHATSAPP_APP_SECRET): /api/webhooks/resend and /api/webhooks/whatsapp reconcile final delivery status on notification_logs.
• v1.3.4 — documented Resend batch-endpoint sending for scheduled invitation emails (up to 100/call) and the whole-batch retry/dead-letter behavior.
• v1.3.3 — updated WhatsApp notification docs from WAHA to the Meta WhatsApp Cloud API, updated the scheduled-invitations delivery docs to the GitHub Actions workflow, and refreshed the environment variable reference (WHATSAPP_ACCESS_TOKEN, WHATSAPP_PHONE_NUMBER_ID,WHATSAPP_API_VERSION, WHATSAPP_GRAPH_BASE_URL).
• v1.3.2 — added environment variable reference rows for scheduled notifications and providers (CRON_SECRET, RESEND_API_KEY,RESEND_FROM_EMAIL, WhatsApp, Telegram, and AI insight keys).
• v1.3.1 — clarified campaign report PDF generation: metrics are aggregated from active invitees, and the activity timeline table is excluded from the exported PDF.
• v1.3.0 — added the public ticket-view endpoint and path-parameter documentation to the API reference.
• v1.2.0— added the "Email template defaults" sub-section under Notifications.
• v1.1.0 — added SEO and search-policy documentation, including crawler routes, public sitemap scope, and RSVP noindex behavior.
• v1.0.0 — initial documentation: getting started, concepts, guides, full API reference (auth, public / officer / admin endpoints with request/response contracts, error codes, data schemas), and reference.