Skip to main content

​
API Overview

Estudio Three uses a modern serverless architecture with Supabase as the backend and Vercel for serverless functions.

​
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

All API operations require authentication via Supabase Auth. The system supports:
  • Email/Password authentication
  • OAuth providers (Google, GitHub)
  • Session-based access control
  • Automatic Row Level Security (RLS)
See Authentication for detailed implementation.

​
Base URLs

​
Supabase API
https://[project-id].supabase.coConfigured via VITE_SUPABASE_URL environment variable
​
Vercel Functions
/api/* endpoints deployed on your Vercel domainExample: https://your-domain.vercel.app/api/ai

​
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

The API operates on these core entities:
  • 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

All endpoints return consistent error formats: 
{
  "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)

All database tables have RLS policies that automatically filter data by user_id: 
-- Example RLS policy
create policy "Usuarios gestionan sus tareas" 
  on tasks for all 
  using ( auth.uid() = user_id );
This means users can only access their own data, even if they know other record IDs.

​
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

Most API operations are abstracted through Zustand stores:
  • useAuthStore: Authentication and profile management
  • useTaskStore: Task CRUD operations
  • useCalendarStore: Event and calendar operations
  • useRoutineStore: Routine generation and management

​
Next Steps

Authentication

Learn about sign-up, sign-in, and session management

AI Coach

Integrate the AI coaching and translation endpoint

Tasks

Manage tasks, subtasks, and recurring patterns

Calendar

Work with events and weekly schedules