​

API Overview

​

Architecture

​

Backend Stack

• Supabase: PostgreSQL database with real-time subscriptions
• Vercel Serverless Functions: AI and translation endpoints
• Zustand Stores: Client-side state management with Supabase sync
• Row Level Security (RLS): User data isolation at database level

​

Data Flow

Client (Zustand Store) <-> Supabase API <-> PostgreSQL
                      \-> Vercel Functions <-> External AI APIs

​

Authentication

• Email/Password authentication
• OAuth providers (Google, GitHub)
• Session-based access control
• Automatic Row Level Security (RLS)

​

Base URLs

​

Rate Limiting

​

AI Coach Endpoint

• Limit: 30 requests per minute per IP address
• Tracking: In-memory rate limit map with 60-second sliding window
• Error Code: 429 when limit exceeded

// Rate limit response
{
  "error": "Demasiadas peticiones",
  "code": 429
}

​

Supabase Operations

• No explicit rate limits on read operations
• Write operations protected by RLS policies
• Connection pooling handles concurrent requests

​

Data Models

• Profiles: User profiles with onboarding state
• Tasks: Academic and personal tasks with subtasks
• Events: Calendar events (exams, matches, training, classes)
• Routines: Daily routine blocks (fixed and flexible)
• Focus Sessions: Pomodoro-style work sessions
• Subjects: Academic subjects with difficulty ratings
• Goals: Long-term objectives with progress tracking

​

Error Handling

{
  "error": string,  // Human-readable error message
  "code": number    // HTTP status code
}

​

Common Error Codes

• 400: Bad request (missing or invalid parameters)
• 401: Unauthorized (invalid or missing authentication)
• 403: Forbidden (RLS policy violation)
• 404: Not found
• 429: Rate limit exceeded
• 500: Internal server error
• 503: Service unavailable (AI provider down)

​

Security

​

Row Level Security (RLS)

-- Example RLS policy
create policy "Usuarios gestionan sus tareas" 
  on tasks for all 
  using ( auth.uid() = user_id );

​

API Key Management

• Supabase anonymous key is safe for client-side use
• Vercel function secrets (e.g., GROQ_API_KEY) are server-side only
• CORS is configured to allow requests from your app domain

​

Client Libraries

​

Supabase Client

import { createClient } from '@supabase/supabase-js';

export const supabase = createClient(
  process.env.VITE_SUPABASE_URL,
  process.env.VITE_SUPABASE_ANON_KEY
);

​

Store-based Operations

• useAuthStore: Authentication and profile management
• useTaskStore: Task CRUD operations
• useCalendarStore: Event and calendar operations
• useRoutineStore: Routine generation and management

​

Next Steps