Status: ✅ Production — May 2026

Every route in PoliLex is a Partial Prerender (◐): the static shell (nav, layout, skeleton UI) is pre-generated at build time and served from CDN with instant TTFB. Dynamic content — auth state, user data, subscription status — streams in behind <Suspense> boundaries. The entire application uses the Next.js 16 'use cache' directive with cacheLife() profiles rather than route-segment config — cache policy lives next to the data, not scattered across page files.

All caching concerns live in a single, purpose-built module. Nothing cache-related is scattered across src/lib/utils/, src/lib/constants/, or individual action files:

next.config.mjs imports STABLE_DATA_CACHE_LIFE directly from src/lib/cache/cache-ttl.ts via jiti. The cacheLife config entry and every cacheLife() call inside 'use cache' functions reference the same object — values cannot drift between build config and runtime:

// Single source of truth — next.config.mjs reads the same object 'use cache' functions use
const { STABLE_DATA_CACHE_LIFE } = jiti(
  resolve(__dirname, './src/lib/cache/cache-ttl.ts'),
);
const nextConfig = {
  cacheComponents: true,
  cacheLife: { 'stable-data': STABLE_DATA_CACHE_LIFE }, // stale 1h / revalidate 7d / expire 30d
};

dynamicLoader() is a composable primitive that encapsulates the two framework requirements every loader must satisfy: React.cache() for per-request memoisation, and connection() to register dynamic context before any I/O so Next.js doesn't attempt to statically prerender the route. Without connection(), native TCP Prisma queries are invisible to the framework's static-analysis pass and the build throws a crypto.randomUUID() error at compile time.

Wrapping these two concerns into a single utility means the pattern is structurally impossible to get wrong — you cannot forget connection(), call it in the wrong order, or accidentally duplicate cache() boilerplate. It works identically for zero-argument and parameterised loaders:

// Zero-argument loader
export const loadAdjectivesData = dynamicLoader(async () =>
  safeFetch(getAdjectiveCollectionData, fallback, 'Error:'),
);

// Parameterised loader — types flow through automatically
export const loadAspectPairs = dynamicLoader(
  async (limit: number): Promise<AspectPairsResult> =>
    safeFetch(() => getCachedAspectPairs({ limit }), fallback, 'Error:'),
);

Server actions and mutations should call invalidate.*() helpers from src/lib/cache/invalidate.ts rather than raw tag strings. The module owns CACHE_TAGS (vocabulary, reflexive lab, exam content, blog/tenant, OpenAI costs) and wraps revalidateTag() internally:

// Tag strings defined once — callers never write raw strings
invalidate.adjectives();
invalidate.blog.post(companyId, postId); // touches POST_DETAIL + POSTS_LIST + ANALYTICS atomically
invalidate.openaiCosts(model); // optional fine-grained model tag + the aggregate tag
invalidate.exam.exercise(examId, taskType); // surgical exam cache bust

The advantage over ad-hoc revalidateTag() is threefold: tag strings cannot be misspelled (TypeScript errors at the call site), related tags are always invalidated together (e.g. a blog post change also clears the post list and analytics), and the full set of tags in the system is discoverable in one place rather than grep-scattered across action files.

auth() (reads cookies/headers) must never be called inside a 'use cache' function. Both clients are defined in src/server-actions/prisma.ts and exported as prisma (default) and cachedPrisma:

The prisma client's claimsFn wraps auth() in try/catch and silently returns empty claims during PPR prerendering (when no request context exists), preventing build failures. cachedPrisma must never call auth() — ESLint rule local/no-cached-prisma-outside-use-cache flags accidental misuse at write time.

Custom rules in eslint.config.mjs catch cache, logging, and App Router boundary mistakes at write time:

Cache & Suspense

• local/no-cached-prisma-outside-use-cache — warns when cachedPrisma is used outside a 'use cache' function (set to warn because call-stack tracing is incomplete).
• local/require-suspense-for-suspending-route-components — client components using useSearchParams() or use(promise) must sit below <Suspense> (or the route opts in via connection()).
• local/no-suspense-fallback-with-route-loading — prevents duplicating the same loading UX with both segment loading.tsx and page-level Suspense.

Server / client boundaries (see ACTIONS-STRUCTURE.md)

• local/no-use-client-in-server-layers, local/no-use-server-in-forbidden-locations, local/no-prisma-in-client-boundary, local/no-client-import-server-action-impl, local/no-barrel-server-actions-import, and related rules enforce the RPC entrypoint pattern under src/server-actions/.

Logging

• no-restricted-syntax on console.error — warns in src/server-actions/**/*.ts and src/app/api/**/*.ts, pointing developers to logUserError() instead.

// Good — always produces useful output in production
logUserError('Update failed:', error);

src/server-actions/podcast/ is fully on this pattern (including best-effort wordplay analysis logging at publish).

During static prerendering there is no request context, so Clerk's auth() rejects with an internal HangingPromiseRejectionError. The solution is a typed AuthRequiredError class defined in a client-safe module (src/lib/errors/auth-errors.ts) with no server-only imports — essential because auth error detection runs in both server and client contexts:

// Brand property survives minification — class names mangle to 'i' or 'c' in production
export class AuthRequiredError extends Error {
  readonly isAuthRequiredError = true;
}

All auth-gate helpers (requireAuth, requireAdmin, requireSubscription) catch HangingPromiseRejectionError and re-throw AuthRequiredError. A shared safeFetch utility in every page loader suppresses auth errors with cause-chain walking — if an action re-wraps new Error('...', { cause: authErr }), safeFetch recurses through .cause and still silently discards it:

