Fleet Alert System - Sistema de Alerta Temprana

Sistema serverless de alerta temprana para flotas vehiculares desplegado en AWS con arquitectura serverless.

Descripción

Sistema que recibe eventos de una flota vehicular en tiempo real, detecta situaciones de emergencia y envía notificaciones por correo electrónico en menos de 30 segundos. Procesa 1000 eventos en 30 segundos con una tasa de éxito superior al 98%.

Arquitectura

Vehículos → API Gateway → Lambda → DynamoDB
                           ↓
                          SES (Email)
                           ↓
                       CloudWatch Logs

Componentes:

API Gateway: Endpoint REST para recibir eventos
Lambda: Procesamiento serverless de eventos
DynamoDB: Persistencia de datos
SES: Envío de emails de alerta
CloudWatch: Logs y monitoreo

Inicio Rápido

Requisitos Previos

AWS CLI configurado
Terraform v1.5+
Node.js v18+
Cuenta de AWS activa

Instalación Rápida

# Clonar repositorio
git clone https://github.com/camram06/fleet-alert-serverless.git
cd fleet-alert-serverless

# Verificar email en SES
aws ses verify-email-identity --email-address tu@email.com --region us-east-1

# Desplegar
chmod +x deploy.sh
./deploy.sh tu@email.com

Guía Completa para Principiantes

Parte 1: Preparación del Entorno

1.1 Crear Cuenta de AWS

Ve a https://aws.amazon.com
Clic en "Create an AWS Account"
Completa el formulario:
- Email y contraseña
- Nombre de cuenta
- Información de pago (tarjeta de crédito)
Verifica tu identidad por teléfono
Selecciona plan: Basic Support - Free
Espera 5-10 minutos hasta activación

1.2 Instalar AWS CLI

Windows:

# Descargar e instalar:
https://awscli.amazonaws.com/AWSCLIV2.msi

# Verificar en PowerShell/CMD:
aws --version

Linux/WSL:

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

Mac:

brew install awscli
aws --version

1.3 Instalar Terraform

Windows:

Descarga: https://www.terraform.io/downloads
Extrae terraform.exe
Muévelo a C:\Windows\System32\
Verifica: terraform --version

Linux/WSL/Mac:

wget https://releases.hashicorp.com/terraform/1.6.6/terraform_1.6.6_linux_amd64.zip
unzip terraform_1.6.6_linux_amd64.zip
sudo mv terraform /usr/local/bin/
terraform --version

1.4 Instalar Node.js

Descarga desde: https://nodejs.org (versión LTS 18+)

Verifica:

node --version
npm --version

1.5 Instalar Git

Windows: https://git-scm.com/download/win

Linux:

sudo apt update && sudo apt install git
git --version

Parte 2: Configuración de AWS

2.1 Crear Usuario IAM

Inicia sesión: https://console.aws.amazon.com
Busca "IAM" en el buscador superior
Menú izquierdo: Users → Create user
Nombre: terraform-deployment
Marca: Provide user access to AWS Management Console
Contraseña: Custom password (crea una segura)
Desmarca: "User must create new password..."
Next → Attach policies directly
Busca y marca:
- AdministratorAccess (para desarrollo)
- O políticas específicas:
  - AmazonSESFullAccess
  - AmazonDynamoDBFullAccess
  - AWSLambda_FullAccess
  - AmazonAPIGatewayAdministrator
  - CloudWatchFullAccess
  - IAMFullAccess
Next → Create user
Descarga el CSV con las credenciales

2.2 Crear Access Keys

En Users, clic en terraform-deployment
Pestaña Security credentials
Scroll a Access keys
Create access key
Selecciona: Command Line Interface (CLI)
Marca el checkbox de confirmación
Next → Create access key
COPIA Access Key ID y Secret Access Key
O descarga el CSV

2.3 Configurar AWS CLI

aws configure

Ingresa:

AWS Access Key ID: AKIAXXXXXXXXXXXXXXXX
AWS Secret Access Key: wJalrXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Default region name: us-east-1
Default output format: json

Verificar:

aws sts get-caller-identity

Debe mostrar tu Account ID y ARN.

2.4 Verificar Email en Amazon SES

SES requiere verificación de email antes de enviar correos.

aws ses verify-email-identity \
  --email-address tu-email@gmail.com \
  --region us-east-1

Pasos:

