Multi-Tenant SaaS Platform | TypeScript

Plataforma backend SaaS multi-tenant

Descripción general del proyecto

Un backend robusto y listo para producción API creado con NestJS, diseñado para aplicaciones de software como servicio de nivel empresarial.

Empezando

Guía rápida para configurar y ejecutar la plataforma.

Descripción general de la arquitectura

Ciclo de vida de solicitud visual

graph TD
    A[Client Request] --> B[Global Guards: JWT & RBAC]
    B --> C[Global Interceptors: Logging/Transform]
    C --> D[Feature Module: Controller]
    D --> E[Service Layer: Business Logic]
    E --> F[Repository Layer: Prisma ORM]
    F --> G[(PostgreSQL: Row Level Isolation)]
    
    subgraph Async Operations
        E --> H[BullMQ / Redis]
        H --> I[Worker: Email/Billing]
    end

Impacto de la ingeniería e interés nacional

Patrones de arquitectura central

• Arquitectura limpia: Separación clara entre capas de presentación, negocios y datos.
• Inyección de dependencia: Sistema NestJS DI para código comprobable y mantenible
• Organización del módulo: Módulos basados en funciones para escalabilidad
• Patrón de repositorio: Acceso a datos resumidos a través de Prisma
• Validación DTO: Validación y transformación integral de entradas
• Manejo de errores: Manejo de errores centralizado con códigos de estado HTTP adecuados

Stack tecnológico

• Idioma: TypeScript 5.0+
• Tiempo de ejecución: Node.js 18+
• Marco: NestJS 10+ (marco backend de nivel empresarial)
• Base de datos: PostgreSQL 15+ (cumplimiento de ACID, seguridad a nivel de fila)
• ORM: Prisma 5+ (acceso a base de datos con seguridad de escritura)
• Autenticación: JWT con Passport.js (autenticación sin estado)
• Autorización: Control de acceso basado en roles (RBAC)
• Sistema de cola: Redis + BullMQ (procesamiento de trabajos en segundo plano)
• Validación: validador de clase + transformador de clase
• Contenedorización: Docker 24+ con compilaciones de varias etapas
• Pruebas: Jest 29+ con Supertest para pruebas E2E
• Registro: Registro estructurado de Winston

Características

Autenticación y autorización

• Registro de usuario e inicio de sesión
• Autenticación basada en JWT
• Control de acceso basado en roles (Administrador/Usuario)
• Hash de contraseña con bcrypt

Multi-tenant

• Aislamiento de datos basado en la organización
• Multitenant a nivel de fila
• Los usuarios pertenecen a organizaciones.

Módulos CRUD

• Usuarios: Administrar usuarios de la organización
• Organizaciones: Gestión sólo de administrador
• Proyectos: Proyectos específicos de la organización
• Tareas: Tareas específicas del proyecto con asignación

Todos los módulos incluyen:

• Paginación
• Filtrado
• Clasificación
• Validación de entrada
• Manejo de errores

Procesamiento en segundo plano

• Simulación de envío de correo electrónico asincrónico (registrado en la consola)
• Reintentos de trabajo y manejo de fallas (simplificado)
• Registro

Integración externa

• Procesamiento de pagos de Stripe simulado
• Endpoint de webhook para eventos de pago

Pruebas

• Pruebas unitarias para servicios.
• Prueba básica e2e para autenticación.

Variables de entorno

Crear un .env archivo en el directorio raíz:

# Database
DATABASE_URL="postgresql://username:password@localhost:5432/portfolio_saas?schema=public"

# JWT
JWT_SECRET="your-secret-key"
JWT_EXPIRES_IN="1h"

# Redis
REDIS_URL="redis://localhost:6379"

# Email (simulation)
EMAIL_HOST="smtp.gmail.com"
EMAIL_PORT=587
EMAIL_USER="[email protected]"
EMAIL_PASS="your-password"

# Payment (Stripe sandbox)
STRIPE_SECRET_KEY="sk_test_..."
STRIPE_WEBHOOK_SECRET="whsec_..."

Cómo ejecutar localmente

Requisitos previos

• Node.js (v18+)
• PostgreSQL
• Redis
• Ventana acoplable (opcional)

Configuración local

1. Clonar el repositorio

   git clone <repository-url>
   cd portfolio-saas-backend
   

2. Instalar dependencias

   npm install
   

