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-utils/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-utils/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:'),
);

Raw revalidateTag() calls are never used directly in server action files. All cache invalidation goes through named helpers exported from src/lib/cache-utils/invalidate.ts, which owns every tag string as a single typed constant:

// 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

The advantage over raw 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. The project exports two separate Prisma clients at the infrastructure level:

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.

Two custom rules in eslint.config.mjs catch cache and logging mistakes at write time:

local/no-cached-prisma-outside-use-cache — warns when cachedPrisma is used inside a function that doesn't start with 'use cache'. Catches accidental RLS bypass. Set to warn because the rule cannot trace call stacks — helpers designed to be called from 'use cache' functions are valid uses:

// Blog posts are public data — anonymous RLS is intentional here.
/* eslint-disable local/no-cached-prisma-outside-use-cache */
const [posts, total] = await Promise.all([cachedPrisma.blogPost.findMany(...)]);
/* eslint-enable local/no-cached-prisma-outside-use-cache */

no-restricted-syntax on console.error — warns in all src/lib/actions/actions.*.ts and src/app/api/**/*.ts files, pointing developers to logUserError() instead. logUserError silently swallows AuthRequiredError (expected during PPR prerendering) and uses error.message + stack-frame fallback rather than error.constructor.name, which production minifiers mangle to single letters:

// Bad — constructor names mangle to 'i' or 'c' in production builds
console.error(
  'Update failed:',
  error instanceof Error ? error.constructor.name : typeof error,
);

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

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.

Every route that streams dynamic content through a <Suspense> boundary uses both loading mechanisms:

User clicks <Link href="/adjectives" />
  │
  ├─ loading.tsx → AdjectivesPageSkeleton     ← navigation window (before server responds)
  ├─ Server responds: static shell
  ├─ <Suspense fallback={<AdjectivesPageSkeleton />}> ← streaming window (while data resolves)
  └─ dataPromise resolves → full page

src/app/loading.tsx (root fallback) exports AppShellSkeleton — a pure Server Component that pixel-accurately mirrors the real Navbar: exact bg-white dark:bg-gray-800, same h-8 min-w-20.5 rounded-full pill tokens for LanguageSelector and DarkToggle, same gradient shells for the icon buttons. All 21 routes use the same skeleton-component contract rather than inline fallbacks or full-screen spinners.

Skeleton creation standards enforced across the codebase:

• Use <Skeleton> from @/components/ui/skeleton for individual elements
• Apply animate-pulse to a container — all elements pulse together as a unit
• Match colour tokens exactly from the real component (border, background, text)
• Always include dark: variants
• Never inline a skeleton in page.tsx — extract to src/components/<feature>/FeatureSkeleton.tsx so it can be imported by both <Suspense fallback> and loading.tsx

Full coverage: 21 routes each have a matching loading.tsx pointing to a properly-built page skeleton.

.github/workflows/pr-checks.yml runs three jobs on every PR:

The build job is the only place missing connection() calls surface — these errors only occur during next build, not next dev. Fork PRs skip it automatically (GitHub withholds secrets from forks).

Complete implementation details, every pattern, rationale, and checklist: docs/cache-components/CACHE_COMPONENTS.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/lib/actions/actions.subscriptions.ts):
  • 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; heavy Jest coverage on __tests__/lib/polar + __tests__/api/webhook (632 tests) and 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)

   • IP allowlisting for webhooks (Polar's 5 official IPs only)
   • Rate limiting (100 req/min webhooks, 20 req/min checkouts)
   • Comprehensive audit logging with IP, user agent, timestamp

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 where used for race-sensitive billing/user updates (see e.g. critical user action paths)
   • 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 component with prominent "Fix Payment" CTA
  • Alert displays on credits page when subscription.past_due webhook received
  • Shows period end date and redirects to Polar portal for secure payment update
  • ManageSubscriptionBadge.tsx prioritizes payment failure button above all other actions
  • 2 new test scenarios added to credits page test suite
• 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: 246 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 — __tests__/lib/polar + __tests__/api/webhook: 632 Jest tests (idempotency, webhooks, state machine matrices, transitionSubscription, chaos/partial-failure suites)
• Subscription credits UI — 246 tests in the four files listed above
• Cron routes — 57 tests under __tests__/app/api/cron
• Repo-wide — 5,297+ Jest test cases (e.g. 5,297 on last full npx jest run; 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*)
• 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

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; payment-focused folders alone exceed 600 tests; full Jest run is 5,297+ cases

Seven Complete Guides (367 KB total):

• POLAR_IMPLEMENTATION.md (105 KB) — Complete implementation guide, security architecture, custom UI documentation, phase-by-phase build
• PAYMENT_IMPLEMENTATION_WALKTHROUGH.md — Developer walkthrough: Polar as source of truth, claim→apply→mark flow, event handlers, state machine
• STRIDE_THREAT_MODEL.md (54 KB) — Security threat analysis, attack scenarios, defense-in-depth validation
• INTEGRATION_TESTING_SUMMARY.md (9 KB) — Live testing results, all 7 scenarios documented, token calculation details
• DEVELOPER_QUICK_REFERENCE.md (6 KB) — Quick reference for daily work, schemas, debugging tips
• VALIDATION_REPORT_2026-01-28.md (13 KB) — Complete validation report with before/after comparisons
• CRON_IMPLEMENTATION.md (68 KB) — Automated maintenance system documentation, cron job architecture, monitoring guide
• RECOMMENDATIONS.md (112 KB) — Technical recommendations for hardening, observability, and production readiness

Custom UI Components:

• src/components/credits/subscription/plans/SubscriptionPlans.tsx — Plan display, upgrade/downgrade/cancel
• src/components/credits/ManageSubscriptionBadge.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 with Zuplo edge protection)

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