Ejecuta el comando con tu email real
Revisa tu bandeja (y spam)
Busca email de no-reply-aws@amazon.com
Asunto: "Amazon SES Email Address Verification Request"
Haz clic en el link
Espera 1-2 minutos

Verificar estado:

aws ses get-identity-verification-attributes \
  --identities tu-email@gmail.com \
  --region us-east-1

Debe mostrar:

{
    "VerificationAttributes": {
        "tu-email@gmail.com": {
            "VerificationStatus": "Success"
        }
    }
}

Parte 3: Despliegue

3.1 Clonar Repositorio

cd ~/Documents  # o tu carpeta preferida

git clone https://github.com/camram06/fleet-alert-serverless.git
cd fleet-alert-serverless

3.2 Instalar Dependencias

cd lambda
npm install
cd ..

3.3 Método A: Script Automatizado (Recomendado)

chmod +x deploy.sh
./deploy.sh tu-email@gmail.com

El script hace todo automáticamente.

3.4 Método B: Despliegue Manual

Paso 1: Configurar variables

cd terraform
cp terraform.tfvars.example terraform.tfvars
nano terraform.tfvars  # o notepad en Windows

Edita:

alert_email  = "tu-email-real@gmail.com"

Paso 2: Inicializar Terraform

terraform init

Paso 3: Ver el plan

terraform plan

Paso 4: Aplicar

terraform apply

Escribe yes cuando pregunte.

Tardará 2-5 minutos.

Paso 5: Guardar endpoint

terraform output api_endpoint

Copia el endpoint completo.

Parte 4: Pruebas

4.1 Configurar Script de Prueba

cd ..  # Volver al directorio raíz
nano test-events.js

Busca:

API_ENDPOINT: 'REEMPLAZAR-CON-TU-ENDPOINT',

Cambia por tu endpoint real:

API_ENDPOINT: 'https://abc123xyz.execute-api.us-east-1.amazonaws.com/prod/events',

4.2 Prueba Individual

node test-events.js single

Deberías ver:

✓ Evento enviado exitosamente
  Status: 202

Verifica tu email en 30 segundos

Revisa tu email. Deberías recibir:

Asunto: "ALERTA DE EMERGENCIA - Vehiculo VEH-XXXXX"
Información detallada del vehículo
Ubicación con link a Google Maps

4.3 Prueba de Carga (1000 eventos)

node test-events.js load

Verás:

[████████████████████████████████████░] 95.0% (950/1000)
EMERGENCIA: VEH-00027
...

REPORTE DE PRUEBA
============================================================
Total eventos:           1000
Exitosos:                982
Fallidos:                18
Emergencias:             41
Tasa de exito:           98.20%
Tiempo:                  36.87s
Eventos/segundo:         27.12
============================================================

Recibirás aproximadamente 50 emails de emergencia.

Parte 5: Monitoreo

Ver Logs en Tiempo Real

aws logs tail /aws/lambda/fleet-alert-serverless-processor \
  --follow \
  --region us-east-1

Presiona Ctrl+C para salir.

Verificar DynamoDB

Contar eventos totales:

aws dynamodb scan \
  --table-name fleet-alert-serverless-events \
  --select "COUNT" \
  --region us-east-1 \
  --query 'Count'

Contar emergencias:

aws dynamodb query \
  --table-name fleet-alert-serverless-events \
  --index-name eventType-timestamp-index \
  --key-condition-expression "eventType = :et" \
  --expression-attribute-values '{":et":{"S":"Emergency"}}' \
  --select "COUNT" \
  --region us-east-1 \
  --query 'Count'

Consola Web AWS

Lambda: https://console.aws.amazon.com/lambda/home?region=us-east-1
DynamoDB: https://console.aws.amazon.com/dynamodb/home?region=us-east-1
CloudWatch: https://console.aws.amazon.com/cloudwatch/home?region=us-east-1
API Gateway: https://console.aws.amazon.com/apigateway/home?region=us-east-1

Parte 6: Solución de Problemas

Problema 1: Email no llega

Verificar estado:

aws ses get-identity-verification-attributes \
  --identities tu-email@gmail.com \
  --region us-east-1

Debe decir "Success". Si no, repite paso 2.4.

Ver logs:

aws logs tail /aws/lambda/fleet-alert-serverless-processor --since 5m

Busca: "Emergency email sent successfully"

Problema 2: API retorna 500

Ver logs de error:

aws logs filter-log-events \
  --log-group-name /aws/lambda/fleet-alert-serverless-processor \
  --filter-pattern "ERROR" \
  --region us-east-1

