Playfit Game Assistant

Context

Playfit is a modern, full-stack video game recommendation assistant built to help players manage backlog fatigue and choose their next game. The product delivers an interactive onboarding flow and personalized suggestions instantly, without requiring user registration. The entire codebase is open source (github.com/carloseav15/playfit), serving as the foundation for an upcoming multi-platform rollout including native Android, iOS, and Flutter clients planned for 2026.

Problem

Most game discovery tools force users to go through complex setup, sign-up barriers, and manual catalog creation before giving value. This initial friction leads to high bounce rates. Additionally, recommendation engines often suffer from cold-start problems and fail to calculate friction risk (e.g., suggesting a frustrating Souls-like game to a casual player).

Constraints

• Onboarding must remain "Zero-Login" (no credentials required) while retaining offline progress.
• Initial recommendations must load in sub-second times.
• Relational data logic and security must be enforced on the database layer (RLS) without exposing administrative bypass keys.
• Profile migrations must be atomic: if a guest user decides to sign up, their local data must merge cleanly with the cloud database.
• Linter and tests must run in milliseconds inside local environments and CI pipelines to support fast iterations.

Approach

Monorepo Architecture

I structured Playfit as a monorepo with two isolated workspaces. apps/web runs the Next.js 16 UI and serverless API routes. packages/core holds all domain logic — the recommendation engine, IndexedDB store integrations, and Supabase database clients. The core package is imported by the web app but remains framework-agnostic, making it straightforward to reuse when native mobile clients are added.

Local-First Onboarding

Every visitor gets an instant session with a browser-generated UUID v4 stored in IndexedDB. No sign-up, no email, no friction. The recommendation engine scores games by genre and tag affinity, applying penalty weights when a user flags a genre as frustrating (e.g., Souls-like for casual players). All state lives locally until the user chooses to create an account.

Security & Migration

Server-side administrative keys are never available at runtime. PostgreSQL Row-Level Security (RLS) policies and SECURITY DEFINER functions enforce authorization directly in the database. When a guest decides to sign up, a Supabase Edge Function (Deno) atomically merges their IndexedDB profile into the cloud account — no data loss, no duplicates.

Results

• Separated business engine (@playfit/core) and routing (apps/web) to ensure codebase maintainability.
• Open-source codebase published on GitHub (github.com/carloseav15/playfit) to show architecture transparency.
• Fast onboarding and immediate recommendations served directly from IndexedDB state.
• Sub-second recommendation rendering using database-backed caching tables (api_cache) to store raw API outputs.
• Robust security architecture using strict RLS rules, database rate limiters, and RPCs for CRUD operations.
• Full automated testing suite including 13+ unit/integration test files (Vitest) and End-to-End user flow tests (Playwright).
• Roadmap established for native iOS, Android, and Flutter clients utilizing shared core engines.

Learnings

• Local-first strategies dramatically improve user acquisition and initial engagement.
• Shifting security checks directly to the database via RLS and PostgreSQL functions simplifies the serverless API footprint.
• De-duplicating game IDs via recursive database redirect tables is critical to catalog integrity.
• Biome linter and Vitest speed up local loops, ensuring high quality before code reaches the GitHub Actions pipeline.