Arquitectura

CentralForms es una plataforma centralizada de formularios dinámicos que permite desacoplar la lógica de formularios de sitios web, portales, landings y aplicaciones consumidoras.

El sistema permite:

• Definir formularios desde backend.
• Exponer formularios mediante API REST.
• Consumir formularios desde múltiples aplicaciones externas.
• Renderizar formularios dinámicamente mediante SDK JavaScript.
• Procesar submissions de forma centralizada.
• Persistir envíos para auditoría y trazabilidad.
• Ejecutar destinos configurables como email, webhook y futuras integraciones.

Arquitectura conceptual

CentralForms sigue una arquitectura desacoplada. Las aplicaciones consumidoras interactúan con un frontend o SDK, la API central gestiona seguridad y orquestación, las capas internas procesan y persisten la información, y los datos se envían a destinos configurables.

Flujo de alto nivel

1. Aplicación consumidora solicita formulario mediante GET.
2. API valida seguridad y retorna estructura + CSRF.
3. Usuario envía datos mediante POST.
4. API valida, procesa y persiste.
5. Se ejecutan destinos configurados: email, webhook u otros.

Arquitectura por capas

La arquitectura está organizada por responsabilidades para separar presentación, lógica de aplicación, dominio e infraestructura.

Capa	Componente	Responsabilidad
Capa externa	Aplicaciones consumidoras	Sitios web, portales, aplicaciones internas y landings que consumen CentralForms.
Capa frontend	Embed JS / SDK	Integra el formulario en el frontend, renderiza campos dinámicos y ejecuta solicitudes GET/POST.
Capa API	Controllers	Recibe solicitudes HTTP y expone endpoints públicos y administrativos.
Capa API	Controllers y configuración HTTP	Recibe requests, aplica headers, rate limiting y delega validaciones de negocio/seguridad a servicios de aplicación.
Capa de aplicación	Form Service	Obtiene definiciones de formularios y coordina la lógica funcional.
Capa de aplicación	Submission Service	Procesa y almacena los envíos.
Capa de aplicación	Security Service	Centraliza validaciones de seguridad y reglas de acceso.
Capa de aplicación	CSRF Service	Genera, persiste, valida e invalida tokens CSRF.
Capa de dominio	Entidades	Define entidades como Consumer, Form, FormField, Submission, FormDestination, CsrfToken e IntegrationLog.
Capa de infraestructura	Base de datos	Persiste formularios, envíos, tokens, destinos y logs.
Capa de infraestructura	Email Service	Envía correos y notificaciones.
Capa de infraestructura	Webhook Service	Ejecuta integraciones HTTP con sistemas externos.

Proyectos de la solución

La solución está separada en cuatro proyectos principales:

CentralForms.Api
CentralForms.Application
CentralForms.Domain
CentralForms.Infrastructure

Proyecto	Responsabilidad
CentralForms.Api	Controllers, Swagger, CORS, Rate Limiting, Health Check y archivos estáticos del SDK.
CentralForms.Application	DTOs, interfaces, casos de uso y lógica de aplicación.
CentralForms.Domain	Entidades del dominio.
CentralForms.Infrastructure	EF Core, repositorios, servicios externos, SMTP, HTTP webhooks e integration logs.

Componentes principales

Componente	Responsabilidad	Observaciones
CentralForms API	Expone endpoints REST y orquesta validaciones.	Incluye Swagger/OpenAPI y Health Check.
SDK / Embed JS	Consume la API y renderiza formularios dinámicos.	Soporta validación visual, callbacks y renovación CSRF.
Servicios de aplicación	Implementan lógica de negocio y procesamiento.	No exponen entidades directamente.
Servicios de seguridad	Validan API Key, Origin, CSRF y reglas de acceso.	Se ejecutan antes de la lógica de negocio.
Base de datos	Persiste formularios, campos, submissions, tokens y logs.	SQL Server.
Email Service	Envía notificaciones SMTP.	Se ejecuta como destino configurado.
Webhook Service	Envía submissions a sistemas externos.	Usa FormDestination.Value como URL destino.
Destination Dispatcher	Ejecuta destinos en background con scope DI independiente.	Evita capturar el DbContext original del request HTTP.

Responsabilidad por capa

Responsabilidad	API	Application	Domain	Infrastructure
Recibir solicitudes HTTP	Sí	No	No	No
Exponer endpoints REST	Sí	No	No	No
Documentar Swagger/OpenAPI	Sí	No	No	No
Validar contrato de entrada	Sí	Sí	No	No
Aplicar reglas de negocio	No	Sí	Sí	No
Definir entidades	No	No	Sí	No
Persistir datos	No	No	No	Sí
Enviar correos	No	No	No	Sí
Ejecutar webhooks	No	No	No	Sí
Registrar integration logs	No	Sí	No	Sí
Servir SDK JS	Sí	No	No	No

Decisiones arquitectónicas

