Saltar al contenido principal

Resumen de Implementación

Esta sección describe las decisiones arquitectónicas, elecciones tecnológicas y prácticas de desarrollo que guían el desarrollo de la plataforma Percus.

Filosofía​

Percus está construido con estos principios fundamentales:

  • Calidad Primero: Alta cobertura de pruebas, linting estricto, revisiones de código
  • Diseño Orientado al Dominio: La lógica de negocio impulsa la arquitectura
  • Serverless Primero: Enfoque en entrega de valor, no gestión de infraestructura
  • Seguridad por Diseño: Autenticación, encriptación y registro de auditoría desde el día uno
  • Mejora Progresiva: Empezar simple, agregar complejidad cuando sea necesario

Stack Tecnológico​

Backend​

Runtime y Lenguaje:

  • AWS Lambda con .NET 10 (C#)
  • Arquitectura serverless para escalamiento automático y optimización de costos
  • .NET 10 elegido por mejor rendimiento en arranque en frío (~850ms-1s)

¿Por qué AWS Lambda + .NET?

  • Cero gestión de infraestructura
  • Escalamiento automático (de 0 a miles de ejecuciones concurrentes)
  • Pago solo por uso real
  • .NET proporciona tipado fuerte, herramientas maduras y excelente rendimiento
  • Soporte nativo de async/await para operaciones I/O escalables

Base de Datos:

  • Amazon Aurora Serverless v2 con PostgreSQL 15
  • Auto-escala de 0.5 a 128 ACU según la carga
  • Despliegue Multi-AZ para alta disponibilidad
  • Respaldos automatizados y recuperación point-in-time

¿Por qué PostgreSQL en lugar de MySQL?

  • Soporte superior de JSON (tipo JSONB con indexación)
  • Búsqueda de texto completo incorporada
  • Tipos array y compuestos
  • Mejor soporte con Entity Framework Core
  • Características de consulta más avanzadas (CTEs, funciones de ventana)

ORM:

  • Entity Framework Core
  • Consultas type-safe con LINQ
  • Migraciones automatizadas para evolución de esquema
  • Seguimiento de cambios y patrón unit of work

Almacenamiento:

  • Amazon S3 para plantillas, assets y videos generados
  • CloudFront CDN para entrega global de contenido
  • URLs firmadas para acceso seguro a contenido privado

API:

  • API Gateway (REST API)
  • Throttling, monitoreo y caché incorporados
  • Integración con patrón Lambda proxy

Frontend​

Framework:

  • Next.js 15 (App Router) con TypeScript
  • Server-side rendering (SSR) para mejor SEO y rendimiento
  • Generación estática (SSG) para páginas cacheables
  • Desplegado en Vercel para deployment sin configuración

Estilos:

  • Tailwind CSS para desarrollo rápido de UI
  • Sistema de diseño personalizado con paleta de colores definida
  • Enfoque responsive-first

Gestión de Estado:

  • TanStack Query (React Query) para estado del servidor
  • Zustand para estado del cliente
  • Caché automático, refetch y actualizaciones optimistas

Formularios y Validación:

  • React Hook Form para formularios eficientes
  • Zod para validación de esquemas
  • Datos de formulario type-safe con TypeScript

Patrones Arquitectónicos​

Diseño Orientado al Dominio (DDD)​

Organizamos el sistema alrededor de dominios de negocio, no capas técnicas.

Contextos Delimitados:

La plataforma está dividida en 4 contextos delimitados independientes:

  1. Contexto de Identidad y Acceso

    • Organizaciones, usuarios, roles, permisos
    • Autenticación y autorización

  2. Contexto de Gestión de Campañas

    • Proyectos (campañas de marketing)
    • Plantillas (estructuras de video con versionado)

  3. Contexto de Integración

    • Credenciales de API
    • Configuraciones de webhooks
    • Configuración de entrega por email

  4. Contexto de Analítica

    • Eventos de generación de videos
    • Seguimiento de engagement (vistas, completados)

Cada contexto tiene su propio:

  • Modelo de dominio (entidades, value objects, agregados)
  • Reglas de negocio e invariantes
  • Contexto de base de datos (Entity Framework)
  • Función Lambda (microservicio)

¿Por qué DDD?

  • Alinea el código con el lenguaje de negocio
  • Límites claros reducen el acoplamiento
  • Más fácil de entender, probar y mantener
  • Los miembros del equipo pueden trabajar independientemente en diferentes contextos

Arquitectura Limpia​

Seguimos el principio de inversión de dependencias con capas claras:

┌─────────────────────────────────┐
│      Capa API (Lambda)          │  ← HTTP, JSON, DTOs
├─────────────────────────────────┤
│   Capa Aplicación (Casos Uso)  │  ← Orquestación, validación
├─────────────────────────────────┤
│    Capa Dominio (Entidades)    │  ← Lógica negocio, invariantes
├─────────────────────────────────┤
│  Infraestructura (EF, S3, etc.) │  ← Persistencia, servicios externos
└─────────────────────────────────┘

Responsabilidades de Capa:

Capa Dominio:

  • Entidades con reglas de negocio
  • Value objects para validación
  • Agregados que hacen cumplir invariantes
  • Eventos de dominio para comunicación
  • Sin dependencias de otras capas

Capa Aplicación:

  • Casos de uso (uno por acción de usuario)
  • Servicios de dominio (lógica de negocio compleja)
  • Verificaciones de autorización
  • Coordinación de transacciones

Capa Infraestructura:

  • DbContexts de Entity Framework
  • Repositorios (acceso a datos)
  • Cliente S3 (almacenamiento de archivos)
  • Clientes de API externas

Capa API:

  • Handlers de función Lambda
  • DTOs de request/response
  • Validación de entrada
  • Manejo de errores y logging

Beneficios:

  • Testeable (dominio sin dependencias)
  • Flexible (cambiar infraestructura sin tocar dominio)
  • Mantenible (clara separación de responsabilidades)

Arquitectura de Microservicios​

Cada contexto delimitado se despliega como una función Lambda independiente:

  • Servicio de Identidad: Autenticación y gestión de usuarios
  • Servicio de Campañas: Proyectos y plantillas
  • Servicio de Integración: Credenciales API y webhooks
  • Servicio de Analítica: Seguimiento de eventos y métricas

Comunicación:

  • Síncrona: Llamadas API directas (cuando es necesario)
  • Asíncrona: Eventos de dominio (preferido para cross-context)

¿Por qué Microservicios?

  • Despliegue y escalamiento independientes
  • Autonomía del equipo (cada equipo posee un servicio)
  • Flexibilidad tecnológica (puede usar diferentes lenguajes si es necesario)
  • Aislamiento de fallos (falla de un servicio no tumba todo el sistema)

Prácticas de Desarrollo​

Desarrollo Dirigido por Pruebas (TDD)​

Escribimos pruebas antes de la implementación.

Requisitos de Cobertura:

  • General: 90% mínimo
  • Capa dominio: >95% (lógica de negocio es crítica)
  • Capa aplicación: >90%
  • Capa infraestructura: >85%
  • Capa API: >90%
  • Frontend: >90%

Tipos de Pruebas:

Pruebas Unitarias (Rápidas, Aisladas):

  • Entidades y value objects de dominio
  • Casos de uso con dependencias simuladas
  • Funciones puras y utilidades

Pruebas de Integración (Base de Datos, Servicios Externos):

  • Consultas de repositorio (usando Testcontainers para PostgreSQL real)
  • Endpoints de API (usando WebApplicationFactory)
  • Flujos de usuario end-to-end (usando Playwright)

¿Por qué Alta Cobertura?

  • Confianza en refactorización
  • Documentación de comportamiento
  • Detección temprana de regresiones
  • Fuerza mejor diseño (código testeable es usualmente mejor código)

Desarrollo Dominio-Primero​

Orden de Implementación (Estricto):

  1. Capa Dominio (Pruebas → Implementación → Cobertura >95% → Lint limpio)
  2. Capa Aplicación (Pruebas → Implementación → Cobertura >90% → Lint limpio)
  3. Capa Infraestructura (Pruebas → Implementación → Cobertura >85% → Lint limpio)
  4. Capa API (Pruebas → Implementación → Cobertura >90% → Lint limpio)
  5. Frontend (Pruebas → Implementación → Cobertura >90% → Lint limpio)

Regla: No pasar a la siguiente capa hasta que la actual esté 100% completa.

¿Por qué Dominio-Primero?

  • La lógica de negocio es el código más valioso
  • Si el dominio está mal, todo lo demás está mal
  • Probar dominio es más fácil (sin dependencias)
  • Proporciona base sólida para otras capas

Estándares de Calidad de Código​

Linting (Forzado en CI/CD):

  • Backend: dotnet format --verify-no-changes
  • Frontend: ESLint + Prettier
  • Sin merge si el linting falla

Análisis Estático:

  • Backend: StyleCop, ReSharper
  • Frontend: TypeScript modo estricto
  • Seguridad: Snyk, Dependabot para escaneo de vulnerabilidades

Revisiones de Código:

  • Todo código debe revisarse antes del merge
  • Verificaciones automatizadas (pruebas, lint, cobertura) deben pasar
  • Al menos una aprobación requerida

Compuertas de Calidad (Bloquean Merge Si):

  • ❌ Cobertura de pruebas cae por debajo del 90%
  • ❌ Cualquier falla de prueba
  • ❌ Errores de lint
  • ❌ Errores de TypeScript
  • ❌ Vulnerabilidades de seguridad (altas/críticas)

Decisiones Arquitectónicas Clave​

Autenticación: Google Workspace SSO​

Decisión: Usar Google OAuth para toda autenticación (sin contraseñas).

Razonamiento:

  • Sin carga de gestión de contraseñas (sin hashing, flujos de reset, riesgo de brechas)
  • Conveniente para usuarios empresariales (mayoría tiene cuentas Google)
  • Google maneja MFA y auditorías de seguridad
  • Gratis para implementación OAuth básica

Implementación:

  • NextAuth.js en frontend
  • Tokens JWT para autorización de API
  • Creación de usuario en primer login

Base de Datos: Aurora Serverless PostgreSQL​

Decisión: Usar Aurora Serverless v2 con PostgreSQL 15.

Razonamiento:

  • Auto-escalamiento: Escala capacidad de cómputo automáticamente (0.5-128 ACU)
  • Costo-efectivo: Pago solo por capacidad usada
  • Alta disponibilidad: Multi-AZ con failover automático
  • Beneficios PostgreSQL: Mejor soporte JSON, búsqueda texto completo, características avanzadas

vs DynamoDB:

  • Modelo relacional se ajusta mejor a nuestro dominio
  • Consultas complejas son más simples (JOINs, GROUP BY)
  • Transacciones a través de múltiples tablas

vs PostgreSQL Auto-hospedado:

  • Sin gestión de servidor
  • Escalamiento automático
  • Respaldos y HA incorporados

ORM: Entity Framework Core​

Decisión: Usar Entity Framework Core para todo acceso a base de datos.

Razonamiento:

  • Type safety: Modelos C# mapeados a tablas de base de datos
  • Migraciones: Control de versiones para esquema de base de datos
  • Consultas LINQ: Fuertemente tipadas, verificadas en tiempo de compilación
  • Seguimiento de cambios: Detección automática de dirty y actualizaciones

Estrategia de Migración:

  • Desarrolladores crean migraciones localmente: dotnet ef migrations add
  • Migraciones almacenadas en Git
  • GitHub Actions ejecuta migraciones durante despliegue
  • Lambda de Migración de respaldo para ejecuciones manuales

¿Por qué no SQL crudo o Dapper?

  • EF proporciona más productividad (menos código repetitivo)
  • Las migraciones son críticas para evolución de esquema
  • Trade-off: Ligeramente más lento, pero vale la pena por mantenibilidad

Despliegue: Serverless + IaC​

Decisión: Usar Terraform para infraestructura como código.

Razonamiento:

  • Reproducible: Misma infraestructura en staging y producción
  • Control de versiones: Cambios rastreados en Git
  • Multi-cloud: Puede migrar fuera de AWS si es necesario
  • Modular: Módulos reutilizables para patrones comunes

CI/CD:

  • GitHub Actions para toda automatización
  • Push a develop → Despliegue a staging
  • Push a main → Despliegue a producción
  • Pruebas automatizadas, linting, verificaciones de cobertura

Monitoreo: CloudWatch + Sentry​

Decisión: Usar CloudWatch para infraestructura, Sentry para errores de aplicación.

CloudWatch:

  • Logs, métricas, alarmas de Lambda
  • Logs de requests de API Gateway
  • Rendimiento de consultas de base de datos

Sentry:

  • Seguimiento de errores de frontend
  • Monitoreo de excepciones de backend
  • Seguimiento de releases, source maps

Alertas:

  • Slack/Email cuando los errores aumentan
  • PagerDuty para problemas críticos (producción caída)

Arquitectura de Seguridad​

Defensa en Profundidad​

Capa 1: Protección Edge

  • CloudFront + AWS WAF
  • Protección DDoS, rate limiting
  • Restricciones geográficas (si es necesario)

Capa 2: API Gateway

  • Throttling de requests (100 req/min por usuario)
  • Validación de API key
  • Límites de tamaño de request/response

Capa 3: Aplicación

  • Validación de token JWT
  • Control de acceso basado en roles (RBAC)
  • Aislamiento de datos a nivel de organización

Capa 4: Datos

  • Encriptación en reposo (AWS KMS)
  • Encriptación en tránsito (TLS 1.3)
  • Credenciales de base de datos en AWS Secrets Manager

Capa 5: Auditoría

  • Todas las acciones críticas registradas
  • Seguimiento de actividad de usuario
  • Retención de log de auditoría: 1 año

Preparación para Cumplimiento​

GDPR:

  • Exportación de datos bajo solicitud
  • Eliminación de datos bajo solicitud (soft delete + anonimizar)
  • Seguimiento de consentimiento
  • Derecho al olvido

SOC 2:

  • Controles de acceso (RBAC)
  • Registro de auditoría
  • Encriptación (reposo + tránsito)
  • Plan de respuesta a incidentes

Objetivos de Rendimiento​

Tiempo de Respuesta API:

  • Menos de 500ms para percentil 95
  • Menos de 1s para percentil 99

Carga de Página Frontend:

  • Menos de 2 segundos para dashboard
  • Menos de 3 segundos para detalles de proyecto

Consultas de Base de Datos:

  • Menos de 100ms para consultas simples
  • Menos de 500ms para analítica compleja

Generación de Video:

  • Menos de 10 segundos para plantilla típica
  • Menos de 30 segundos para plantillas complejas

Disponibilidad:

  • 99.9% SLA de uptime
  • Despliegue Multi-AZ para redundancia

Optimización de Costos​

Beneficios Serverless:

  • Pago solo por uso real (sin servidores inactivos)
  • Escalamiento automático (sin sobre-aprovisionamiento)
  • Sin overhead operacional

Costos Estimados (Mensuales):

  • MVP (100 usuarios): ~$200
  • Escala (1,000 usuarios): ~$800
  • Empresa (10,000 usuarios): ~$3,000

Controles de Costo:

  • Concurrencia reservada en Lambdas críticos
  • Aurora auto-pause cuando está inactivo (desarrollo)
  • Políticas de ciclo de vida S3 (archivar videos antiguos)
  • Caché de CloudFront (reducir requests a origen)

Estrategia de Escalabilidad​

Escalamiento Horizontal:

  • Lambda: Automático, hasta límites de cuenta
  • Aurora: Agregar read replicas para cargas read-heavy
  • S3: Almacenamiento ilimitado

Escalamiento Vertical:

  • Lambda: Aumentar asignación de memoria (también aumenta CPU)
  • Aurora: Escalar capacidad ACU (0.5 → 128 ACU)

Caché:

  • CloudFront: Cachear assets estáticos (plantillas, imágenes)
  • API Gateway: Cachear respuestas GET (1-5 minutos)
  • Aplicación: Redis/ElastiCache si es necesario (Fase 2+)

Optimización de Base de Datos:

  • Índices en claves foráneas y campos de búsqueda
  • Particionado para tablas grandes (eventos de analítica)
  • Vistas materializadas para analítica compleja

Mejoras Futuras​

Fase 2 (6-12 meses):

  • Notificaciones en tiempo real (WebSockets)
  • Analítica avanzada (pruebas A/B, mapas de calor)
  • Marketplace de plantillas
  • Soporte multi-idioma (Español, Portugués)

Fase 3 (12-24 meses):

  • Características impulsadas por IA (auto-generar scripts)
  • App móvil (iOS/Android)
  • Integraciones avanzadas (Salesforce, HubSpot)
  • Opción white-label para clientes enterprise

Resumen​

Puntos Clave:

✅ Arquitectura Serverless: Lambda + Aurora para escalamiento automático y optimización de costos

✅ Diseño Orientado al Dominio: 4 contextos delimitados con límites claros

✅ Arquitectura Limpia: Capas Dominio → Aplicación → Infraestructura → API

✅ Desarrollo Test-First: Requisito de cobertura 90%, enfoque dominio-primero

✅ Estándares de Calidad: Linting forzado, revisiones de código requeridas, compuertas de calidad automatizadas

✅ Seguridad por Diseño: OAuth, encriptación, RBAC, registro de auditoría desde el día uno

✅ Stack Moderno: .NET 10, Next.js 15, PostgreSQL 15, TypeScript

Esta arquitectura nos permite:

  • Construir rápidamente (serverless, herramientas modernas)
  • Escalar eficientemente (auto-escalamiento, microservicios)
  • Mantener calidad (pruebas, linting, revisiones)
  • Entregar valor (enfoque en dominio, no infraestructura)

Siguiente: Ver documentación de planificación detallada en el repositorio percus-backoffice (carpeta .plan/).