​

System Architecture

​

High-Level Architecture

​

Technology Stack

​

Frontend

​

Backend & Infrastructure

​

Additional Libraries

​

Architecture Layers

​

1. Presentation Layer (Frontend)

// next.config.ts
const nextConfig = {
  output: "export",
  images: { unoptimized: true }
}

• Static site generation (SSG) for optimal performance
• Client-side routing with Next.js App Router
• Progressive enhancement with JavaScript
• Responsive design with Tailwind CSS

src/features/
  ├── auth/           # Authentication components
  ├── dashboard/      # User dashboard
  ├── meal-plan/      # Nutrition plan display
  ├── workout-plan/   # Exercise plan display
  ├── wizard/         # 9-step plan generator
  ├── payment/        # Payment integration
  ├── subscription/   # Subscription management
  └── plans/          # Plan viewer and tracking

​

2. State Management

// Client-side state is managed with Zustand
// Key stores include:
- wizardStore     // Multi-step form state
- authStore       // User authentication state
- planStore       // Active plan data

• localStorage for wizard progress (pre-auth)
• Supabase for authenticated user data

​

3. Authentication Layer

• Magic link authentication (passwordless)
• Email/password authentication
• OAuth providers (future)
• Session management with JWT
• Row Level Security (RLS) enforcement

// src/lib/supabase/client.ts
import { createBrowserClient } from "@supabase/ssr";

export function createClient() {
  return createBrowserClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY,
    {
      auth: {
        persistSession: true,
        autoRefreshToken: true,
        detectSessionInUrl: true,
      },
    }
  );
}

​

4. Data Layer (Supabase)

• profiles - User profiles (extends auth.users)
• subscriptions - Active subscriptions
• user_plans - Generated fitness plans (freemium)
• wizard_data - Wizard form submissions
• plan_downloads - Download tracking and security
• webhook_logs - Payment webhook audit trail
• subscription_audit_log - Subscription change history

• Row Level Security (RLS) enabled on all tables
• Service role key for admin operations
• Anon key for client-side operations

​

5. Payment Processing Layer

1. Create MercadoPago payment preferences
2. Handle payment webhooks from MercadoPago
3. Activate subscriptions in Supabase
4. Log all payment events for audit

​

User Flow Architecture

​

New User Journey

​

Returning User Journey

​

Data Flow Patterns

​

1. Wizard Data Persistence

• Data stored in localStorage
• No server communication required
• Allows users to complete wizard before signup

• Migration from localStorage to Supabase wizard_data table
• Persistent across devices
• Used for plan regeneration

​

2. Plan Generation

​

3. Subscription Validation

// Pseudo-code
const canAccess = await checkAccess(userId);
// Checks:
// 1. User is authenticated
// 2. Has active subscription (status='active')
// 3. Subscription end_date > NOW()

​

Deployment Architecture

​

Production Environment

​

Staging Environment

​

Security Architecture

​

Authentication Security

• JWT tokens with automatic refresh
• HttpOnly cookies for session storage
• CSRF protection via Supabase
• Magic links expire after 1 hour

​

Database Security (RLS)

-- Example: Users can only view their own data
CREATE POLICY "Users can view own profile"
  ON profiles FOR SELECT
  USING (auth.uid() = id);

​

API Security

• CORS restricted to known origins
• Rate limiting on webhook endpoints
• Request signature verification (MercadoPago)
• Service role key stored as encrypted secrets

​

PDF Protection

1. No public URLs: PDFs generated on-demand
2. Watermarking: Email + expiration date embedded
3. Download tracking: Every download logged with IP
4. Rate limiting: Max 5 downloads per day for paid users
5. Authentication required: No anonymous access

​

Performance Optimization

​

Frontend Performance

• Static export: Pre-rendered HTML at build time
• Code splitting: Automatic with Next.js
• CDN: Global distribution via Cloudflare
• Image optimization: Disabled for static export (manual optimization)

​

Database Performance

• Indexes: All foreign keys and frequently queried columns
• Connection pooling: Managed by Supabase
• Query optimization: Using Supabase RLS and indexed filters

​

Worker Performance

• Edge computing: Low latency worldwide
• Concurrent execution: Auto-scaling
• Idempotency: Prevents duplicate webhook processing

​

Monitoring & Logging

​

Application Logs

• Frontend: Browser console errors (production: minimal)
• Worker: Cloudflare Workers logs
• Database: Supabase logs and metrics

​

Audit Trails

• webhook_logs: All payment webhooks
• subscription_audit_log: Subscription lifecycle events
• plan_downloads: Every PDF download

​

Scalability Considerations

​

Current Scale

• Database: Supabase free tier (500MB, 2GB bandwidth)
• Hosting: Cloudflare Pages (unlimited bandwidth)
• Workers: 100,000 requests/day (free tier)

​

Growth Strategy

1. Database scaling: Upgrade to Supabase Pro as needed
2. Worker scaling: Already auto-scales, may need paid plan
3. CDN: Already global, no action needed
4. Caching: Implement Redis for hot data (future)

​

Environment Variables

​

Frontend (.env.local)

NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...

​

Cloudflare Worker (secrets)

MP_ACCESS_TOKEN=APP-xxx
SUPABASE_URL=https://xxx.supabase.co
SUPABASE_SERVICE_KEY=eyJ...
WORKER_URL=https://mercadopago-jcv.fagal142010.workers.dev

​

Related Documentation

• Database Schema - Complete database structure
• Payment Integration - MercadoPago implementation
• Deployment Guide - Deployment procedures