DDD Serverless Monorepo

Serverless Framework v4 monorepo siguiendo principios de Domain-Driven Design (DDD) con arquitectura de microservicios usando Serverless Compose.

🚀 Inicio Rápido

Prerrequisitos

Node.js >= 22.0.0 (LTS)
pnpm >= 9.0.0
AWS CLI configurado con credenciales
Serverless Framework v4

🔐 Configuración de AWS

1. Instalar AWS CLI

# macOS
brew install awscli

# Windows
choco install awscli

# Linux
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip && sudo ./aws/install

2. Configurar Credenciales AWS

# Opción 1: Configuración interactiva
aws configure

# Opción 2: Variables de entorno
export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key
export AWS_DEFAULT_REGION=us-east-1

# Opción 3: Perfil específico
aws configure --profile serverless
export AWS_PROFILE=serverless

3. Verificar Configuración

# Verificar credenciales
aws sts get-caller-identity

# Verificar región
aws configure get region

📦 Instalación y Deploy

# 1. Instalar dependencias del monorepo
pnpm install

# 2. Instalar dependencias de la layer (manual)
cd Layers/Dependencies/nodejs
pnpm install --prod
cd ../../..

# 3. Desplegar todo con Serverless Compose
pnpm run deploy

📁 Estructura del Proyecto

/
├── serverless.compose.ts         # 🆕 Orchestrador Serverless Compose
├── Layers/                       # 🆕 Lambda Layers compartidas
│   └── Dependencies/             # Layer de dependencias npm
│       ├── serverless.ts         # Configuración de la layer
│       ├── package.json          # Config del proyecto layer
│       └── nodejs/               # Contenido de la layer
│           ├── package.json      # Dependencies de producción
│           └── node_modules/     # Instaladas manualmente
├── Apps/                         # Aplicaciones Serverless
│   └── Backoffice/              # Servicio Backoffice
│       ├── Functions/           # Lambda handlers
│       │   ├── Api/             # Endpoints HTTP
│       │   └── Status/          # Health checks
│       ├── package.json         # Dependencies del servicio
│       └── serverless.ts        # Configuración Serverless
├── Src/                         # Código fuente compartido (DDD)
│   └── Contexts/                # Shared kernel DDD
│       ├── Backoffice/          # Contexto Backoffice
│       └── Shared/              # Kernel compartido
└── Tests/                       # Tests organizados por contexto

🛠️ Comandos Disponibles

🚀 Deploy con Serverless Compose

# Deploy completo (layers + servicios) - RECOMENDADO
pnpm run deploy
# Equivale a: serverless --config=serverless.compose.ts deploy

# Deploy por etapas
pnpm run deploy -- --stage staging
pnpm run deploy -- --stage prod

# Información de todos los servicios
serverless --config=serverless.compose.ts info

# Eliminar todo el stack
serverless --config=serverless.compose.ts remove

🔧 Gestión de Layers (Independiente)

# Deploy solo layers
pnpm run deploy:layers
# Equivale a: cd Layers/Dependencies && pnpm run deploy

# Gestión manual de dependencies
cd Layers/Dependencies/nodejs
pnpm install --prod  # Agregar/actualizar dependencies
cd .. && pnpm run deploy  # Deploy de la layer

🏗️ Desarrollo Local

# Desarrollo con live reload (Serverless v4)
pnpm run dev:backoffice
# Equivale a: cd Apps/Backoffice && serverless dev

# Desarrollo offline (simulación local)
cd Apps/Backoffice && pnpm run offline

📊 Monitoreo y Debug

# Ver información de un servicio específico
cd Apps/Backoffice && serverless info

# Ver logs de una función
cd Apps/Backoffice && serverless logs -f productsList

# Invocar función remotamente
cd Apps/Backoffice && serverless invoke -f health

# Invocar función localmente
cd Apps/Backoffice && serverless invoke local -f health

🏗️ Arquitectura

Domain-Driven Design (DDD)

Bounded Contexts: Cada contexto en Contexts/ es autónomo
Aggregate Roots: Entidades principales que mantienen consistencia
Value Objects: Objetos inmutables que encapsulan lógica de dominio
Repository Pattern: Abstracción de acceso a datos
CQRS: Separación de comandos (escritura) y queries (lectura)

Serverless Framework v4 + Compose

🎼 Serverless Compose: Orchestración de múltiples servicios
🔗 Cross-Stack References: Referencias dinámicas entre servicios
⚡ Lambda Layers: Dependencias npm separadas del código de negocio
🚀 HTTP API v2: Más rápido y económico que REST API
📦 ESBuild: Bundling nativo para mejor rendimiento
💪 ARM64: Arquitectura optimizada para costo y rendimiento
🔄 Node.js 22.x: Runtime más reciente y optimizado

🏗️ Arquitectura de Layers

Dependencies Layer (Independiente)

