Arquitectura de Cierro

Visión General

Cierro es una aplicación SaaS construida con una arquitectura moderna de cliente-servidor, utilizando React en el frontend y Supabase como Backend-as-a-Service (BaaS).

Diagrama de Arquitectura

┌─────────────────────────────────────────────────────────────────┐
│                         CLIENTE                                  │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐ │
│  │   React     │  │  TipTap     │  │      Liveblocks         │ │
│  │   + Vite    │  │  Editor     │  │  (Colaboración Real)    │ │
│  └──────┬──────┘  └──────┬──────┘  └────────────┬────────────┘ │
│         │                │                       │               │
│         └────────────────┼───────────────────────┘               │
│                          │                                       │
└──────────────────────────┼───────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│                       AUTENTICACIÓN                              │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                        Clerk                              │   │
│  │  • Login/Registro  • OAuth  • JWT  • Session Management  │   │
│  └─────────────────────────────────────────────────────────┘   │
└──────────────────────────┬───────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│                        SUPABASE                                  │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐ │
│  │  PostgreSQL │  │   Storage   │  │     Edge Functions      │ │
│  │  + RLS      │  │   Buckets   │  │     (Deno Runtime)      │ │
│  └──────┬──────┘  └──────┬──────┘  └────────────┬────────────┘ │
│         │                │                       │               │
│         └────────────────┼───────────────────────┘               │
└──────────────────────────┼───────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│                    SERVICIOS EXTERNOS                            │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌───────┐ │
│  │ Resend  │  │ Gemini  │  │ HubSpot │  │Pipedream│  │Reveniu│ │
│  │ (Email) │  │  (IA)   │  │  (CRM)  │  │ (iPaaS) │  │(Pagos)│ │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘  └───────┘ │
└─────────────────────────────────────────────────────────────────┘

Componentes Principales

Frontend (React)

Estructura de URLs

La aplicación utiliza rutas con scope de empresa mediante slug:

/:slug/dashboard          # Dashboard principal
/:slug/proposals          # Lista de propuestas
/:slug/proposals/new      # Nueva propuesta
/:slug/proposals/:id      # Detalle/edición de propuesta
/:slug/clients            # Gestión de clientes
/:slug/catalog            # Catálogo de productos
/:slug/reports            # Reportes y analytics
/:slug/team               # Gestión de equipo
/:slug/settings           # Configuración
/:slug/workflows          # Automatizaciones
/:slug/admin              # Panel de administración (super admin)

Hook de Navegación: useCompanyNavigation proporciona funciones y paths para navegación consistente:

const { toProposals, toDashboard, paths, buildPath } = useCompanyNavigation();

// Navegación programática
toProposals();

// Uso con Link
<Link to={paths.proposals}>Propuestas</Link>

Estructura de Componentes

src/
├── components/
│   ├── budget/           # Editor de presupuestos
│   │   ├── editor/       # Componentes del editor
│   │   │   ├── tiptap/   # Extensiones TipTap
│   │   │   ├── blocks/   # Bloques del documento
│   │   │   └── templates/# Plantillas
│   │   └── ...
│   │
│   ├── dashboard/        # Widgets del dashboard
│   ├── reports/          # Gráficos y tablas
│   ├── settings/         # Configuración
│   ├── team/             # Gestión de equipo
│   ├── tour/             # Sistema de tours guiados
│   ├── workflows/        # Editor visual de automatizaciones
│   │   ├── nodes/        # Nodos (Trigger, Condition, Action)
│   │   ├── panels/       # Paneles de configuración
│   │   └── templates/    # Galería de plantillas
│   └── ui/               # Componentes shadcn
│
├── contexts/
│   └── AuthContext.tsx   # Estado de autenticación
│
├── hooks/                # Custom hooks
│   ├── useCompanyNavigation.ts  # Navegación con slug
│   ├── useTour.ts        # Gestión de tours
│   └── ...
└── pages/                # Páginas/rutas

Librerías Principales

Librería	Propósito
React 18	UI Framework
TipTap	Editor WYSIWYG
Liveblocks + Yjs	Colaboración en tiempo real
React Query	Cache y estado del servidor
shadcn/ui	Componentes UI
Tailwind CSS	Estilos
Recharts	Gráficos

Backend (Supabase)

PostgreSQL + RLS

La base de datos utiliza Row Level Security para control de acceso granular:

