Documentación Técnica Completa

Arquitectura, APIs, Esquemas de Base de Datos y Flujos de Desarrollo

Versión: 2.1.0 Security Level: Enterprise

Documentación Técnica Completa - Sistema de Gestión de Estados Financieros

Resumen Ejecutivo

Sistema profesional de gestión de estados financieros multicompañía construido con tecnología moderna, diseñado para contadores, PYMES y firmas de accounting. Arquitectura escalable con capacidades de análisis avanzado, reporting profesional y seguridad enterprise-grade.

Arquitectura del Sistema

Stack Tecnológico Principal

Diagrama de Arquitectura

        
   Frontend             Supabase             Netlify       
   React + Vite     PostgreSQL       CDN + Edge   
   TypeScript            Auth + RLS           Functions     
   Tailwind CSS          Realtime             Analytics     
        
                                                      
                                                      
        
   Usuario              Storage              Monitoring   
   Browser              S3 Bucket            Logs + Errors

Estructura del Proyecto

Estadosfinancieros/
 src/                    # Código fuente principal
    components/         # Componentes React reutilizables
    contexts/          # Contextos de React (Auth, Theme, etc.)
    hooks/             # Custom React Hooks
    lib/               # Librerías y utilities
    types/             # Definiciones TypeScript
    utils/             # Funciones utilitarias
    App.tsx            # Componente principal
    main.tsx           # Punto de entrada
 database/              # Scripts de base de datos
 scripts/               # Scripts de automatización
 public/               # Archivos estáticos
 supabase/              # Configuración Supabase
 docs/                  # Documentación adicional

Esquema de Base de Datos Completo

Tablas Principales (29 Tablas)

1. Gestión de Usuarios y Autenticación

2. Gestión de Empresas

3. Catálogos y Maestros

4. Datos Financieros

5. Reporting y Exportación

6. Integraciones ERP

7. Sistema y Logs

Relaciones Clave

Modelo de Seguridad

Row Level Security (RLS)

Todas las tablas tienen RLS habilitado con políticas específicas:

-- Ejemplo: Política para financial_entries
CREATE POLICY "Users can view own company entries" 
ON financial_entries FOR SELECT 
TO authenticated 
USING (
  company_id IN (
    SELECT company_id FROM user_companies 
    WHERE user_id = auth.uid()
  )
);

Políticas de Acceso

  1. Administradores: Acceso completo a todas las empresas
  2. Contadores: Acceso a empresas asignadas + todas las funcionalidades
  3. Usuarios Básicos: Acceso solo a su empresa + funcionalidades limitadas
  4. Solo Lectura: Usuarios con permisos de visualización únicamente

Encriptación y Protección

Configuración de Entornos

Variables de Entorno (.env.development)

# Supabase Configuration
VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_ANON_KEY=example-anon-key

# App Configuration  
VITE_APP_VERSION=1.0.0
VITE_ENVIRONMENT=development
VITE_DEBUG=true

# Feature Flags
VITE_ENABLE_ANALYTICS=false
VITE_ENABLE_PREMIUM_FEATURES=true

# External Services
VITE_BCV_API_URL=https://bcv-api.example.com
VITE_EXCHANGE_RATE_API_KEY=example-key-placeholder

Variables de Producción

# Production-specific
VITE_ENVIRONMENT=production
VITE_DEBUG=false
VITE_ENABLE_ANALYTICS=true

# Monitoring
VITE_SENTRY_DSN=your-sentry-dsn
VITE_LOGROCKET_ID=your-logrocket-id

Performance y Optimización

Optimizaciones de Base de Datos

Optimizaciones Frontend

Métricas de Performance

API e Integraciones

Supabase Client API

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

const supabase = createClient(
  import.meta.env.VITE_SUPABASE_URL,
  import.meta.env.VITE_SUPABASE_ANON_KEY
);

// Ejemplos de uso
const { data: entries } = await supabase
  .from('financial_entries')
  .select('*')
  .eq('company_id', companyId);

Endpoints Principales

  1. Autenticación: /auth/v1/*
  2. Datos Financieros: /rest/v1/financial_entries
  3. Reportes: /rest/v1/generated_reports
  4. Empresas: /rest/v1/companies
  5. Usuarios: /rest/v1/user_profiles

Webhooks y Integraciones

Motor de Sincronización ERP (Odoo)

El sistema utiliza una arquitectura de Proxy para evitar problemas de CORS:

  1. Frontend: Solicita sincronización a la Edge Function odoo-proxy.
  2. Edge Function: Actúa como puente, autentica con Odoo y extrae account.account y account.move.line.
  3. Mapeo Automático: Transforma los datos de Odoo (naturaleza, tipos) al esquema de HermesAI.
  4. Persistencia: Guarda los saldos finales en financial_entries.

Perfiles de Importación Personalizados

El sistema permite a los usuarios definir perfiles de importación (mapeos) para archivos CSV/Excel de cualquier sistema contable que no esté soportado nativamente.

Motor de Reporting

Plantillas de Reportes

-- Estructura de report_templates
CREATE TABLE report_templates (
  id UUID PRIMARY KEY,
  name VARCHAR(255),
  description TEXT,
  template_type VARCHAR(50), -- balance_sheet, income_statement, etc.
  template_config JSONB,     -- Configuración del reporte
  is_public BOOLEAN DEFAULT false,
  created_by UUID REFERENCES users(id),
  created_at TIMESTAMPTZ DEFAULT NOW()
);

Formatos de Exportación

Módulos Avanzados de Análisis

Simulador de Escenarios

Valoración de Empresas

Evaluación de Seguros

Seguridad y Compliance

Normativas Cumplidas

Medidas de Seguridad

  1. Encriptación: AES-256 para datos en reposo
  2. Backups: Diarios + retención 30 días
  3. Auditoría: Logs completos de todas las acciones
  4. 2FA: Autenticación de dos factores opcional
  5. IP Whitelisting: Para acceso administrativo

© 2025 HermesAI Financial Systems. Todos los derechos reservados.

Documentación generada automáticamente el 22/12/2025.