function isAuthRequired(error: unknown): boolean {
  if (error instanceof AuthRequiredError) return true;
  if (
    error instanceof Error &&
    (error as AuthRequiredError).isAuthRequiredError
  )
    return true;
  if (error instanceof Error && error.cause) return isAuthRequired(error.cause); // recursive
  return false;
}

logUserError replaces bare console.error in all action catch blocks. It falls back to error.stack frame extraction when error.message is empty — production minifiers mangle constructor names to single letters, making error.constructor.name useless as a log value.

Next.js tracks dynamic context through fetch(), cookies(), headers(), and connection(). Native TCP Prisma queries are not tracked. Pages whose first I/O is cachedPrisma (no preceding auth()) must call await connection() explicitly to register dynamic context — otherwise crypto.randomUUID() inside the Prisma PG adapter throws at build time:

Route "/video" used crypto.randomUUID() before accessing either uncached data or Request data.

connection() lives in the loader function, not the page component, keeping framework internals out of the UI layer.

Most feature routes use <Suspense fallback={<FeatureSkeleton />}> around async server work or use(promise) (see docs/cache-components/CACHE_COMPONENTS.md Pattern 8). There is no root segment loading.tsx under src/app/. Segment loading.tsx files exist for onboarding, RLS testing, and company portal subtrees (e.g. src/app/[lang]/(landing)/onboarding/loading.tsx, src/app/[lang]/(home)/test-rls/loading.tsx, src/app/[lang]/companies/[slug]/loading.tsx and blog/videos/pdf variants); do not duplicate the same loading UX with both segment loading.tsx and page-level Suspense for the same subtree.

Clerk’s async ClerkProvider in src/app/[lang]/layout.tsx uses AppShellSkeletonWithPage ( NavbarSkeleton + SuspenseFallbackChrome ) as the Suspense fallback while getKeylessStatus runs.

