🚀 AlexDjangoX

Full-Stack Developer | AI Solutions

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 140 comprehensive tests
• Idempotency Guarantees — All operations use deterministic keys (SHA-256); safe retries without duplicate charges
• Fail-Open Design — System continues processing during transient failures; no legitimate transactions blocked
• Event-Driven Processing — Asynchronous webhook handlers with in-memory deduplication (O(1) lookup)

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)

• Multi-Layer Validation — Zod UUID format check → Business logic allowlist → Runtime authorization
• Webhook Security — HMAC signature verification on all payloads before processing
• Authentication Enforcement — Clerk authentication required for all server actions; automatic sign-in redirects
• Error Sanitization — User-facing messages sanitized through getUserErrorMessage(); no internal details exposed
• Audit Trail — All balance mutations recorded with transaction IDs for reconciliation and compliance

8 Event Types Processed:

• 140 Comprehensive Tests — 87% code coverage across all payment logic
• Financial Standards — Zero tolerance for test failures; all edge cases and error paths verified
• Idempotency Testing — Duplicate webhook delivery, race conditions, concurrent updates
• Security Testing — Product ID manipulation, authentication bypass, signature tampering
• Integration Testing — Full payment flows from checkout to token allocation

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