• 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    │
└─────────────────────────────────────────────────────────────┘

• Context-Based Complex Forms — VerbAttributesForm uses provider pattern to share state across nested components without prop drilling
• Field-Level Subscriptions — Single useWatch call for multiple fields, maintaining React Hook Form's optimization benefits
• Structured Error Handling — Server actions return typed ActionState<T> with success/error/data discriminated unions
• Test Coverage — Forms tested with data-testid attributes (never text content), ensuring reliable test stability across i18n and content changes

// 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 };
}

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

const handleSuccess = useEffectEvent(() => {
  toast({ title: '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 to current learning module (Aspect Master, Reflexive Lab, Preposition Lab, etc.)
• 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

┌─────────────────────────────────────────────────────────────┐
│  AITutorAssistant                                           │
│  ├── TamboProvider (SDK Context)                            │
│  │   ├── useTamboThread (conversation state)                │
│  │   └── useTamboThreadInput (message handling)             │
│  ├── ChatHeader                                             │
│  │   ├── ThreadSelector (dropdown with archived threads)    │
│  │   └── ThreadArchiveForm (save with title/subtitle)       │
│  ├── MessageList                                            │
│  │   ├── MessageItem (user/assistant messages)              │
│  │   ├── MarkdownRenderer (formatted responses)             │
│  │   └── LoadingIndicator (streaming state)                 │
│  ├── ChatInput (textarea with send button)                  │
│  └── QuickSuggestions (one-click prompts)                   │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│  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", etc.
  threadId    String    -- Tambo SDK thread identifier
  title       String?   -- User-provided archive title
  subtitle    String?   -- Optional description
  isCurrent   Boolean   @default(true)
  isArchived  Boolean   @default(false)
  messageCount Int      @default(0)
  createdAt   DateTime  @default(now())
  updatedAt   DateTime  @updatedAt
  archivedAt  DateTime?

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

• 122+ tests covering Tambo components and integration
• Component isolation — Each UI component tested independently with mocked Tambo hooks
• Integration tests — Full AITutorAssistant flow with mocked SDK responses
• Server action tests — Thread CRUD operations with Prisma mocking

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
• 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 across sessions
• Per-Channel Muting — Users can mute specific channels while maintaining global notification settings
• 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"
      }
    }
  }
}

┌─────────────────────────────────────────────────────────────┐
│  ChatPage                                                   │
│  ├── Chat (Stream Chat Provider)                            │
│  │   ├── ChannelIdHandler (deep-link support)               │
│  │   ├── ChannelRestorer (session persistence)              │
│  │   ├── ChatSidebar                                        │
│  │   │   ├── ChannelList (filterable channel list)          │
│  │   │   └── UserSearch (company-scoped user discovery)     │
│  │   └── ChatChannel                                        │
│  │       ├── Menubar                                        │
│  │       │   ├── ThemeToggle                                │
│  │       │   └── PushSubscriptionToggleButton               │
│  │       ├── CustomChannelHeader                            │
│  │       │   └── ChannelNotificationToggle (per-channel)    │
│  │       ├── MessageList                                    │
│  │       └── MessageInput                                   │
│  └── usePushNotifications (FCM hook)                        │
└─────────────────────────────────────────────────────────────┘

The usePushNotifications hook manages the complete FCM lifecycle:

interface UsePushNotificationsReturn {
  isSupported: boolean; // Browser supports notifications & Firebase configured
  isEnabled: boolean; // User granted permission
  isLoading: boolean; // Operation in progress
  error: string | null; // Last error message
  enablePushNotifications: () => Promise<boolean>;
  disablePushNotifications: () => Promise<boolean>;
}

// Key responsibilities:
// 1. Check browser support & Firebase configuration
// 2. Register Firebase service worker
// 3. Request notification permission
// 4. Obtain and cache FCM token
// 5. Register/unregister device with Stream Chat
// 6. Auto-register on client reconnection

The Firebase Messaging service worker handles background notifications:

// firebase-messaging-sw.js
importScripts('firebase/firebase-app-compat.js');
importScripts('firebase/firebase-messaging-compat.js');

// Receive config from main app via postMessage
self.addEventListener('message', (event) => {
  if (event.data?.type === 'FIREBASE_CONFIG') {
    firebase.initializeApp(event.data.config);
    const messaging = firebase.messaging();

    messaging.onBackgroundMessage((payload) => {
      const { title, body, icon } = payload.notification;
      self.registration.showNotification(title, { body, icon });
    });
  }
});

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 and React Testing Library for components and business logic
• End-to-end regression tests with Playwright for critical user journeys in the browser
• Load and performance exercises with Artillery focused on core APIs, server-side operations, and caching behavior
• 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
• CI pipeline (.github/workflows/pr-checks.yml) running lint, type-check, Jest, and next build on every PR — the build step is the only place missing connection() calls and 'use cache' violations surface (see PPR section above)