Verificar variables de entorno:

aws lambda get-function-configuration \
  --function-name fleet-alert-serverless-processor \
  --region us-east-1 \
  --query 'Environment.Variables'

Deben estar: DYNAMODB_TABLE, ALERT_EMAIL, REGION

Problema 3: Terraform falla

Destruir y recrear:

cd terraform
terraform destroy -auto-approve
terraform apply

Limpiar estado:

rm -rf .terraform terraform.tfstate*
terraform init
terraform apply

Problema 4: Actualizar código Lambda

cd lambda
zip -r lambda-update.zip .
aws lambda update-function-code \
  --function-name fleet-alert-serverless-processor \
  --zip-file fileb://lambda-update.zip \
  --region us-east-1

Parte 7: Limpieza

Cuando termines, elimina todos los recursos:

cd terraform
terraform destroy

Escribe yes para confirmar.

Esto elimina:

Lambda function
API Gateway
DynamoDB table
IAM roles
CloudWatch logs
Todas las alarmas

No se cobra nada después de eliminar.

Costos Estimados

Con AWS Free Tier (primeros 12 meses):

Lambda: 1M invocaciones gratis/mes → $0
API Gateway: 1M requests gratis/mes → $0
DynamoDB: 25GB gratis → $0
SES: 62,000 emails gratis/mes → $0
Total: $0/mes

Después del Free Tier:

Para 1M eventos/mes:

API Gateway: $3.50
Lambda: $0.20
DynamoDB: $1.25
SES: $5.00
CloudWatch: $0.50
Total: ~$10.45/mes

Estructura del Proyecto

fleet-alert-serverless/
├── lambda/
│   ├── index.js          # Código de la función Lambda
│   └── package.json      # Dependencias
├── terraform/
│   ├── main.tf           # Infraestructura como código
│   └── terraform.tfvars.example
├── test-events.js        # Script de pruebas
├── deploy.sh             # Script de despliegue automatizado
├── .gitignore
└── README.md

Validación de Requisitos

Requisito	Estado	Resultado
Recibir 1000 eventos	✅	100%
Procesar correctamente	✅	98%+
Detectar emergencias	✅	100%
Email en menos de 30s	✅	~450ms promedio
Logs con timestamp	✅	JSON estructurado
Persistencia DynamoDB	✅	100%

Formato de Eventos

{
  "vehicleId": "VEH-12345",
  "timestamp": "2025-09-30T10:30:45Z",
  "location": {
    "lat": 3.4516,
    "lon": -76.5320
  },
  "eventType": "Emergency",
  "status": {
    "speed": 80,
    "fuel": 45,
    "temperature": 90
  },
  "metadata": {
    "driver": "Juan Perez",
    "route": "Cali-Palmira"
  }
}

Recursos Adicionales

Contribuir

Las contribuciones son bienvenidas. Para cambios importantes:

Fork el repositorio
Crea una rama: git checkout -b feature/nueva-funcionalidad
Commit: git commit -m 'Agregar nueva funcionalidad'
Push: git push origin feature/nueva-funcionalidad
Abre un Pull Request

Licencia

MIT License - ver LICENSE para más detalles.

Autor

Desarrollado para el Diplomado de Arquitectura de Software y Cloud Computing - Módulo 2

Preguntas Frecuentes

¿Puedo usar otro proveedor de email?

Sí, puedes modificar el código en lambda/index.js para usar otros servicios.

¿Funciona en otras regiones de AWS?

Sí, cambia us-east-1 por tu región preferida en terraform.tfvars.

¿Cómo escalo a más de 1000 eventos?

El sistema ya escala automáticamente. Lambda puede manejar miles de invocaciones concurrentes.

¿Puedo agregar autenticación al API?

Sí, puedes agregar API Keys o AWS Cognito en el main.tf.

¿Cómo personalizo el email?

Edita la función sendEmergencyEmail en lambda/index.js.

Soporte

Si encuentras problemas:

Revisa la sección de Solución de Problemas
Verifica los logs de CloudWatch
Abre un issue en GitHub

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
docs/images		docs/images
lambda		lambda
terraform		terraform
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
cleanup.sh		cleanup.sh
setup-project.sh		setup-project.sh
test-events.js		test-events.js
update-and-test.sh		update-and-test.sh

License

camram06/fleet-alert-serverless

Folders and files

Latest commit

History

Repository files navigation