-- Ejemplo de política RLS
CREATE POLICY "Users can view their company budgets"
ON budgets FOR SELECT
USING (
  company_id = get_company_id_from_clerk(
    (current_setting('request.jwt.claims')::json->>'sub')
  )
);

Edge Functions

Funciones serverless en Deno para lógica de negocio:

• Procesamiento de pagos

• Envío de emails

• Integraciones externas

• IA para generación de contenido

Storage

Buckets para almacenamiento de archivos:

Bucket	Público	Uso
company-logos	✅	Logos de empresas
budget-images	✅	Imágenes en presupuestos
knowledge-files	❌	Archivos de conocimiento

Flujo de Datos

Creación de Presupuesto

┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
│  Usuario │────>│  Editor  │────>│ Liveblocks│────>│  Yjs Doc │
│  Input   │     │  TipTap  │     │  Room     │     │  State   │
└──────────┘     └──────────┘     └──────────┘     └──────────┘
                                                         │
                                                         ▼
┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
│  Toast   │<────│  React   │<────│ Supabase │<────│  Save    │
│  Success │     │  Query   │     │  INSERT  │     │  Trigger │
└──────────┘     └──────────┘     └──────────┘     └──────────┘

Generación con IA

┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
│  Prompt  │────>│   Edge   │────>│  Gemini  │────>│ Response │
│  Usuario │     │ Function │     │   API    │     │  Stream  │
└──────────┘     └──────────┘     └──────────┘     └──────────┘
                                                         │
                                                         ▼
┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
│  Editor  │<────│  TipTap  │<────│  Parse   │<────│ Markdown │
│  Update  │     │  Commands│     │  Content │     │  to HTML │
└──────────┘     └──────────┘     └──────────┘     └──────────┘

Autenticación

┌──────────┐     ┌──────────┐     ┌──────────┐
│  Login   │────>│  Clerk   │────>│   JWT    │
│  Form    │     │  Auth    │     │  Token   │
└──────────┘     └──────────┘     └──────────┘
                                       │
                      ┌────────────────┼────────────────┐
                      ▼                ▼                ▼
               ┌──────────┐     ┌──────────┐     ┌──────────┐
               │ Supabase │     │Liveblocks│     │  React   │
               │  Client  │     │   Auth   │     │  Context │
               └──────────┘     └──────────┘     └──────────┘

Patrones de Diseño

Component Composition

// Ejemplo de composición de componentes
<BudgetEditor>
  <EditorToolbar />
  <EditorCanvas>
    <TipTapEditor />
    <CollaboratorCursors />
  </EditorCanvas>
  <BlocksPanel />
</BudgetEditor>

Custom Hooks

// Hooks para lógica reutilizable
const { company, isLoading } = useCompany();
const { hasPermission } = usePermissions();
const { uploadImage } = useImageUpload();
const { subscription } = useSubscription();

Context Providers

// Providers anidados para estado global
<ClerkProvider>
  <QueryClientProvider>
    <AuthProvider>
      <ThemeProvider>
        <App />
      </ThemeProvider>
    </AuthProvider>
  </QueryClientProvider>
</ClerkProvider>

Seguridad

Capas de Seguridad

1. Clerk: Autenticación y gestión de sesiones

2. JWT Validation: Verificación en cada request

3. RLS Policies: Control de acceso a nivel de fila

4. Edge Functions: Validación de permisos en backend

Flujo de Autorización

Request → Clerk JWT → Supabase Client → RLS Policy → Data
                ↓
         Edge Function
                ↓
         Permission Check
                ↓
         Business Logic

Performance

Optimizaciones Frontend

• Code Splitting: Lazy loading de rutas

• React Query: Cache inteligente

• Debounce: Reducción de requests

• Virtual Lists: Para listas largas

Optimizaciones Backend

• Connection Pooling: Supabase Pooler

• Indexes: En columnas frecuentes

• Edge Functions: Cold start optimization

• CDN: Para assets estáticos

Escalabilidad

Horizontal

• Supabase escala automáticamente

• Edge Functions son serverless

• Liveblocks maneja concurrencia

Vertical

• Upgrade de plan Supabase

• Conexiones de database

• Storage limits

Monitoreo

Logs

• Supabase Dashboard: Logs de DB y Auth

• Edge Function Logs: Errores y performance

• Browser Console: Errores de cliente

Métricas

• Request latency

• Error rates

• Active users

• Storage usage