3. Configurar base de datos

   # Start PostgreSQL and Redis locally or via Docker
   docker run --name postgres -e POSTGRES_USER=username -e POSTGRES_PASSWORD=password -e POSTGRES_DB=portfolio_saas -p 5432:5432 -d postgres:15
   docker run --name redis -p 6379:6379 -d redis:7-alpine
   

4. Configurar el entorno

   cp.env.example.env
   # Edit.env with your values
   

5. Ejecutar migraciones de bases de datos

   npm run prisma:migrate
   npm run prisma:generate
   

6. Iniciar la aplicación

   npm run start:dev
   

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

Configuración de Docker

1. Compile y ejecute con Docker Compose

   docker-compose up --build
   

Esto iniciará la aplicación, PostgreSQL y Redis.

API Documentación

Autenticación

Regístrate

POST /auth/register
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "password123",
  "firstName": "John",
  "lastName": "Doe",
  "organizationId": "org-id"
}

Iniciar sesión

POST /auth/login
Content-Type: application/json

{
  "username": "[email protected]",
  "password": "password123"
}

Respuesta:

{
  "access_token": "jwt-token-here"
}

Organizaciones (solo administrador)

Crear organización

POST /organizations
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "My Company"
}

Listar organizaciones

GET /organizations?page=1&limit=10&name=search
Authorization: Bearer <token>

Proyectos

Crear proyecto

POST /projects
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Website Redesign",
  "description": "Redesign company website"
}

Listar proyectos

GET /projects?page=1&limit=10&name=search
Authorization: Bearer <token>

Tareas

Crear tarea

POST /tasks
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "Design homepage",
  "description": "Create new homepage design",
  "projectId": "project-id"
}

Listar tareas

GET /tasks?page=1&limit=10&status=pending
Authorization: Bearer <token>

Pagos

Crear intención de pago

POST /payments/create-intent
Content-Type: application/json

{
  "amount": 1000,
  "currency": "usd"
}

gancho web

POST /payments/webhook
Content-Type: application/json
Stripe-Signature: <signature>

{
  "type": "payment_intent.succeeded",
  "data": {... }
}

Decisiones de diseño

Multi-tenant

• Multitenant basado en filas: Cada tabla incluye organizationId para aislamiento de datos
• Ventajas: Simple, escalable, sin duplicación de esquemas
• Contras: Requiere un filtrado de consultas cuidadoso

Autenticación

• JWT con pasaporte: Estándar industrial, sin estado
• Basado en roles: Roles simples de ADMIN/USUARIO
• Hash de contraseña: bcrypt por seguridad

Trabajos en segundo plano

• BullMQ con Redis: Sistema de cola confiable
• Simulación de correo electrónico: Registros en lugar de envíos reales para demostración

Integración de pagos

• Raya simulada: Simula el procesamiento de pagos reales
• Manejo de webhooks: Procesamiento básico de eventos

Base de datos

• PostgreSQL: Robusto, compatible con ACID
• prisma: ORM con seguridad de tipos, migraciones, gestión de esquemas

Arquitectura

• Módulos NestJS: Organización basada en características
• inyección de dependencia: Código comprobable y mantenible
• Validación: validador de clase para validación de entrada

Nota técnica sobre aislamiento de datos

La plataforma implementa una estrategia de base de datos compartida y esquema compartido. El aislamiento de datos se aplica a nivel de servicio mediante filtros de OrganizationId obligatorios en cada consulta. Este enfoque equilibra la rentabilidad con la escalabilidad requerida para las empresas emergentes de alto crecimiento.

Pruebas

# Unit tests
npm run test

# E2E tests
npm run test:e2e

# Coverage
npm run test:cov

Implementación

Esta aplicación está en contenedores con Docker y se puede implementar en cualquier plataforma en la nube que admita contenedores Docker (AWS ECS, Google Cloud Run, Azure Container Instances, etc.).

Para producción:

1. Utilice configuraciones específicas del entorno
2. Configurar migraciones de bases de datos adecuadas
3. Configurar el monitoreo y el registro
4. Implementar limitación de velocidad
5. Agregar versiones de API
6. Configurar pipeline de CI/CD

Contribuyendo

1. Siga el estilo de código existente
2. Escribir pruebas para nuevas funciones.
3. Actualizar documentación
4. Utilice mensajes de confirmación significativos

Autor

Patrick Araujo - Ingeniero Informático Para ver otros proyectos y detalles de el portafolio, visite: https://pklavc.com/projects/

Este proyecto demuestra capacidades avanzadas de desarrollo backend para aplicaciones empresariales SaaS.