Skeleton standards: extract skeletons to src/components/<feature>/*Skeleton*.tsx; match layout tokens and dark: variants; prefer shared chrome helpers from @/lib/skeleton-chrome where applicable.

Primary validation (lint, type-check, Jest, next build) runs locally and on Vercel — not in GitHub Actions (see workflow comment in .github/workflows/pr-checks.yml). The build step is the only place missing connection() calls and 'use cache' violations surface; these errors only occur during next build, not next dev.

GitHub Actions supplements with focused jobs:

Local equivalents: npm run test:gold-audit:diff (PR diff), npm run test:gold-audit (full audit), npm run test:polar-webhooks.

docs/cache-components/CACHE_COMPONENTS.md — Cache Components, Suspense, loaders, patterns.
docs/cache-components/CACHE_STRATEGY.md — cache tags, invalidation.
docs/next-intl/NEXT_INTL.md — next-intl (routing, bundles, src/proxy.ts).
docs/bundle-size/BUNDLE_SIZE.md — analyzer workflow, baselines, lazy-load targets.

Three-layer combobox stack:

Engineering details: large verb lists use A–Z browse batches + scroll load; clear control is keyboard- and screen-reader-accessible; conjugation wizard resets fetched verb state when the user picks a different lemma (prevents stale inject). Internal specs: docs/AUDIT-MD/SELECT_AUDIT.md.

Heavy npm packages and feature shells load only when the user navigates to them or opens the UI. Baseline workflow: npm run bundle:baseline → node scripts/compare-bundle-baseline.mjs (manual; compares checked-in snapshots under baseline/).

Full inventory and analyzer workflow: docs/bundle-size/BUNDLE_SIZE.md. Combined static JS stayed ~flat while CSS dropped ~349 KiB after splitting heavy CSS out of the eager graph (May 2026 baseline).

Stack: next-intl v4 · ICU MessageFormat in JSON · en (default) and pl only — no other product locales

PoliLex treats internationalization as a first-class platform concern: routing, middleware, layout boundaries, and client bundles are aligned so senior reviewers can reason about locale, payload size, and React 19 / Next.js 16 constraints in one place.

Next.js 16: proxy lives at src/proxy.ts (Node runtime by default for this file — no segment runtime export in the proxy module.)

cacheComponents: uncached async work from ClerkProvider must sit inside <Suspense>. params are not hidden behind that fallback: the layout awaits params first so locale + intl mount without flashing the full AppShellSkeletonWithPage for segment resolution alone (see docs/next-intl/NEXT_INTL.md §6).

Plugin wiring: createNextIntlPlugin('./src/intl/request.ts') in next.config.mjs; next-intl listed in optimizePackageImports.

End-to-end file map, code pointers, SEO, and edge-case notes: docs/next-intl/NEXT_INTL.md

System Status: ✅ v2.5 — Production Ready (April 2026; v2.4 live validation March 2026)

Polar is the payment and subscription stack for international tax compliance and simplified global operations. It acts as Merchant of Record, handling VAT, GST, and sales tax obligations across 100+ countries—reducing operational burden versus acting as the merchant of record yourself.

Business Value:

• ✅ Automatic Tax Compliance — Polar calculates, collects, and remits taxes globally
• ✅ Merchant of Record — Polar assumes tax liability as the legal seller
• ✅ Zero Tax Registration — Sell worldwide without jurisdiction-specific registrations
• ✅ Simplified Operations — Single integration, worldwide coverage, reduced overhead

Principle: Polar is the source of truth for subscription and order state (what the customer is entitled to, what was charged, and what Polar’s API returns). Nothing in the app “overrules” Polar for billing reality: Postgres holds materialized state and app-derived fields (e.g. token balances from your rules applied to Polar events); Clerk is a cache for fast auth and Edge gating. If Postgres or Clerk lag Polar, reconciliation and live reads converge back to Polar — see crons and getSubscriptionStatus / resolvePolarSubscriptionForAccount.

Mental model: one authority (Polar), two projections (DB = durable + tokens, Clerk = session cache), with explicit sync and repair paths.

1. Polar sends a webhook → validateEvent (@polar-sh/sdk/webhooks) on src/app/api/webhook/polar/route.ts.
2. Claim → claimWebhookEvent (src/lib/polar/webhook-idempotency.ts) — unique row per provider + eventType + eventId (P2002 = duplicate delivery, skip).
3. Apply → e.g. transitionSubscription, handleTopup, applyCustomerStateChanged, handleOrderRefunded — Prisma updated (balances, rows).
4. Mark → markWebhookEventProcessed with a resultSnapshot.
5. Best-effort Clerk → syncClerk so middleware/UI see fresh metadata after the DB commit (failures logged; do not roll back money).

• getSubscriptionStatus() (src/server-actions/subscriptions/):
  • Always reads tokens and stable user keys from Prisma.
  • Merges live Polar via resolvePolarSubscriptionForAccount so subscription identity matches Polar when the API is available (overrides a stale local mirror). If Polar is unreachable, response falls back to last-known DB state (logged) — a degraded read, not a second authority.
  • Edge case in code: if Polar’s API shows no sub yet the DB has a still-valid polarCurrentPeriodEnd (e.g. migration/restored user), access may be granted from DB until Polar and reconciliation align — treat as bridging, not a competing SoT.
  • Background syncClerkMetadataInBackground — repairs Clerk from computed state without blocking the response (comments: Clerk is a cache; webhooks are primary).
• Sign-in / mobile: syncClerkPublicMetadataFromDatabase — re-hydrates Clerk from Prisma + Polar (see file header: “Polar query failure is non-fatal — falls back to existing DB data”). Used e.g. by POST /api/me/sync-public-metadata (Bearer JWT) for clients with empty metadata.
• Route protection: src/proxy.ts — subscription gating calls evaluateSubscriptionGate in src/lib/polar/derive-subscription-status.ts (same rules as the former inline block; Clerk publicMetadata only, Edge-safe).

Daily crons and retryWebhookEvent (see Automated Maintenance System) re-align DB and Clerk to Polar when webhooks are missed or processes crash after claim; see src/lib/polar/cron/webhook-retry.ts and related routes.

flowchart LR
  subgraph polar [Polar MoR]
    WH[Webhooks] --- API[Subscriptions API]
  end
  WH -->|HMAC + claim| DB[(Postgres / Prisma)]
  DB -->|apply + mark| DB
  DB -->|best effort| Clerk[(Clerk publicMetadata)]
  API -->|live read| GS[getSubscriptionStatus]
  DB --> GS
  GS -->|background repair| Clerk
  GS --> UI[Credits / clients]
  Clerk --> MW[proxy / middleware gating]

Design Principles:

• Polar as source of truth — Subscription and order reality comes only from Polar (webhooks + API). Postgres and Clerk are projections; drift is corrected toward Polar (live reads, reconciliation, crons).
• Financial Software Standards — Zero tolerance for bugs where money is involved; npm run test:polar-webhooks covers 652 Jest tests across __tests__/lib/polar, __tests__/hooks/webhooks/polar, __tests__/api/webhook, and __tests__/modules/webhooks — plus dedicated state-machine matrices
• Database-Backed Idempotency — Claim→apply→mark via claimWebhookEvent + markWebhookEventProcessed in src/lib/polar/webhook-idempotency.ts (insert claim, P2002 = duplicate); stable eventIds prevent double-processing
• Fail-Closed for Money — Balance mutations fail-closed; metadata sync fail-open for optimal reliability
• Event-Driven Processing — Asynchronous webhook handlers with state machine validation and transaction atomicity
• Live Validated — 100% congruency verified across Polar ↔ Backend ↔ Clerk ↔ Frontend through comprehensive E2E testing
• Custom UI Control — In-app subscription management (v2.2) for 95% of operations, Polar portal for payment-sensitive 5%

Architecture:

• Subscription Tokens (tokenBalance) — Tier allocation from getCreditsForProductId / CREDIT_ALLOCATIONS in src/lib/polar/utils.ts (e.g. 1,000 Pro, 2,500 Premium; free tier FREE_TIER_CREDITS = 100)
• Top-up Tokens (topupTokenBalance) — Purchased tokens, persist indefinitely
• Spending Priority — Subscription tokens consumed first (monthly reset), then top-up tokens (never expire)
• Balance Preservation — Subscription changes preserve purchased tokens via pure calculation: newBalance = newCredits + max(0, currentTotal - oldCredits)

Example: User with 1,500 tokens (1,000 subscription + 500 purchased) upgrades to 2,500-credit plan → Final balance: 3,000 tokens (2,500 new subscription + 500 preserved top-up)

Three-Layer Defense-in-Depth:

1. Edge Protection (Zuplo API Gateway — optional external layer)

   • Documented in docs/polar/STRIDE_THREAT_MODEL.md for webhook IP allowlisting and rate limits
   • In-repo Polar webhook security = HMAC signature verification via @polar-sh/sdk/webhooks only
   • Zuplo is used elsewhere for translate/scrape gateway paths (NEXT_PUBLIC_GATEWAY_URL) — not wired into src/app/api/webhook/polar/

2. Application Layer

   • Multi-layer validation (Zod UUID → Business logic allowlist → Runtime auth)
   • HMAC signature verification via Polar SDK on all webhook payloads
   • Database-backed idempotency — claimWebhookEvent + markWebhookEventProcessed with stable keys (duplicate insert P2002 → skip)
   • Prisma Serializable isolation on race-sensitive user mutations (e.g. src/server-actions/user/mutations.ts) — not inside polar webhook handlers themselves
   • Zero-trust metadata (token amounts derived from productId only, not client data)

3. Data Layer

   • Clerk authentication required for all server actions
   • Row-level security policies on Supabase
   • Transaction audit trail with polarId tracking
   • Error sanitization (no internal details exposed to users)

Event matrix (subscription + customer.state_changed use claim→mark on the route; top-up order.paid / order.refunded claim inside handleTopup / handleOrderRefunded for top-up products only):

v2.2 Refinements (Jan 28, 2026):

• subscription.created Support — Polar sends this event first; state machine now handles it correctly
• Clear freeTrialEndDate — Explicitly nulled when upgrading from free to paid plans
• Duplicate Transaction Prevention — Pre-existence check eliminates constraint errors
• Custom UI Implementation — Migrated from Polar portal to in-app subscription management for greater control

v2.3 Automation & UX (Jan 28, 2026):

• Payment Failure Handling — Complete UX flow for failed payments:
  • PaymentFailureAlert.tsx on credits page when subscription.past_due webhook received
  • Shows period end date and redirects to Polar portal for secure payment update
  • FixPaymentAction.tsx in AccountManagementCard prioritizes payment failure CTA above other actions
  • PaymentFailedBanner in locale layout surfaces payment issues app-wide
• Reconciliation Cron — Automated DB-Clerk desync detection and healing (daily at 3 AM UTC; Hobby-compatible)
• Cleanup Cron — Automated webhook event pruning (daily at 2 AM UTC, 30-day retention)
• Cron Security — Bearer token authorization, IP logging, fail-open error handling
• Operational Observability — Comprehensive logging of execution metrics, desync rates, cleanup counts

v2.4 Webhook Refactor & Idempotency (March 2026):

• Modular Webhook Handlers — Logic in src/hooks/webhooks/polar/ (state-machine, subscription-transition, customer-state-changed, topup, order-refund, sync-clerk, retry)
• Idempotency Hardening — Explicit claimWebhookEvent + markWebhookEventProcessed flow; deprecated checkAndMarkWebhookEventProcessed
• Direct Integration Tests — 13 tests for claim→mark flow, replay prevention, fail-closed behavior

v2.5 Customer, period & order hardening (April 2026):

• customer.state_changed — First-class handler (applyCustomerStateChanged) for Polar's customer-level snapshot: reconciles active_subscriptions with the database, with guards when the list is empty but the paid period is still valid, then state-machine + Clerk sync where appropriate; stable idempotency keys per customer + subscription shape.
• Period end — period.ended and subscription.period_ended wired through the same transitionSubscription + claim→mark path as other subscription events (explicit payload mapping for subscription_id / period fields).
• Order de-duplication — order.paid / paid order.updated skips subscription_create when the subscription stream already owns allocation, reducing double-processing noise.
• Operations visibility — Rich structured logging on the webhook route (logPolar); optional file-sink tracing via webhook-file-logger (claim, customer state, orders, result/end markers) to support E2E and production debugging; CLI helpers logs:view, logs:clear, logs:tail in package.json.
• Surface area — src/hooks/webhooks/polar/index.ts exports applyCustomerStateChanged alongside existing transition, topup, refund, and retry modules.

Runtime (single source of truth in code):

• Pure state core — src/hooks/webhooks/polar/state-machine.ts: reduceSubscriptionState (5 states × SUBSCRIPTION_EVENTS including period.ended), reducePlanChange, deriveStateFromDb — no database or network calls.
• Typed constants — src/hooks/webhooks/polar/polar-types.ts exposes SubscriptionState / SubscriptionEvent and runtime arrays SUBSCRIPTION_STATES + SUBSCRIPTION_EVENTS (and SUBSCRIPTION_STATE / SUBSCRIPTION_EVENT maps) so tests can iterate every state and event in lockstep with the reducer.
• Orchestration — src/hooks/webhooks/polar/subscription-transition.ts loads the user, computes currentState → nextState via the reducer, then executes per-nextState branches (ACTIVE, PAST_DUE, CANCELED_PENDING with period-edge logic, FREE, REVOKED) including Clerk sync and optional transaction rows.
• Token math isolated — src/hooks/webhooks/polar/subscription-token-balance.ts: computeActiveTransitionTokenBalance and computeRevokedTransitionTokenBalance mirror the ACTIVE/REVOKED paths (incl. polarSubscriptionIdChanged for new checkout rows, likelyStaleUpgrade to avoid clobbering an already-credited balance, lateral/NONE).
• Idempotency helpers — subscriptionEventId and subscriptionPayloadSnapshot live next to transitionSubscription and encode period.ended as period_ended:{subId} (and modifiedAt / period end where needed).

How tests are layered (no parallel “fake” state machine in production tests):

Takeaway: transitions are provable at the pure layer (exhaustive matrix), verified on the real async function, cross-checked against customer-level events, and aligned across proxy / credits server / Clerk metadata via src/lib/polar/derive-subscription-status.ts + consistency tests.

Strategic Decision (Jan 28, 2026): Migrated from Polar's hosted customer portal to custom React components for subscription management, achieving greater control over user experience and business logic.

Why Custom UI?

Initially, the system relied on Polar's customer portal for all subscription operations (cancel, upgrade, downgrade). While functional, this approach had limitations:

• Context Switching — Users redirected to external portal, breaking in-app flow
• Limited Control — Couldn't customize confirmation dialogs or messaging
• Branding Disconnect — External portal didn't match application's design language
• No Analytics — Couldn't track user interactions with subscription UI
• Inflexible UX — Portal workflow not optimized for our use cases

Custom Implementation:

Built 4 subscription UI entry points (primary Jest files: 117 tests total) handling common operations in-app:

Benefits Achieved:

• Seamless Experience — All subscription actions in-app, no context switching
• Full Control — Custom confirmation dialogs with clear, contextual messaging
• Consistent Branding — Matches application design system and internationalization (Polish/English)
• Enhanced UX — Real-time feedback with granular loading states per action
• Business Logic — Payment processing locks prevent concurrent operations
• Analytics Ready — Track every user interaction with subscription UI

Hybrid Approach:

Smart delegation between custom UI and Polar portal:

Technical Architecture:

User clicks "Upgrade to Premium"
         ↓
Custom UI shows confirmation dialog
         ↓
User confirms → Server action (changePlan)
         ↓
Redirect to Polar checkout (payment collection)
         ↓
User completes payment → Polar webhook
         ↓
Database + Clerk metadata sync
         ↓
Frontend polling detects change
         ↓
Custom UI updates (new plan badge, token balance)

Result: 95% of subscription interactions handled in-app with seamless UX, while Polar portal handles payment-sensitive operations (5% of use cases) requiring regulatory compliance.

Proactive Health & Data Management:

Implemented automated cron jobs to maintain system health and prevent data bloat without manual intervention.

Polar Reconciliation Cron (/api/cron/polar-reconciliation):

• Schedule: Daily at 4:00 AM UTC
• Purpose: Sync database and Clerk with Polar (source of truth)
• Process: For each user with polarCustomerId, query Polar API, compare with DB, fix mismatches
• Impact: Catches re-registration, missed webhooks, manual Polar dashboard changes

Clerk Reconciliation Cron (/api/cron/clerk-reconciliation):

• Schedule: Daily at 3:00 AM UTC (Vercel Hobby–compatible; once per day)
• Purpose: Self-healing system that detects and fixes DB-Clerk desynchronization
• Process: Scans all users, identifies discrepancies (plan ID, token balance, subscription status), automatically corrects mismatches
• Monitoring: Alerts if desync rate exceeds 1%, tracks fix success rate
• Impact: Zero manual intervention required; system self-corrects before users notice issues

Webhook Cleanup Cron (/api/cron/webhook-cleanup):

• Schedule: Daily at 2:00 AM UTC
• Purpose: Delete webhook events older than 30 days to prevent database bloat
• Process: Removes processed webhook records while maintaining audit trail for debugging
• Retention: Configurable 30-day history balances compliance with performance
• Impact: Prevents WebhookEvent table growth, maintains query performance

Webhook Recovery Cron (/api/cron/webhook-recovery):

• Schedule: Daily at 5:00 AM UTC
• Purpose: Retry unprocessed webhook events (e.g., crashed between claim and mark)
• Process: Finds events with processedAt: null in retry window (5 min–24 h old), re-applies via retryWebhookEvent
• Impact: Self-healing for transient failures; events older than 24 h marked as failed

Security Architecture:

• Authorization: Bearer token authentication (CRON_SECRET) prevents unauthorized execution
• IP Logging: Tracks unauthorized access attempts for security monitoring
• Fail-Open Design: Returns 200 on error to prevent Vercel retry storms (next scheduled run will retry)
• Observability: Comprehensive logging of execution duration, items processed, failure rates

Operational Metrics:

• Reconciliation: Typically 0.00% desync rate, sub-300ms execution time
• Cleanup: ~15,000 events deleted daily, sub-100ms execution time
• Reliability: Zero manual intervention required since deployment

Test Coverage: __tests__/app/api/cron — 57 Jest tests across cron route handlers (authorization, success, errors; run npx jest __tests__/app/api/cron for the exact set).

Automated Testing (verify with npm test — numbers below from Jest as run in dev):

• Payment stack — npm run test:polar-webhooks: 652 Jest tests across __tests__/lib/polar, __tests__/hooks/webhooks/polar, __tests__/api/webhook, __tests__/modules/webhooks
• Subscription credits UI — 117 tests in the four primary files listed above (213 under __tests__/components/credits; +98 under __tests__/components/subscriptions for account-management integration)
• Cron routes — 57 tests under __tests__/app/api/cron
• Repo-wide — 7,389+ Jest test cases across 709 suite files (count shifts as tests are added)
• Financial Standards — Invariants covered by dedicated suites (webhook-subscription-transitions, integration routes)
• E2E — Playwright on critical journeys (npm run test:e2e*), including payment lifecycle, URL contracts, and exam routes
• Idempotency — __tests__/lib/polar/webhook-idempotency.test.ts and route integration tests (claim→mark, P2002 duplicates)
• Security Testing — Product ID / auth / signature scenarios in API webhook test folders
• Integration Testing — polar-state-machine-integration, polar-e2e-scenarios, real-application suites
• Test gold audit — npm run test:gold-audit:diff on PRs; nightly full manifest audit via GitHub Actions

Live Validation (Jan 28, 2026):

• 7 Real User Scenarios — Complete subscription lifecycle tested with actual Polar webhooks
• 100% Congruency — Verified state synchronization across Polar → Database → Clerk → Frontend
• Token Calculations — All upgrade/downgrade/cancel/topup scenarios validated with real data
• Webhook Processing — ~40 webhook deliveries processed successfully with proper deduplication
• State Machine — All transitions tested (FREE → ACTIVE → CANCELED_PENDING → etc.)
• Payment Failure UX — Alert component integrated and tested with 2 new scenarios
• Automated Health Checks — Reconciliation and cleanup cron jobs deployed and validated

Test Execution: see npm test; npm run test:polar-webhooks alone is 652 cases; full Jest run is 7,389+ cases (709 suites)

Polar & billing guides (docs/polar/, ~213 KB total):

• POLAR_INTEGRATION_TECHNICAL_GUIDE.md (~33 KB) — Complete implementation guide, security architecture, custom UI documentation
• PAYMENT_IMPLEMENTATION_WALKTHROUGH.md (~10 KB) — Developer walkthrough: Polar as source of truth, claim→apply→mark flow, event handlers, state machine
• STRIDE_THREAT_MODEL.md (~70 KB) — Security threat analysis, attack scenarios, defense-in-depth validation
• E2E_SUBSCRIPTION_COMPLETE_CYCLE.md (~25 KB) — Live E2E subscription lifecycle scenarios and validation notes
• CRON_IMPLEMENTATION.md (~18 KB) — Automated maintenance system documentation, cron job architecture, monitoring guide
• WEBHOOK_RECOVERY.md (~14 KB) — Webhook recovery cron, retry windows, and operational runbook
• EXPO.md (~42 KB) — Mobile client integration notes for Polar and session sync

Broader engineering index: docs/README.md — feature layout, cache components, next-intl, testing gold standard, and audit docs.

Custom UI Components:

• src/components/credits/subscription/plans/SubscriptionPlans.tsx — Plan display, upgrade/downgrade/cancel
• src/components/credits/subscription/plans/components/account-management/AccountManagementCard.tsx — Plan badge, actions, fix-payment when paymentFailed
• src/components/credits/ConfirmationDialog.tsx — Upgrade / downgrade / cancel confirmations
• src/components/credits/PaymentFailureAlert.tsx — Payment failure banner (v2.3)
• src/components/credits/subscription/plans/hooks/useSubscriptionActions.ts — Centralized server-action wiring for the credits flow

Security Rating: 9.8/10 ⭐⭐⭐ (Enterprise-grade: HMAC webhooks, RLS, idempotent money writes; optional Zuplo edge documented in STRIDE threat model)

Modern form architecture leveraging React 19 hooks and Next.js 16 server actions for optimal DX and performance.

Canonical references: FORM_ACTIONS_ARCHITECTURE.md · ActionState<T> in src/lib/utils/form-actions.ts

• Progressive Enhancement — Forms work without JavaScript using native FormData submission, enhanced with client-side validation when available
• Type-Safe Validation — Dual-layer Zod schema validation (client-side React Hook Form + server-side safeParse) ensures data integrity at every boundary
• Optimized Re-renders — useWatch replaces form.watch() for granular field subscriptions, eliminating unnecessary component updates
• Stable Event Handlers — React 19's useEffectEvent provides dependency-free callbacks for effect handlers, removing dependency array confusion
• Data-Driven Rendering — Configuration objects with map() eliminate JSX repetition while maintaining type safety and readability

┌─────────────────────────────────────────────────────────────┐
│  1. User submits form → <form action={formAction}>          │
├─────────────────────────────────────────────────────────────┤
│  2. Client-side validation → React Hook Form + Zod          │
├─────────────────────────────────────────────────────────────┤
│  3. FormData serialization → Native browser behavior        │
├─────────────────────────────────────────────────────────────┤
│  4. Server action invoked → useActionState manages pending  │
├─────────────────────────────────────────────────────────────┤
│  5. Server-side validation → Zod safeParse with structured  │
│     error responses                                          │
├─────────────────────────────────────────────────────────────┤
│  6. Database mutation → Prisma with RLS policies            │
├─────────────────────────────────────────────────────────────┤
│  7. Response handling → useEffectEvent for success/error    │
└─────────────────────────────────────────────────────────────┘

• Hook-Composed Complex Forms — VerbAttributesForm delegates to useCreateVerbForm (src/components/conjugator/form/create-verb-form/hooks/) with child field components; legacy VerbAttributesFormProvider context was removed
• Reference implementations — AddAdjectiveForm.tsx, WordWizardForm.tsx, TextProcessor.tsx, useCreatePodcastForm / useCreateConversationForm
• Structured Error Handling — Most actions return typed ActionState<T> from src/lib/utils/form-actions.ts; Lexical document actions use a separate CreateEditorDocumentState (ok / fieldErrors) shape
• Test Coverage — Forms tested with data-testid attributes (never text content), ensuring reliable test stability across next-intl copy and content changes
• Creatable Fields — Collection routes use CollectionWordSelect; verb/subtitle flows use VerbCombobox → CreatableCombobox with explicit null-clear handling (opt?.value ?? '') for controlled React Hook Form fields

// Client Component
import { toast } from '@/lib/shared/toast'; // Sonner wrapper
import type { ActionState } from '@/lib/utils/form-actions';

// Server Action with safeParse validation
export async function submitFormAction(
  prevState: ActionState<DataType>,
  formData: FormData,
): Promise<ActionState<DataType>> {
  const result = schema.safeParse(Object.fromEntries(formData));
  if (!result.success) {
    return { success: false, errors: result.error.flatten().fieldErrors };
  }
  // ... database mutation
  return { success: true, data: createdRecord };
}

const [actionState, formAction, isPending] = useActionState(
  submitFormAction,
  initialState,
);
const watched = useWatch({ control: form.control }); // Single subscription

const handleSuccess = useEffectEvent(() => {
  toast.success('Success!');
  onSuccess?.();
}); // No dependency array needed!

useEffect(() => {
  if (actionState.success) handleSuccess();
}, [actionState.success]);

A sophisticated AI tutoring system powered by Tambo SDK, providing personalized Polish language instruction with full conversation persistence and custom interactive learning components.

• Thread-Based Conversations — Full conversation history preserved across sessions with automatic restoration on page load
• Lab-Specific Context — AI tutor adapts per labContext string. Wired today: Aspect Master, Reflexive Lab, Preposition Lab, Motion Lab, Verb Prefixes, Spelling Master, Exam, Declension (per grammatical case), Adjectives/Adverbs collections, Occupations collection. (Character Lab and Idioms Lab do not yet mount a tutor wrapper.)
• Deferred loading — User opens tutor via opt-in gate; AITutorAssistantTambo (next/dynamic, ssr: false) loads the Tambo SDK bundle on demand
• Custom Interactive Components — AI can render learning-specific UI:
  • LearningHintCard — Contextual tips with difficulty levels and examples
  • ExerciseGenerator — Interactive quizzes with real Polish content
  • ProgressVisualization — Learning analytics with charts and statistics
• Thread Management — Archive conversations with titles/subtitles, restore previous threads, delete old conversations
• Message Limits — Configurable per-thread message caps with graceful degradation
• Token-Based Costing — Integrated with platform credit system, pre-authorization with actual usage tracking

┌─────────────────────────────────────────────────────────────┐
│  Lab wrapper (e.g. aspect-master/AITutorAssistant.tsx)      │
│  └── AITutorAssistant (gate: sign-in / subscription / open) │
│      └── AITutorAssistantTambo (dynamic, ssr: false)        │
│          ├── TamboProvider (SDK context + auth token)         │
│          │   ├── useTamboThread / useTamboThreadInput         │
│          ├── ChatHeader                                       │
│          │   ├── ThreadSelector                               │
│          │   └── ThreadArchiveForm                            │
│          ├── MessageList (MessageItem, MarkdownRenderer)      │
│          ├── ChatInput                                        │
│          └── QuickSuggestions                                 │
└─────────────────────────────────────────────────────────────┘

Registry & config: src/components/tambo/config/tambo-config.ts. Base shell: src/components/tambo/ai-tutor-assistant/.

┌─────────────────────────────────────────────────────────────┐
│  Thread Creation & Persistence Flow                         │
├─────────────────────────────────────────────────────────────┤
│  1. User opens lab → Check localStorage for saved threadId  │
│  2. If found → Restore thread with retry logic (3 attempts) │
│  3. If not → Create new thread on first message             │
├─────────────────────────────────────────────────────────────┤
│  4. Messages sent → Real-time streaming response            │
│  5. Thread auto-saved → localStorage + database sync        │
│  6. Message count tracked → Update database periodically    │
├─────────────────────────────────────────────────────────────┤
│  7. User archives → Save title/subtitle, mark as archived   │
│  8. New thread created → localStorage cleared, fresh start  │
│  9. User can restore → Select from dropdown, switch thread  │
│  10. User can delete → Permanent removal from database      │
└─────────────────────────────────────────────────────────────┘

The AI can dynamically render interactive learning components by returning structured JSON:

// AI returns component specification
{
  "component": "ExerciseGenerator",
  "props": {
    "title": "Verb Aspect Practice",
    "exercises": [
      {
        "question": "Wczoraj _____ (czytać/przeczytać) książkę przez cały dzień.",
        "options": ["czytałem", "przeczytałem", "czytam"],
        "correctAnswer": "czytałem",
        "explanation": "Use imperfective 'czytałem' for duration"
      }
    ]
  }
}

// Component registry maps to React component with Zod validation
const tamboComponents = [
  { name: 'ExerciseGenerator', component: ExerciseGenerator, propsSchema: exerciseGeneratorSchema },
  { name: 'LearningHintCard', component: LearningHintCard, propsSchema: learningHintCardSchema },
  { name: 'ProgressVisualization', component: ProgressVisualization, propsSchema: progressVisualizationSchema }
];

model TamboThread {
  id           String    @id @default(cuid())
  userId       String
  labContext   String    -- "aspect-master", "reflexive-lab", "exam", etc.
  threadId     String    -- Tambo SDK thread identifier
  title        String?
  subtitle     String?
  isCurrent    Boolean   @default(false)
  isArchived   Boolean   @default(false)
  messageCount Int       @default(0)
  createdAt    DateTime  @default(now())
  updatedAt    DateTime  @updatedAt
  archivedAt   DateTime?

  User User @relation(fields: [userId], references: [clerkId], onDelete: Cascade)

  @@unique([userId, labContext, threadId])
}

(See prisma/schema.prisma for indexes.)

• 267+ tests under __tests__/components/tambo/ (hooks co-located there, not a separate __tests__/hooks/tambo/ tree)
• Server action tests — __tests__/lib/actions/tambo*.test.ts
• Integration — __tests__/tambo-integration.test.tsx, collection-ai integration suites
• Component isolation — Each UI component tested with mocked Tambo hooks
• Docs — docs/tambo/TAMBO_AI_INTEGRATION.md, TAMBO_THREAD_MANAGEMENT.md

A production-grade real-time chat system built on Stream Chat SDK with Firebase Cloud Messaging (FCM) integration for reliable push notifications across web, Android, and iOS.

• Multi-Tenant Messaging — Users can only chat with members of their organization through Clerk ID validation and company-scoped user queries (CompanyChatPeersProvider)
• Real-Time Updates — Instant message delivery with typing indicators, read receipts, and presence status via Stream Chat WebSocket
• Channel Management — Create, archive, and restore conversation channels with persistent state (ChannelRestorer, deep-link via ChannelIdHandler)
• Global push toggle — Enable/disable FCM from chat sidebar menubar; preferences persisted via /api/push-preference
• Responsive Design — Adaptive sidebar/channel layout with mobile-first breakpoint management
• Internationalization — Polish language support with custom translations via Streami18n

┌─────────────────────────────────────────────────────────────┐
│  Push Notification Flow (Stream Chat Push v3 + Firebase)   │
├─────────────────────────────────────────────────────────────┤
│  1. User enables notifications → Browser permission request │
├─────────────────────────────────────────────────────────────┤
│  2. Permission granted → Firebase SDK requests FCM token    │
├─────────────────────────────────────────────────────────────┤
│  3. FCM token obtained → Register with Stream Chat          │
│     via client.addDevice(token, 'firebase', userId)         │
├─────────────────────────────────────────────────────────────┤
│  4. Push template configured → Stream API receives template │
│     with platform-specific notification payloads            │
├─────────────────────────────────────────────────────────────┤
│  5. New message event → Stream sends to Firebase servers    │
├─────────────────────────────────────────────────────────────┤
│  6. Firebase delivers → Service worker receives & displays  │
│     notification even when app is backgrounded/closed       │
└─────────────────────────────────────────────────────────────┘

Stream Chat Push v3 uses Handlebars-style templates for customizable notifications:

{
  "data": {
    "version": "v2",
    "sender": "stream.chat",
    "type": "{{ event_type }}",
    "channel_id": "{{ channel.id }}",
    "message_id": "{{ message.id }}"
  },
  "android": {
    "priority": "high",
    "notification": {
      "title": "{{ sender.name }}",
      "body": "{{ truncate message.text 150 }}",
      "sound": "default"
    }
  },
  "webpush": {
    "notification": {
      "title": "{{ sender.name }}",
      "body": "{{ truncate message.text 150 }}",
      "icon": "{{ sender.image }}"
    },
    "fcm_options": { "link": "/chat" }
  },
  "apns": {
    "payload": {
      "aps": {
        "alert": {
          "title": "New message from {{ sender.name }}",
          "body": "{{ truncate message.text 150 }}"
        },
        "badge": "{{ unread_count }}",
        "sound": "default"
      }
    }
  }
}

┌─────────────────────────────────────────────────────────────┐
│  chat/page.tsx (RSC) → ChatPageClient (Clerk gate, SW reg)  │
│  └── ChatStreamAuthenticated (next/dynamic, ssr: false)     │
│      ├── CompanyChatPeersProvider                           │
│      ├── PushNotificationsProvider → usePushNotifications   │
│      └── <Chat> (stream-chat-react)                         │
│          ├── ChannelIdHandler                               │
│          ├── ChannelRestorer                                │
│          ├── ChatSidebar                                    │
│          │   ├── Menubar (ThemeToggleButton, push toggle)   │
│          │   ├── ChannelList                                │
│          │   └── UsersMenu (company-scoped discovery)       │
│          └── ChatChannel                                    │
│              ├── CustomChannelHeader                        │
│              ├── MessageList                                │
│              └── MessageComposer / CustomMessageInput       │
└─────────────────────────────────────────────────────────────┘

Entry: src/app/[lang]/(chat)/chat/. Stream components: src/components/stream-chat/.

The usePushNotifications hook (src/components/stream-chat/hooks/usePushNotifications.ts) manages the FCM lifecycle. It is consumed via PushNotificationsProvider, not wired directly in the page component:

interface UsePushNotificationsReturn {
  isSupported: boolean;
  isEnabled: boolean;
  isLoading: boolean;
  error: string | null;
  enablePushNotifications: () => Promise<boolean>;
  disablePushNotifications: () => Promise<boolean>;
}

// Options: { chatClient, userId } — required for Stream addDevice/removeDevice

Key responsibilities: browser support check → register SW → request permission → obtain FCM token → client.addDevice(token, 'firebase', userId) → persist preference via /api/push-preference → auto-register on client reconnect.

public/firebase-messaging-sw.js imports shared helpers from /fcm-push-utils.js, deduplicates message IDs (60 s window), handles notificationclick deep links back to /chat, and shows notifications for data-only FCM payloads when the app is backgrounded.

PoliLex is validated with a full testing pipeline that combines automated tests, static analysis, and load testing.
Every change is validated through:

• Automated unit and integration suites using Jest (7,389+ tests across 709 suites) and React Testing Library — combobox primitives (CreatableCombobox, VerbCombobox, CollectionWordSelect), flashcards, exam flows, polar webhooks (652 via test:polar-webhooks), and Lexical UI (EmojiMartPicker load/error paths)
• End-to-end regression tests with Playwright for critical user journeys in the browser (payments, URL contracts, editor, exam, verb families, podcast/video routes)
• Load and performance exercises with k6 and Artillery focused on core APIs, server-side operations, and caching behavior (npm run load-test:k6:*, npm run load-test:artillery:*)
• Strict static typing and schema validation with TypeScript (strict mode), Prisma, Zod, and @t3-oss/env-nextjs for data, inputs, and configuration
• Automated linting and formatting with ESLint, Prettier, and import-sorting to enforce consistent, production-grade code quality
• Test gold audit — manifest-tier enforcement via npm run test:gold-audit:diff (PR) and nightly GitHub Actions audit; primary lint/type-check/Jest/build runs locally and on Vercel (see PPR section above)

Engineering docs: docs/README.md — index for cache components, next-intl, forms, polar, testing gold standard, and feature audits.