Backend Runtime

The backend runtime lives in apps/api and uses Hono on Node.js 20.

Startup Sequence

apps/api/src/index.ts performs startup in this order:

1. Import ./lib/env.js to validate environment variables at process start.
2. Initialize Sentry via initSentry({ dsn, environment }).
3. Build app via createApp().
4. Start HTTP server with @hono/node-server on env.PORT.

If env validation fails, startup exits immediately.

Middleware Chain

Defined in apps/api/src/app.ts.

Order is important and currently:

1. secureHeaders()
2. cors({...})
3. correlationMiddleware
4. dbMiddleware
5. request logger
6. route-level middleware (auth, rbac, tenant, profile-specific)
7. global error handlers (onError, onNotFound)

CORS and Allowed Headers

CORS is configured from CORS_ALLOWED_ORIGINS and explicitly allows:

• Authorization
• Content-Type
• Idempotency-Key
• X-Correlation-Id

Credentials are allowed (credentials: true).

Route Topology

All routes are mounted under createApp().

Service and Health

• GET / returns { service, links }
• GET /health returns { status: "ok", version, env }

Versioned API groups

• /api/v1/auth -> authRouter
• /api/v1/consumer -> consumerRouter
• /api/v1/pos -> posRouter (POS operator code verification)
• /api/v1/client -> clientRouter
• /api/v1/client also mounts campaignsRouter
• /api/v1/marketing -> marketingRouter
• /api/v1/admin -> adminRouter
• /api/v1/webhooks -> webhooksRouter
• /api/v1/oauth -> posOAuthRouter
• /api/v1/internal/cron -> cronRouter

Complete Endpoint Reference

Auth (/api/v1/auth)

Method	Path	Auth	Description
GET	/me	authProfileMiddleware	Profile state for authenticated user

Consumer (/api/v1/consumer)

Method	Path	Permission	Description
GET	/wallets	WALLET_VIEW_OWN	List all wallets for user
GET	/wallets/:walletId	WALLET_VIEW_OWN	Single wallet detail
GET	/wallets/:walletId/history	WALLET_HISTORY_OWN	Ledger entries (limit capped at 100)
POST	/wallets/:walletId/redeem/preview	WALLET_REDEEM	Redemption preview calculation
POST	/wallets/:walletId/redeem/confirm	WALLET_REDEEM	Execute redemption with row lock
GET	/offers	WALLET_VIEW_OWN	Offers for the consumer's merchants
GET	/offers/:campaignId	WALLET_VIEW_OWN	One offer the consumer can open
GET	/profile	WALLET_VIEW_OWN	Consumer date of birth
PATCH	/profile	WALLET_VIEW_OWN	Set consumer date of birth

Client (/api/v1/client)

Method	Path	Permission	Description
POST	/bootstrap-merchant-workspace	TENANT_PROFILE_UPDATE	Idempotent workspace creation
GET	/tenants/:tenantId	TENANT_VIEW	Dashboard overview with stats
PATCH	/tenants/:tenantId/onboarding	TENANT_PROFILE_UPDATE	Update onboarding profile
GET	/tenants/:tenantId/pos-connections	TENANT_VIEW	List POS connections
POST	/tenants/:tenantId/pos-connections/square/connect	TENANT_POS_CONNECT	Initiate Square OAuth
POST	/tenants/:tenantId/pos-connections/clover/connect	TENANT_POS_CONNECT	Initiate Clover OAuth
DELETE	/tenants/:tenantId/pos-connections/:connectionId	TENANT_POS_CONNECT	Disconnect POS (soft delete)
GET	/tenants/:tenantId/reward-rules	TENANT_VIEW	List all reward rule versions
POST	/tenants/:tenantId/reward-rules	TENANT_REWARD_CONFIG	Create new reward rule version
GET	/tenants/:tenantId/transactions	TENANT_ANALYTICS_VIEW	Transaction feed (limit capped at 100)
GET	/tenants/:tenantId/metrics/daily	TENANT_ANALYTICS_VIEW	Daily series for transactions and points
GET	/tenants/:tenantId/analytics	TENANT_ANALYTICS_VIEW	Merchant analytics for the path tenant. Query days is an integer from 7 to 90 and defaults to 30. Returns earn vs redeem, top consumers, redemption conversion, new vs returning, and revenue impact from stored ledger-linked purchase amounts minus used redemption discounts
GET	/tenants/:tenantId/consumers	TENANT_CONSUMER_VIEW	Wallet holders list
POST	/tenants/:tenantId/branding/logo	TENANT_PROFILE_UPDATE	Upload tenant logo (base64, max ~10 MB)
DELETE	/tenants/:tenantId/branding/logo	TENANT_PROFILE_UPDATE	Remove tenant logo
PATCH	/tenants/:tenantId/branding	TENANT_PROFILE_UPDATE	Set white-label programName, primaryColor, and accentColor. Colors are hex. null clears a field
GET	/tenants/:tenantId/promotions	TENANT_REWARD_CONFIG	List earn multipliers and bonus configs
POST	/tenants/:tenantId/promotions/multipliers	TENANT_REWARD_CONFIG	Create an earn multiplier window
DELETE	/tenants/:tenantId/promotions/multipliers/:multiplierId	TENANT_REWARD_CONFIG	Remove an earn multiplier window
PUT	/tenants/:tenantId/promotions/bonuses	TENANT_REWARD_CONFIG	Save first-purchase, milestone, and birthday bonus configs
POST	/tenants/:tenantId/promotions/flyer	TENANT_REWARD_CONFIG	Download a PDF flyer. Body is { "offer": "..." }. The PDF heading is the tenant business name
GET	/tenants/:tenantId/store-operators	TENANT_TEAM_INVITE	List operators + pending invites
POST	/tenants/:tenantId/store-operator-invites	TENANT_TEAM_INVITE	Invite operator by email
DELETE	/tenants/:tenantId/store-operator-invites/:inviteId	TENANT_TEAM_INVITE	Revoke pending invite
DELETE	/tenants/:tenantId/store-operators/:userId	TENANT_TEAM_INVITE	Remove active operator
GET	/debug/square	TENANT_VIEW	Square config diagnostics (no secrets)
GET	/tenants/:tenantId/campaigns	TENANT_CAMPAIGN_VIEW	List campaigns
POST	/tenants/:tenantId/campaigns	TENANT_CAMPAIGN_MANAGE	Create campaign
GET	/tenants/:tenantId/campaigns/:campaignId	TENANT_CAMPAIGN_VIEW	Load campaign + sanitized HTML
PATCH	/tenants/:tenantId/campaigns/:campaignId	TENANT_CAMPAIGN_MANAGE	Edit draft campaign
POST	/tenants/:tenantId/campaigns/:campaignId/preview	TENANT_CAMPAIGN_MANAGE	Render a campaign preview
POST	/tenants/:tenantId/campaigns/:campaignId/schedule	TENANT_CAMPAIGN_MANAGE	Materialize recipients and schedule send
POST	/tenants/:tenantId/campaigns/:campaignId/cancel	TENANT_CAMPAIGN_MANAGE	Cancel a draft or scheduled campaign
GET	/tenants/:tenantId/campaigns/:campaignId/stats	TENANT_CAMPAIGN_VIEW	Campaign recipient stats
POST	/tenants/:tenantId/campaigns/media	TENANT_CAMPAIGN_MANAGE	Upload campaign media asset

