TheFittClub Vault

thefittclub-product

5 min read

Sistema de documentos del proyecto:

Documentos técnicos complementarios:

🏆 TheFittClub V2: Master Business Logic & Requirements

This document is the Single Source of Truth for all functional requirements. Any technical implementation must satisfy these business tiers while adhering to the Edge-Native (Cloudflare/D1/RRv7) architecture.

🏗️ LAYER 1: PLATFORM GLOBAL RULES (The Ecosystem)

1. Product Matrix & Upselling

  • Free Combination: Users can own and mix Rituals, Modules, and Capsules. All must coexist in a unified Dashboard (“Mi Espacio”).
  • Dynamic Upselling: The Dashboard uses AI-detected tags (e.g., “lumbar pain”) to suggest specific Capsules or Modules (Ticket 5).
  • Access Control (Ticket 3): Access is strictly managed by user_purchases. Free products (Lead Magnets) bypass Stripe but are registered in D1.

2. Billing, Benefits & Guarantees (Ticket 3 & 9)

  • Club Discount: Active subscribers get a permanent 5% discount on one-off purchases (Modules/Capsules).
  • Refund Windows: Rituals (7 days), Modules (3 days), Capsules (0 days - No refunds).
  • Gifting (Ticket 9): Users can purchase products as gifts, generating a unique gift_vouchers code for third-party redemption.

3. Gamification & Global Stats (Ticket 8)

  • Global Streak: Any completion across any product adds to the “Días Activos” global counter and total minutes.
  • Isolation: Progress within a Ritual does NOT unlock phases in a Module. Each program track is independent in D1.
  • Async Processing: All gamification logic (streaks, badges) is handled via Cloudflare Queues to ensure <200ms response times.

🧩 LAYER 2: THE UNIVERSAL ADAPTIVE ENGINE (Building Blocks)

Every program is a “Playlist” of these relational blocks:

1. The Session Canvas (Ticket 2)

  • Canvas Order: Administrators define the sequence (e.g., PDF Intro → Audio → Routine → PDF Tips).
  • 3-Series Routine: Routines are split into Warmup, Main, and Cool-down blocks.
  • Playback State: Video/Audio progress is persisted in user_playback_state for cross-device continuity.

2. Progressive Intelligence (Ticket 2 & 7)

  • RPE Scaling: After each session, users rate effort (1-10). If RPE >= 9, the engine stays at the current version. If ⇐ 8, it scales up to Version 6 (Ticket 7).
  • AI Overrides: If an exercise is “Banned” in user_exercise_preferences, the loader automatically injects the alternative_exercise_id.

3. Personal Journal & AI Memory (Ticket 5)

  • Dual Storage: D1 stores the raw text/photo and the NLP-extracted tags (e.g., “high stress”, “diastasis”).
  • Async NLP: Analysis is performed via context.cloudflare.waitUntil to avoid UI latency.

📜 LAYER 3: PRODUCT-SPECIFIC MECHANICS

3.1 RITUALS (Continuous Transformation)

Ej: Ritual Core, Ritual Tao, Ritual Glúteos.

  • Modalities: Users choose daily: Express (5m), Base (20m), or Progressive (Versions 1-6).
  • Phase Ascent (Ticket 6):
    • Fast Track: 3 consecutive weeks, 4 days/week, min 80 min/week.
    • Slow Track: 6 consecutive weeks, 4 days/week (no min minutes).
  • Clinical Fail-Fast (Ticket 6): If the Phase Evaluation fails, the user is locked in “Modo Preparación” with a mandatory compensation exercise for prep_quarantine_days.
  • Loop Logic (Ticket 7): When reaching the end (e.g., Day 180), the sequence loops back automatically using modular arithmetic.

3.2 MODULES (Targeted Recovery)

Ej: Cesárea (MVP), Diástasis, Postura, Caderas Libres.

  • Duration: 4-8 weeks (20-40 effective days).
  • Flow: On-demand progress. No blocking evaluations.
  • Active Components: Context, Techniques, Bitácora (Metrics), and Journal (AI).

3.3 CAPSULES (Rescue Pills)

Ej: SOS Lumbar, Despertar Pélvico (Free), Reto Hipopresivos 30D.

  • Duration: 1-21 days.
  • Flow: Direct consumption. Clinical metrics (Bitácora) and Journal are DISABLED to reduce friction.
  • Rewards: Contribute to Global Streak and grant a completion Badge.

🛠️ ARCHITECTURAL GUARDRAILS (The Architect’s Code)

  1. Loader-First: Data fetching belongs in RRv7 loaders. No client-side useEffect for initial data.
  2. D1 Relational Purity: No JSON arrays for core relations. Use junction tables and normalized rows (e.g. member_conditions keyed off physical_profiles, exercise_materials, phase schedule links).
  3. Compound Keys: Use composite primary keys where appropriate for idempotency (e.g. product_user_progress: user_id + product_id; onboarding: product_id + question_id).
  4. Edge runtime in Workers: Request handlers and loaders must stay Edge-safe: no Node-only fs / path / Node crypto in app code bound to Workers. Tooling (catalog sync, seeds, Drizzle kit) may use Node locally; keep those scripts out of Worker bundles (see scripts/catalog/*, scripts/seeds/*).
  5. Ticket-driven development: No implementation without an approved ticket under _docs/00-tickets/ (see _docs/03-architecture/workflow-arquitect.md). _docs/04-specs/ is reserved for strict QA contracts when a ticket explicitly requires them—not a prerequisite for every feature.

Catalog note (implementation detail)

Editorial content is mostly relational in D1 (training_sessions and related tables). The legacy routines table for Ritual Core Phase 1 is still populated from TypeScript (app/lib/catalog/data/ritual-core/phase-1) via npm run db:sync:catalog until that path is fully migrated. See thefittclub-private-catalog-data.md.

Architectural Decision Log:

  • [2026-04-04] V2 Pivot: Catalog moved from TS files to D1 Relational Schema.
  • [2026-04-04] Async Logic: Gamification moved to Cloudflare Queues; AI NLP moved to waitUntil.
  • [2026-04-24] Schema split: Drizzle definitions live under app/db/schema/ (domain modules + barrel index.ts).
  • [2026-04-26] Docs: Dual catalog pipeline documented — relational canvas + legacy routines TS sync (thefittclub-private-catalog-data.md).
  • [2026-04-26] Docs: Brand identity documentation system established — see thefittclub-brand.md and related files.

Graph View

Backlinks