System Status: ✅ v2.3 — Production Ready & Live Validated (January 28, 2026)

Migrated from Stripe to Polar for international tax compliance and simplified global operations. Polar acts as Merchant of Record, handling VAT, GST, and sales tax obligations across 100+ countries—eliminating the operational burden and legal exposure that Stripe leaves to merchants when selling internationally.

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

Design Principles:

• Financial Software Standards — Zero tolerance for bugs where money is involved; 87% test coverage with 279 comprehensive tests
• Database-Backed Idempotency — All webhook events use stable keys with persistent storage; prevents double-crediting on retries
• 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) — Monthly allocation, resets on renewal (e.g., 1,000 for Pro, 2,500 for Premium)
• 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 with stable keys (no timestamps, prevents replay attacks)
   • Atomic transactions with Serializable isolation (prevents race conditions)
   • 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)

9 Event Types Processed:

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

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 custom React components (1,631 tests) handling common subscription 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.

Reconciliation Cron (/api/cron/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

Cleanup Cron (/api/cron/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

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: 33 comprehensive tests validating authorization, success scenarios, error handling, and performance across both endpoints.

Automated Testing:

• 312 Comprehensive Tests — 87% code coverage across all payment logic (33 tests added for cron automation in v2.3)
• 1,631 UI Component Tests — Custom subscription UI fully tested (520 + 292 + 305 + 514 tests)
• 33 Cron Job Tests — Automated maintenance system fully validated (14 reconciliation + 19 cleanup tests)
• Financial Standards — Zero tolerance for test failures; all edge cases and error paths verified
• E2E Scenario Testing — 8 complete user journeys from signup to downgrade validated
• Idempotency Testing — Duplicate webhook delivery, race conditions, concurrent updates
• Security Testing — Product ID manipulation, authentication bypass, signature tampering, metadata tampering
• Integration Testing — Full payment flows with real webhook payloads
• Cron Security Testing — Authorization validation, unauthorized access logging, error handling, performance

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: 4,386 tests pass (312 payment + 1,631 UI + 33 cron + 2,410 other)

Seven Complete Guides (367 KB total):

• POLAR_IMPLEMENTATION.md (105 KB) — Complete implementation guide, security architecture, custom UI documentation, phase-by-phase build
• 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:

• SubscriptionPlans.tsx — Full-featured plan display with upgrade/downgrade/cancel functionality
• ManageSubscriptionBadge.tsx — Animated current plan badge with action buttons (includes payment failure handling)
• ConfirmationDialog.tsx — Contextual confirmation dialogs for destructive actions
• PaymentFailureAlert.tsx — Payment failure notification with "Fix Payment" CTA (v2.3)
• useSubscriptionActions.ts — React hook centralizing all subscription operations

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 k6 and 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