Layers/Dependencies/
├── serverless.ts              # Config independiente
├── package.json               # Project config
└── nodejs/                    # Layer content
    ├── package.json           # 🎯 Solo dependencies de prod
    └── node_modules/          # Instaladas manualmente

Beneficios:

🔄 Deploy Independiente: Layer se despliega por separado
⚡ Funciones Ligeras: Solo contienen lógica de negocio
🚀 Deployments Rápidos: Solo se actualiza cuando cambian dependencies
🔗 Referencias Dinámicas: Cross-stack references automáticas
📦 Shared Dependencies: Todas las funciones comparten la misma layer

📦 Gestión de Dependencias con pnpm

Workspace Configuration

El proyecto usa pnpm workspaces para gestión eficiente de dependencias:

# pnpm-workspace.yaml
packages:
  - 'Apps/*'
  - 'Src'

Comandos pnpm Útiles

# Instalar dependencia en workspace específico
pnpm add inversify --filter backoffice-service

# Instalar dependencia en root
pnpm add -w typescript

# Ejecutar script en todos los workspaces
pnpm -r run build

# Ejecutar script en workspace específico
pnpm --filter backoffice-service run deploy

🧪 Testing

# Ejecutar todos los tests
pnpm run test

# Tests con coverage
pnpm run test:coverage

# Tests en modo watch
pnpm run test:watch

🔧 Configuración de Entornos

🎯 Stages con Serverless Compose

# Desarrollo (por defecto)
pnpm run deploy
# serverless --config=serverless.compose.ts deploy

# Staging
pnpm run deploy -- --stage staging

# Producción
pnpm run deploy -- --stage prod

🔐 Variables de Entorno y Secretos

# Variables por stage (desde cualquier servicio)
cd Apps/Backoffice
serverless param set --name DATABASE_URL --value "postgresql://..." --stage prod
serverless param set --name JWT_SECRET --value "your-secret" --stage prod
serverless param set --name API_KEY --value "external-api-key" --stage prod

# Listar parámetros
serverless param list --stage prod

# Variables de entorno locales (.env)
cp .env.example .env  # Crear archivo local (no commitear)

🌍 Configuración Multi-Región

# Deploy en región específica
pnpm run deploy -- --region eu-west-1 --stage prod

# Deploy multi-región
pnpm run deploy -- --region us-east-1 --stage prod
pnpm run deploy -- --region eu-west-1 --stage prod

🚨 Troubleshooting

Problemas Comunes

1. Error de Credenciales AWS

# Verificar configuración
aws sts get-caller-identity
aws configure list

# Reconfigurar si es necesario
aws configure

2. Error de Cross-Stack Reference

# Asegurar que las layers se desplegaron primero
cd Layers/Dependencies && pnpm run deploy
cd ../.. && pnpm run deploy

3. Error de Dependencies Layer

# Reinstalar dependencies en la layer
cd Layers/Dependencies/nodejs
rm -rf node_modules pnpm-lock.yaml
pnpm install --prod
cd .. && pnpm run deploy

4. Limpiar y Redesplegar

# Limpiar todo
serverless --config=serverless.compose.ts remove
pnpm run clean

# Redesplegar desde cero
pnpm run deploy

🎯 Workflow de Desarrollo

1. Agregar Nueva Dependencia

# 1. Agregar a layer
cd Layers/Dependencies/nodejs
# Editar package.json - agregar en "dependencies"
pnpm install --prod

# 2. Deploy de la layer
cd .. && pnpm run deploy

# 3. Las funciones automáticamente usan la nueva versión

2. Crear Nueva Función

# 1. Crear handler
mkdir -p Apps/Backoffice/Functions/Api/NewEndpoint
# Crear handler.ts y container.ts

# 2. Agregar a serverless.ts
# Las layers y memorySize se heredan automáticamente del provider

# 3. Deploy
pnpm run deploy

3. Deploy a Producción

# 1. Deploy layers
cd Layers/Dependencies && pnpm run deploy -- --stage prod

# 2. Deploy servicios
cd ../.. && pnpm run deploy -- --stage prod

📚 Recursos Adicionales

🤝 Contribución

Fork del repositorio
Crear feature branch: git checkout -b feature/nueva-funcionalidad
Commit cambios: git commit -am 'Agregar nueva funcionalidad'
Push a la branch: git push origin feature/nueva-funcionalidad
Crear Pull Request

📄 Licencia

Este proyecto está bajo la licencia MIT. Ver LICENSE para más detalles.

Name		Name	Last commit message	Last commit date
Apps/Backoffice		Apps/Backoffice
Layers/Dependencies		Layers/Dependencies
Src/Contexts		Src/Contexts
.env.example		.env.example
.gitignore		.gitignore
AGENTS.md		AGENTS.md
README.md		README.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
serverless.compose.ts		serverless.compose.ts
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation