Billing & Reconciliation Engine

Motor de facturación automatizado diseñado para manejar el ciclo de vida completo de las suscripciones (SaaS), gestión de pagos asíncronos y conciliación financiera utilizando una arquitectura orientada a eventos.

Construido con NestJS, PostgreSQL y Redis, este motor es altamente escalable y tolerante a fallos, preparado para procesar miles de transacciones mediante Webhooks (Stripe) y el patrón Outbox.

Características

• Autenticación JWT y guards de seguridad.
• Simulación y procesamiento de Webhooks (Stripe) con validación de firmas.
• Arquitectura basada en Patrón Outbox para garantizar que ningún evento de pago se pierda en caso de fallo.
• Base de datos relacional PostgreSQL con TypeORM para garantizar transacciones ACID.
• Redis + BullMQ para encolamiento asíncrono de eventos y mitigación de picos de tráfico.
• Frontend de simulación incluido para pruebas fáciles y visualización del ciclo de pagos.

Guía de Configuración Local

Sigue estos pasos paso a paso para ejecutar el entorno en tu máquina:

1. Prerrequisitos

• Node.js (v18 o superior recomendado)
• Docker y Docker Compose (para levantar las bases de datos)

2. Variables de Entorno

Clona el proyecto y crea tu archivo .env utilizando la plantilla.

cp .env.example .env

(Asegúrate de que los valores coincidan con tu base de datos y tus claves de Stripe si vas a probar en vivo. Para uso local, los valores por defecto del .env.example son suficientes para interactuar con Docker).

3. Levantar Infraestructura (Base de datos y Caché)

Asegúrate de tener Docker Desktop abierto y ejecuta:

docker-compose up -d postgres redis

Esto levantará PostgreSQL en el puerto 5433 y Redis en el puerto 6379.

4. Instalar Dependencias

npm install

5. Ejecutar Migraciones de Base de Datos

TypeORM se encargará de crear las tablas de la base de datos (suscripciones, usuarios, registros de pago y eventos outbox):

npm run migration:run

6. Iniciar la Aplicación Backend

npm run start:dev

La API estará disponible en http://localhost:3000.

7. Iniciar el Frontend de Simulación (Opcional)

Para probar todo el flujo visualmente, abre una nueva terminal y sirve la carpeta Frontend:

npx http-server ./Frontend -p 8080

Accede desde tu navegador a http://127.0.0.1:8080 y sigue los pasos en pantalla.