Decisión	Descripción	Impacto
Seguridad por capas	API Key, Origin y CSRF se validan antes de la lógica de negocio.	Reduce exposición de formularios públicos.
Separación por capas	Las responsabilidades se separan entre API, aplicación, dominio e infraestructura.	Facilita mantenimiento, pruebas y evolución.
Multi-tenant lógico	Un sistema soporta múltiples consumers mediante consumerCode.	Permite reutilización para clientes, marcas y aplicaciones.
Procesamiento asíncrono	Email y Webhook se ejecutan en modo Fire & Forget.	No bloquean la respuesta al usuario.
Uso de DTOs	No se exponen entidades directamente.	Permite controlar el contrato API.
CSRF stateful	El token CSRF se genera en GET, se persiste y se valida en POST.	Reduce riesgo de reutilización y falsificación de envíos.
Persistencia antes de integración	La submission se guarda antes de ejecutar email/webhook.	Garantiza trazabilidad aun si una integración falla.
Integration Logs	Cada destino genera trazabilidad de ejecución.	Permite diagnóstico operativo de email y webhook.

Regla de persistencia

El resultado inmediato del POST depende de la validación y persistencia de la Submission, no del éxito de email o webhook.

Límites de la arquitectura

CentralForms centraliza la definición, exposición, validación, persistencia y despacho de formularios. No reemplaza sistemas propietarios de clientes ni plataformas externas de CRM, ERP o automatización.

Quedan fuera del alcance base de esta arquitectura:

• Admin Panel completo para gestión visual de formularios.
• Autenticación administrativa con usuarios, roles y permisos.
• Reintentos automáticos avanzados para integraciones fallidas.
• Dead-letter queue.
• Motor avanzado de plantillas.
• Procesamiento sincrónico de email o webhook.
• Orquestación compleja de flujos externos.
• Gestión de campañas o automatizaciones comerciales.

Flujo de validación de seguridad

Todas las solicitudes pasan por validaciones de seguridad antes de acceder a la lógica de negocio.

Orden de validación

1. Validar API Key.
2. Validar Origin cuando el header viene informado.
3. Validar CSRF, solo en POST.
4. Validar datos del formulario.
5. Procesar lógica de negocio.

Regla crítica

Si una validación falla, el flujo se detiene inmediatamente. No se procesa lógica de negocio ni se persiste una submission.

Flujo GET - Obtención de formulario

El flujo GET obtiene la definición de un formulario dinámico junto con un token CSRF para el envío posterior.

Objetivo

Obtener la estructura del formulario, sus campos configurados y un token CSRF válido para proteger el flujo POST.

Endpoint

GET /api/forms/{consumerCode}/{formCode}

Descripción del flujo

1. El usuario accede a una página que integra CentralForms.

2. El SDK o frontend realiza una solicitud GET al endpoint:

   /api/forms/{consumerCode}/{formCode}

3. La API recibe la solicitud y valida la API Key del consumidor.

4. La API valida que el Origin esté autorizado cuando el header viene informado.

5. Si las validaciones son correctas, la API solicita al servicio de aplicación la definición del formulario.

6. El servicio obtiene el formulario y sus campos desde la base de datos.

7. La API genera un token CSRF para proteger futuros envíos.

8. El token CSRF se almacena con estado activo.

9. La API responde al frontend con:

   • Definición del formulario.
   • Campos configurados.
   • Token CSRF.

10. El SDK o frontend renderiza el formulario dinámicamente al usuario.

Salida esperada

Elemento	Descripción
Definición del formulario	Título, descripción y metadatos del formulario.
Campos	Lista ordenada de campos con tipo, obligatoriedad, placeholder y opciones.
Token CSRF	Token stateful de un solo uso para validar el envío POST.

Posibles errores

Código	Error	Descripción
401	API Key inválida o ausente	La API Key no fue enviada o no coincide con el hash almacenado.
401	Consumer inactivo	En el código actual se maneja como acceso no autorizado.
403	Origin no permitido	El dominio de la aplicación consumidora no está autorizado cuando el header Origin viene informado.
404	Formulario no encontrado	El consumer o formulario solicitado no existe o no está disponible.
500	Error interno del servidor	Error inesperado durante consulta, validación o generación del token.

Notas importantes

• Todas las validaciones de seguridad se ejecutan antes de acceder a la lógica de negocio.
• Este flujo no registra submissions.
• La información retornada es de solo lectura.
• El token CSRF generado será utilizado en el flujo POST.
• La generación y almacenamiento del CSRF es el único cambio de estado de este flujo.
• Todas las comunicaciones deben realizarse sobre HTTPS en ambientes reales.

Flujo POST - Envío de submission

El flujo POST valida, procesa y almacena el envío de un formulario dinámico.

Objetivo

Validar la solicitud, persistir la submission y delegar la ejecución de destinos configurados como email o webhook.

Endpoint

POST /api/forms/{consumerCode}/{formCode}/submit

Descripción del flujo

1. El usuario completa el formulario y lo envía desde la interfaz.

