Yaroslav Smirnov

Matrix Teaching Quest

Interactive stateful narrative engine with custom first-party analytics pipeline. Designed as high-engagement lead conversion funnel for educational platforms. Demonstrates expertise in state machine design, async backend architecture, and zero-dependency analytics infrastructure.

Why This Project Matters

Traditional marketing funnels suffer from opacity—third-party analytics (Google Analytics, Mixpanel) are fragile (GDPR, cookie restrictions), expensive, and create vendor lock-in. Marketing teams need granular funnel visibility but sacrifice user privacy and data ownership.

This system solves three problems:

  1. Data Ownership: Custom analytics pipeline eliminates reliance on third-party trackers. 100% data ownership, no GDPR violations, no dependency on cookie-heavy infrastructure.
  2. Engagement: Static landing pages convert poorly. Stateful, branching narrative experience keeps users engaged longer, improving conversion rates.
  3. Funnel Intelligence: Scene-by-scene abandonment tracking identifies exactly where users drop off. Traditional analytics can’t correlate user behavior within a single-page experience.

The technical challenge: coordinating stateful game logic with real-time analytics, maintaining consistency across client/server boundaries, and designing a browser fingerprinting system robust enough for anonymous session tracking without cookies.

System Architecture & Design

Backend Design Philosophy

Architected as a distributed state machine with separate concerns for game logic, analytics, and admin infrastructure:

Async-First Core

Stateful Narrative Engine

First-Party Analytics Pipeline

Admin Infrastructure

Service Architecture

Frontend (React + Framer Motion)
    ↓ (HTTP)
    ├─ POST /api/v1/quest/start → Initialize session + fingerprint
    ├─ PUT /api/v1/quest/progress → Update scene + log event
    ├─ POST /api/v1/achievements/unlock → Claim achievement
    ├─ POST /api/v1/promo/claim → Generate promo code
    └─ GET /api/v1/analytics/session → Retrieve funnel state
        ↓
FastAPI Backend (Async Routes)
    ├─ Quest Router: Scene transitions, state validation
    ├─ Analytics Router: Event logging, session tracking
    ├─ Achievements Router: Logic for unlock conditions
    ├─ Promo Router: Code generation + quota management
    └─ Admin Router: Dashboard data aggregation
        ↓
PostgreSQL Database
    ├─ sessions table: fingerprint, created_at, last_event
    ├─ events table: session_id, event_type, scene_id, timestamp
    ├─ quest_progress table: session_id, current_scene, unlocked_achievements, JSON state
    ├─ achievements table: id, name, unlock_condition, rarity
    ├─ promo_codes table: code, redeemed, generated_at, generated_for_user
    └─ (Optimized indices on fingerprint, session_id, event_type)

Key Technical Features

Technologies & Stack

Backend

Frontend

Database & Analytics

Infrastructure & DevOps

Engineering Challenges & Trade-offs

Challenge 1: Stateless Analytics in Stateful System

Problem: Traditional analytics assumes stateless HTTP requests. This game is a single-page state machine—you need to correlate multiple events (scene 1 → scene 5 → achievement unlock) to understand user journeys.

Solution Implemented:

Trade-off: Custom analytics requires more code maintenance than GA/Mixpanel, but provides deeper insights and zero vendor lock-in.

Challenge 2: State Consistency Across Client/Server

Problem: Client and server can become out-of-sync if user has poor connection or closes browser mid-request.

Solution Implemented:

Trade-off: Added complexity for robustness. Alternative: simpler eventual-consistency approach (client state always wins) but risks confusing users.

Challenge 3: Achievement Logic Explosion

Problem: 10+ achievements with interdependent unlock conditions (e.g., “unlock if you’ve seen all 5 secret scenes AND visited scene 7 in under 30 seconds”).

Solution Implemented:

Trade-off: More complex code but avoids hardcoding achievement logic in multiple places.

Challenge 4: Promo Code Exhaustion

Problem: Admin sets quota of 100 codes. Multiple concurrent users might claim simultaneously, exhausting quota unfairly or triggering race conditions.

Solution Implemented:

Trade-off: Row-level locking adds ~20ms latency per code claim, but guarantees no overselling.

Challenge 5: Browser Fingerprinting Robustness

Problem: Fingerprinting must survive browser updates, VPN changes, and user privacy settings. False positive (two users identified as same) is worse than false negative.

Solution Implemented:

Trade-off: Imperfect fingerprinting (90% accuracy) but acceptable for marketing analytics. Hybrid approach: use fingerprint for anonymous users, Telegram ID for app users.

Potential Improvements for Production

Current State & Demo Notes

What Works Now

Demo Video

Watch system walkthrough on YouTube

Demonstrates:

Demo/Stub Limitations

None—system fully production-ready.

Why Certain Design Choices Exist

How This Project Demonstrates My Expertise

Backend Engineering

Database Design

Analytics & System Design

Full-Stack Thinking

Tangible Impact