Admin (/api/v1/admin)

Method	Path	Permission	Description
GET	/tenants	ADMIN_TENANTS_VIEW_ALL	List all tenants (limit 200)
GET	/tenants/:tenantId	ADMIN_TENANTS_VIEW_ALL	Tenant detail with members and POS
POST	/wallets/:walletId/freeze	ADMIN_WALLET_FREEZE	Freeze wallet + audit log
POST	/wallets/:walletId/unfreeze	ADMIN_WALLET_FREEZE	Unfreeze wallet + audit log
POST	/wallets/:walletId/adjust	ADMIN_WALLET_ADJUST	Manual points adjustment + audit log
GET	/audit-logs	ADMIN_AUDIT_LOGS_VIEW	Immutable audit trail (limit 200)
GET	/users/search	ADMIN_USER_SEARCH	Search users or list pending approvals
PATCH	/users/:userId/approve	ADMIN_USER_MANAGE	Approve user + auto-provision workspace
PATCH	/users/:userId/role	ADMIN_USER_MANAGE	Change user role + audit log

POS Operator (/api/v1/pos)

Method	Path	Permission	Description
GET	/context	REDEMPTION_VERIFY	Resolve single-tenant context for operator
POST	/redemptions/lookup	REDEMPTION_VERIFY	Look up redemption code without burning
POST	/redemptions/complete	REDEMPTION_VERIFY	Burn redemption code (SELECT FOR UPDATE)

Webhooks (/api/v1/webhooks) — No JWT auth

Method	Path	Auth	Description
POST	/square	HMAC signature	Square webhook receiver (fast-ack)
POST	/clover	HMAC signature	Clover webhook receiver (fast-ack, handles verification handshake)

OAuth Callbacks (/api/v1/oauth) — No JWT auth

Method	Path	Description
GET	/square/callback	Square OAuth code exchange + redirect
GET	/clover/callback	Clover OAuth code exchange + redirect

Internal (/api/v1/internal/cron)

Method	Path	Auth	Description
POST	/square-poll-payments	X-Cron-Secret header	Poll Square ListPayments for all merchants
POST	/clover-poll-payments	X-Cron-Secret header	Poll Clover payments for all merchants
POST	/process-pending-webhooks	X-Cron-Secret header	Retry sweeper for unprocessed raw webhook events
POST	/process-campaigns	X-Cron-Secret header	Send queued campaign recipients

Request Context Contract

Context variables are attached by middleware and consumed by handlers:

• db (Drizzle client) from dbMiddleware
• correlationId from correlationMiddleware
• auth from strict authMiddleware
• authProfile from authProfileMiddleware
• tenantContext from tenantMiddleware

Error Handling Model

apps/api/src/middleware/error-handler.ts centralizes response shaping.

Known error classes handled explicitly

• AppError
• AuthError
• RbacError
• TenantError
• HTTPException
• ZodError

Standard response shape

{
  "code": "...",
  "message": "...",
  "requestId": "req_..."
}

For validation failures, issues is also returned.

Unhandled exceptions are logged and returned as INTERNAL_ERROR (500) without stack leakage.

Execution Characteristics

• DB client is singleton-per-process (dbMiddleware references a shared instance).
• Webhooks use fast-ack behavior with asynchronous post-response processing (setImmediate).
• Consumer redemption confirmation uses SQL row locking (FOR UPDATE) to avoid concurrent over-redemption.
• Ingestion dedup uses DB constraints and idempotency_keys entries.
• Email notifications are fire-and-forget and never block the main flow.
• OAuth state is HMAC-signed and time-limited.

Design Intent

The backend favors explicit boundaries:

• transport concerns in route handlers,
• domain decisions in services/packages,
• cross-cutting concerns in middleware,
• invariants in schema constraints and DB transactions.