2. El SDK o frontend realiza una solicitud POST al endpoint:

   /api/forms/{consumerCode}/{formCode}/submit

3. La solicitud incluye:

   • X-Api-Key
   • X-CSRF-Token
   • Origin
   • Content-Type: application/json

4. La API recibe la solicitud y valida la API Key del consumidor.

5. La API valida el Origin cuando el header viene informado para asegurar que proviene de un dominio autorizado.

6. La API valida el token CSRF, verificando:

   • Existencia.
   • Vigencia.
   • No reutilización.
   • Correspondencia con el consumer y formulario.

7. La API valida los campos enviados según las reglas definidas en el formulario:

   • Campos requeridos.
   • Formatos.
   • Tipos de datos.

8. Si las validaciones son correctas, la API envía los datos al servicio de aplicación para su procesamiento.

9. El servicio de aplicación persiste la Submission en la base de datos.

10. El sistema marca el token CSRF como utilizado.

11. El servicio de aplicación delega la ejecución de destinos al DestinationDispatcher.

12. El DestinationDispatcher ejecuta destinos configurados en background:

    • Email Service.
    • Webhook Service.

13. La API responde con estado exitoso:

    200 OK

14. El SDK o frontend muestra una confirmación al usuario.

Validaciones principales

Validación	Descripción
API Key	Verifica que el consumer esté autenticado.
Consumer activo	Verifica que el consumer pueda operar.
Origin	Verifica que el dominio esté autorizado cuando el header viene informado.
CSRF Token	Verifica existencia, vigencia, uso único y correspondencia con consumer/formulario.
Campos	Verifica requeridos, formatos y tipos de datos.

Posibles errores

Código	Error	Descripción
400	Campos inválidos o requeridos faltantes	Uno o más campos no cumplen las reglas del formulario.
401	API Key inválida o ausente	La API Key no fue enviada o no coincide con el hash almacenado.
401	Consumer inactivo	En el código actual se maneja como acceso no autorizado.
403	Origin no permitido	El dominio de la aplicación consumidora no está autorizado cuando el header Origin viene informado.
403	CSRF inválido, expirado o reutilizado	El token no existe, expiró, fue reutilizado o no corresponde al formulario/consumer.
404	Formulario no encontrado	El consumer o formulario solicitado no existe o no está disponible.
429	Rate limit superado	Se excedió el límite de solicitudes permitido para submit.
500	Error interno del servidor	Error inesperado durante validación, persistencia o procesamiento.

Notas importantes

• Todas las validaciones de seguridad se ejecutan antes de cualquier procesamiento de negocio.
• El token CSRF es obligatorio y debe haber sido generado previamente en el flujo GET.
• La submission se guarda antes de ejecutar integraciones externas.
• Los destinos Email y Webhook se ejecutan de forma asíncrona.
• Email y Webhook no bloquean la respuesta inmediata al usuario.
• Un 200 OK significa que la submission fue validada y persistida, no que las integraciones externas hayan finalizado correctamente.
• El resultado de email y webhook debe revisarse en IntegrationLogs.
• Todas las comunicaciones deben realizarse sobre HTTPS en ambientes reales.

Procesamiento, email, webhook y persistencia

El procesamiento de submissions prioriza persistencia y trazabilidad. Las integraciones externas se ejecutan de forma desacoplada para evitar que errores o latencias externas afecten la respuesta principal.

Flujo general de procesamiento

1. Validación completada.
2. Persistencia de submission.
3. Ejecución asíncrona de destinos.
4. Respuesta al cliente.

Persistencia

Aspecto	Descripción
Entidad principal	Submissions
Datos almacenados	Consumer, formulario, datos JSON, metadata y fecha de creación.
Regla	La submission se guarda antes de ejecutar integraciones externas.
Beneficio	Trazabilidad, auditoría y posibilidad de reprocesamiento futuro.

Email Service

Aspecto	Descripción
Propósito	Enviar notificaciones por correo electrónico basadas en el envío del formulario.
Configuración	Destinatarios, asunto, plantilla y variables dinámicas.
Ejecución	Asíncrona, no bloqueante.
Fallos	Se registran en IntegrationLogs y no afectan el 200 OK si la submission ya fue persistida.

Webhook Service

Aspecto	Descripción
Propósito	Enviar submissions a sistemas externos mediante HTTP.
Configuración	URL destino, método POST y headers personalizados si aplica.
Ejecución	Asíncrona, no bloqueante.
Casos de uso	CRM, ERP, automatizaciones, integraciones de clientes.

Manejo de errores de integraciones

Caso	Resultado
Submission persistida + email falla	POST puede responder 200 OK; el error queda en IntegrationLogs.
Submission persistida + webhook falla	POST puede responder 200 OK; el error queda en IntegrationLogs.
Fallo antes de persistir	POST no debe responder éxito.
Destino inválido	Se registra como Skipped o Failed según la validación.

Futuro recomendado

Agregar retry policy, dead-letter queue, monitoreo de fallos y reprocesamiento manual controlado.